workspace { name "Gonec System C4 Model" description "Complete C4 model for the Gonec microservice-based logistics platform" properties { structurizr.groupSeparator "/" } !docs documentation !adrs decisions model { # People/actors logist = person "Logist" "Business user managing transport requests and bids" { tags "User" } carrier = person "Carrier" "Transportation service provider submitting bids" { tags "User" } systemAdmin = person "System Administrator" "DevOps engineer managing the platform" { tags "Admin" } # External Systems emailService = softwareSystem "Email Service" "External email delivery service" { tags "External" } pushService = softwareSystem "Push Notification Service" "External push notification service" { tags "External" } # Main Software System gonecSystem = softwareSystem "Gonec Logistics Platform" "Microservice-based transportation request and bid management system" { # Frontend Layer spa = container "React SPA" "Single Page Application with TypeScript and WebSockets for real-time updates" "React + TypeScript + WebSockets" { tags "Web Browser,Frontend" perspectives { "Security" "JWT token validation, CORS protection" "Performance" "Code splitting, lazy loading, service worker caching" "Scalability" "CDN distribution, static asset optimization" "Reliability" "Offline capability, error boundaries, retry mechanisms" } // Core Infrastructure Components authenticationLayer = component "Authentication Layer" "JWT-based authentication with Keycloak integration, role-based access control" "React Context, Zustand Store" { tags "Authentication,Security" } routingSystem = component "Routing System" "Client-side routing with protected routes and role-based navigation" "React Router" { tags "Navigation,Routing" } stateManagement = component "State Management" "Global and server state management with caching" "Zustand, TanStack Query" { tags "State,Cache" } // API Integration Layer spaApiClient = component "API Client" "HTTP client with authentication headers, error handling, and request/response interceptors" "Fetch API, Custom Service Layer" { tags "Integration,HTTP" } // Workflow Components workflowEngine = component "Workflow Engine Container" "Orchestrates SRFP workflow stages with role-based permissions and state transitions" "React Components, Container Pattern" { tags "Workflow" } // Data Management Components tableSystem = component "Data Table System" "Sortable, filterable tables with pagination and bulk operations" "TanStack Table, Mantine Components" { tags "DataDisplay,Table" } formSystem = component "Dynamic Form System" "JSON Schema-driven forms with validation and field access control" "React Hook Form, JSON Forms, Zod" { tags "Forms,Validation" } // UI Framework Components uiComponents = component "UI Component Library" "Design system with consistent styling and responsive components" "Mantine 8, TailwindCSS 4, Headless UI" { tags "UI,Components" } layoutSystem = component "Layout System" "Application shell with responsive navigation and status indicators" "React Components, CSS Grid/Flexbox" { tags "Layout,Responsive" } notificationSystem = component "Notification System" "Toast notifications for user feedback and system status" "React Hot Toast, Mantine Notifications" { tags "Notifications,Feedback" } // Specialized Features permissionSystem = component "Permission System" "Role-based UI element visibility and action authorization" "React Context, Custom Hooks" { tags "Security,Permissions" } // Component Relationships logist -> routingSystem "Uses web interface" carrier -> routingSystem "Submits bids and manages profile" routingSystem -> authenticationLayer "Validates access" authenticationLayer -> permissionSystem "Provides role context" workflowEngine -> permissionSystem "Checks role permissions" workflowEngine -> stateManagement "Manages workflow state" formSystem -> spaApiClient "Submits form data" tableSystem -> spaApiClient "Loads reference data" spaApiClient -> stateManagement "Updates cached state" stateManagement -> uiComponents "Provides reactive data" layoutSystem -> notificationSystem "Shows status updates" permissionSystem -> uiComponents "Controls element visibility" // All components use the UI system formSystem -> uiComponents "Renders form controls" tableSystem -> uiComponents "Renders table components" } # API Gateway Layer gateway = container "API Gateway" "Routes, authenticates and rate-limits requests with circuit breaker pattern" "Spring Cloud Gateway + WebFlux + Redis" { tags "Gateway" perspectives { "Security" "JWT validation, rate limiting, CORS, request/response filtering" "Performance" "Connection pooling, caching, load balancing" "Scalability" "Horizontal scaling, session-less design" "Reliability" "Circuit breaker, retry logic, health checks, graceful degradation" } } # Core Business Microservices transportRequestService = container "Transport Request Service" "Manages transport requests with multi-tenant support per warehouse" "Python + FastAPI + asyncio + Motor (MongoDB)" { tags "Microservice,Zeebe Worker,Business" perspectives { "Security" "JWT validation, tenant isolation, input validation, MongoDB authentication" "Performance" "Async I/O, connection pooling, MongoDB indexing, pagination" "Scalability" "Horizontal scaling, MongoDB sharding by warehouse_id" "Reliability" "Health checks, graceful shutdown, retry mechanisms, data validation" } } biddingService = container "Bidding Service" "Manages critical bid operations with ACID transactions and real-time updates" "Node.js + TypeScript + Express + WebSockets + Prisma" { tags "Microservice,Zeebe Worker,Business,Critical" perspectives { "Security" "JWT validation, SQL injection prevention, WebSocket authentication" "Performance" "Event loop optimization, connection pooling, WebSocket efficiency" "Scalability" "Horizontal scaling, read replicas, WebSocket clustering" "Reliability" "ACID transactions, circuit breaker, health monitoring, data consistency" } } referenceDataService = container "Reference Data Service" "Master data management with reactive data access" "Spring Boot + WebFlux + R2DBC + PostgreSQL" { tags "Microservice,Zeebe Worker,Reference" perspectives { "Security" "JWT validation, SQL injection prevention, data access control" "Performance" "Reactive streams, R2DBC connection pooling, caching" "Scalability" "Read replicas, horizontal scaling, cache distribution" "Reliability" "Circuit breaker, health checks, data consistency, backup strategy" } } notificationService = container "Notification Service" "High-performance notification delivery with goroutines" "Go + Gin + Redis + goroutines" { tags "Microservice,Infrastructure" perspectives { "Security" "JWT validation, rate limiting, secure channel communication" "Performance" "Goroutine concurrency, Redis pub/sub, connection reuse" "Scalability" "Horizontal scaling, Redis clustering, worker pools" "Reliability" "Retry mechanisms, dead letter queues, health monitoring" } } analyticsService = container "Analytics Service" "ETL pipeline for business intelligence and reporting" "Python + Apache Airflow + Pandas" { tags "Microservice,Analytics" perspectives { "Security" "Data encryption, access control, audit logging" "Performance" "Batch processing, parallel execution, data compression" "Scalability" "Distributed processing, resource allocation, queue management" "Reliability" "Data validation, retry logic, monitoring, backup procedures" } } # Data Storage Layer transportRequestsDB = container "Transport Requests Database" "Multi-tenant MongoDB with sharding by warehouse" "MongoDB" { tags "Database,NoSQL" perspectives { "Security" "Authentication, authorization, encryption at rest and in transit" "Performance" "Sharding, indexing, connection pooling, query optimization" "Scalability" "Horizontal sharding, replica sets, automatic balancing" "Reliability" "Replica sets, backup strategy, disaster recovery, monitoring" } } biddingDB = container "Bidding Database" "ACID-compliant PostgreSQL for critical transactions" "PostgreSQL" { tags "Database,SQL" perspectives { "Security" "Row-level security, SSL encryption, audit logging" "Performance" "Connection pooling, indexing, query optimization, partitioning" "Scalability" "Read replicas, connection pooling, horizontal partitioning" "Reliability" "ACID compliance, WAL replication, backup strategy, monitoring" } } referenceDB = container "Reference Data Database" "PostgreSQL for master data" "PostgreSQL" { tags "Database,SQL" perspectives { "Security" "Access control, encryption, audit trails" "Performance" "Caching, indexing, query optimization" "Scalability" "Read replicas, connection pooling" "Reliability" "Backup strategy, monitoring, data validation" } } analyticsDB = container "Analytics Database" "Time-series optimized for reporting" "ClickHouse" { tags "Database,Analytics" perspectives { "Security" "Access control, data masking, encryption" "Performance" "Columnar storage, compression, parallel processing" "Scalability" "Horizontal scaling, partitioning, distributed queries" "Reliability" "Replication, backup strategy, data integrity checks" } } # Caching Layer redisCache = container "Redis Cache" "Distributed cache and session storage" "Redis Cluster" { tags "Cache" perspectives { "Security" "Authentication, encryption, network security" "Performance" "In-memory storage, pipelining, clustering" "Scalability" "Redis Cluster, automatic sharding, horizontal scaling" "Reliability" "Persistence, replication, monitoring, failover" } } # Messaging Infrastructure kafka = container "Apache Kafka" "Distributed event streaming platform" "Apache Kafka" { tags "MessageBroker" perspectives { "Security" "SASL/SSL authentication, ACLs, encryption in transit" "Performance" "Partitioning, batching, compression, zero-copy" "Scalability" "Horizontal scaling, partition rebalancing, consumer groups" "Reliability" "Replication, at-least-once delivery, monitoring, backup" } } apicurioRegistry = container "Apicurio Schema Registry" "Schema evolution and validation" "Apicurio Registry" { tags "SchemaRegistry" perspectives { "Security" "Authentication, authorization, schema validation" "Performance" "Caching, efficient serialization, compression" "Scalability" "Horizontal scaling, distributed caching" "Reliability" "Backup strategy, version control, monitoring" } } # Process Orchestration Platform - Camunda 8 group "Camunda 8 Platform" { zeebeGateway = container "Zeebe Gateway" "gRPC gateway for Zeebe clusters" "Camunda 8 Zeebe Gateway" { tags "ProcessEngine,Gateway" perspectives { "Security" "TLS encryption, authentication, authorization" "Performance" "gRPC efficiency, connection pooling, load balancing" "Scalability" "Multiple gateway instances, horizontal scaling" "Reliability" "Health checks, failover, monitoring" } } zeebeBroker = container "Zeebe Broker" "Distributed workflow engine with event sourcing" "Camunda 8 Zeebe Broker" { tags "ProcessEngine,Core" perspectives { "Security" "Secure cluster communication, audit logging" "Performance" "Event sourcing, in-memory processing, efficient serialization" "Scalability" "Horizontal partitioning, distributed processing" "Reliability" "Event log persistence, replication, cluster management" } } connectors = container "Connectors" "Pre-built integration connectors" "Camunda 8 Connectors" { tags "ProcessEngine,Integration" perspectives { "Security" "Secure credential management, encrypted connections" "Performance" "Async processing, connection reuse, batching" "Scalability" "Horizontal scaling, worker distribution" "Reliability" "Retry mechanisms, error handling, monitoring" } } identityService = container "Identity Service" "Camunda identity and access management" "Camunda 8 Identity" { tags "ProcessEngine,Security" perspectives { "Security" "OAuth2/OIDC, RBAC, audit logging, password policies" "Performance" "Token caching, efficient authentication" "Scalability" "Horizontal scaling, session distribution" "Reliability" "High availability, backup procedures, monitoring" } } operate = container "Operate" "Process monitoring and operations" "Camunda 8 Operate" { tags "ProcessEngine,Monitoring" perspectives { "Security" "Role-based access, audit trails, secure communication" "Performance" "Efficient data queries, caching, pagination" "Scalability" "Horizontal scaling, load distribution" "Reliability" "Data consistency, backup strategy, monitoring" } } tasklist = container "Tasklist" "Human task management interface" "Camunda 8 Tasklist" { tags "ProcessEngine,UserInterface" perspectives { "Security" "Authentication, authorization, secure UI" "Performance" "Efficient task queries, caching, real-time updates" "Scalability" "Horizontal scaling, user load distribution" "Reliability" "Data consistency, offline capability, error handling" } } optimize = container "Optimize" "Process analytics and business intelligence" "Camunda 8 Optimize" { tags "ProcessEngine,Analytics" perspectives { "Security" "Data access control, audit logging, secure aggregation" "Performance" "Efficient aggregation, caching, parallel processing" "Scalability" "Horizontal scaling, distributed analytics" "Reliability" "Data consistency, backup strategy, monitoring" } } elasticsearch = container "Elasticsearch" "Process data storage and search" "Elasticsearch" { tags "Database,Search" perspectives { "Security" "Authentication, encryption, audit logging" "Performance" "Indexing optimization, query performance, caching" "Scalability" "Cluster scaling, shard distribution, replica management" "Reliability" "Data replication, backup strategy, monitoring" } } } # Identity Management keycloak = container "Keycloak" "Enterprise identity and access management" "Keycloak" { tags "Security,IdentityProvider" perspectives { "Security" "OAuth2/OIDC, SAML, MFA, password policies, audit logging" "Performance" "Token caching, session optimization, efficient authentication" "Scalability" "Horizontal scaling, session distribution, federation" "Reliability" "High availability, backup procedures, disaster recovery" } } # Observability Stack group "Observability Platform" { jaeger = container "Jaeger" "Distributed tracing system" "Jaeger" { tags "Observability,Tracing" perspectives { "Security" "Secure trace collection, access control" "Performance" "Efficient trace collection, sampling strategies" "Scalability" "Horizontal scaling, distributed storage" "Reliability" "Data retention, backup strategy, monitoring" } } prometheus = container "Prometheus" "Metrics collection and alerting" "Prometheus" { tags "Observability,Metrics" perspectives { "Security" "Secure metrics endpoint, access control" "Performance" "Efficient metrics collection, compression" "Scalability" "Federation, horizontal scaling, sharding" "Reliability" "Data retention, backup strategy, alerting" } } grafana = container "Grafana" "Metrics visualization and dashboards" "Grafana" { tags "Observability,Visualization" perspectives { "Security" "Authentication, authorization, audit logging" "Performance" "Efficient query processing, caching" "Scalability" "Horizontal scaling, dashboard distribution" "Reliability" "High availability, backup procedures" } } elkStack = container "ELK Stack" "Centralized logging and log analysis" "Elasticsearch + Logstash + Kibana" { tags "Observability,Logging" perspectives { "Security" "Log encryption, access control, audit trails" "Performance" "Log parsing optimization, indexing efficiency" "Scalability" "Horizontal scaling, log routing, storage tiering" "Reliability" "Data retention, backup strategy, monitoring" } } } } # Relationships # User interactions systemAdmin -> operate "Monitors processes" systemAdmin -> grafana "Views system metrics" // systemAdmin -> kibana "Analyzes logs" # Frontend to gateway spaApiClient -> gateway "Makes API calls" "HTTPS/REST + WebSockets" # Gateway routing gateway -> transportRequestService "Routes transport requests" "HTTPS/REST" gateway -> biddingService "Routes bid operations" "HTTPS/REST + WebSockets" gateway -> referenceDataService "Routes reference data queries" "HTTPS/REST" gateway -> notificationService "Routes notification requests" "HTTPS/REST" # Service to database relationships transportRequestService -> transportRequestsDB "Reads/writes transport requests" "MongoDB Protocol" biddingService -> biddingDB "Manages bid transactions" "PostgreSQL Protocol" referenceDataService -> referenceDB "Manages reference data" "R2DBC" notificationService -> redisCache "Caches notification state" "Redis Protocol" analyticsService -> analyticsDB "Stores analytical data" "ClickHouse Protocol" # Caching relationships gateway -> redisCache "Caches routes and sessions" "Redis Protocol" transportRequestService -> redisCache "Caches frequent queries" "Redis Protocol" referenceDataService -> redisCache "Caches reference data" "Redis Protocol" # Message broker relationships transportRequestService -> kafka "Publishes transport events" "Kafka Protocol" biddingService -> kafka "Publishes/consumes bid events" "Kafka Protocol" referenceDataService -> kafka "Publishes reference data changes" "Kafka Protocol" notificationService -> kafka "Consumes notification events" "Kafka Protocol" analyticsService -> kafka "Consumes all business events" "Kafka Protocol" # Schema registry relationships transportRequestService -> apicurioRegistry "Validates event schemas" "HTTP/REST" biddingService -> apicurioRegistry "Validates event schemas" "HTTP/REST" referenceDataService -> apicurioRegistry "Validates event schemas" "HTTP/REST" # Zeebe worker relationships transportRequestService -> zeebeGateway "Processes transport workflow tasks" "gRPC" biddingService -> zeebeGateway "Processes bidding workflow tasks" "gRPC" referenceDataService -> zeebeGateway "Processes data validation tasks" "gRPC" # Camunda 8 internal relationships zeebeGateway -> zeebeBroker "Forwards workflow commands" "gRPC" zeebeBroker -> elasticsearch "Exports process data" "Elasticsearch API" connectors -> zeebeGateway "Executes connector tasks" "gRPC" # Camunda 8 UI relationships operate -> elasticsearch "Queries process data" "Elasticsearch API" tasklist -> elasticsearch "Queries task data" "Elasticsearch API" optimize -> elasticsearch "Queries analytics data" "Elasticsearch API" # Authentication relationships authenticationLayer -> keycloak "Authenticates users" "OIDC" gateway -> keycloak "Validates JWT tokens" "OAuth2" transportRequestService -> keycloak "Validates JWT tokens" "OAuth2" biddingService -> keycloak "Validates JWT tokens" "OAuth2" referenceDataService -> keycloak "Validates JWT tokens" "OAuth2" notificationService -> keycloak "Validates JWT tokens" "OAuth2" # Camunda identity integration operate -> identityService "Authenticates via Camunda Identity" "OAuth2" tasklist -> identityService "Authenticates via Camunda Identity" "OAuth2" optimize -> identityService "Authenticates via Camunda Identity" "OAuth2" identityService -> keycloak "Federates with Keycloak" "OIDC" # External service relationships notificationService -> emailService "Sends email notifications" "SMTP/API" notificationService -> pushService "Sends push notifications" "HTTP/REST" # Observability relationships transportRequestService -> jaeger "Sends traces" "OpenTelemetry" biddingService -> jaeger "Sends traces" "OpenTelemetry" referenceDataService -> jaeger "Sends traces" "OpenTelemetry" notificationService -> jaeger "Sends traces" "OpenTelemetry" transportRequestService -> prometheus "Exposes metrics" "HTTP/Prometheus" biddingService -> prometheus "Exposes metrics" "HTTP/Prometheus" referenceDataService -> prometheus "Exposes metrics" "HTTP/Prometheus" notificationService -> prometheus "Exposes metrics" "HTTP/Prometheus" gateway -> prometheus "Exposes metrics" "HTTP/Prometheus" grafana -> prometheus "Queries metrics" "PromQL" transportRequestService -> elkStack "Sends logs" "Logback/HTTP" biddingService -> elkStack "Sends logs" "Winston/HTTP" referenceDataService -> elkStack "Sends logs" "Logback/HTTP" notificationService -> elkStack "Sends logs" "Zerolog/HTTP" gateway -> elkStack "Sends logs" "Logback/HTTP" } views { systemContext gonecSystem "SystemContext" { title "Gonec Logistics Platform - System Context" description "High-level view of the Gonec system and its users" include * autoLayout lr } container gonecSystem "Containers" { title "Gonec Logistics Platform - Container Diagram" description "Detailed view of the microservices architecture" include * autoLayout tb } component spa "FrontendComponents" { include * autolayout tb } # Dynamic views for key scenarios dynamic gonecSystem "TransportRequestFlow" "Transport Request Creation Flow" { title "Transport Request Creation Process" description "End-to-end flow of creating a transport request" logist -> spa "1. Creates transport request" spa -> gateway "2. POST /api/transport-requests" gateway -> transportRequestService "3. Route to transport service" transportRequestService -> transportRequestsDB "4. Store request" transportRequestService -> kafka "5. Publish RequestCreated event" transportRequestService -> zeebeGateway "6. Start transport process" notificationService -> kafka "7. Consume RequestCreated event" notificationService -> emailService "8. Send confirmation email" autoLayout lr } dynamic gonecSystem "BiddingFlow" "Bidding Process Flow" { title "Bid Submission and Selection Process" description "Critical path for bid management with ACID transactions" carrier -> spa "1. Views open requests" spa -> gateway "2. GET /api/transport-requests" gateway -> transportRequestService "3. Fetch open requests" carrier -> spa "4. Submits bid" spa -> gateway "5. POST /api/bids" gateway -> biddingService "6. Route to bidding service" biddingService -> biddingDB "7. Store bid (ACID transaction)" biddingService -> kafka "8. Publish BidSubmitted event" biddingService -> zeebeGateway "9. Continue bidding process" logist -> spa "10. Selects winning bid" spa -> gateway "11. PUT /api/bids/{id}/accept" gateway -> biddingService "12. Update bid status" biddingService -> biddingDB "13. ACID transaction: Update winner" biddingService -> kafka "14. Publish BidAccepted event" autoLayout lr } theme default styles { element "Microservice" { background #91F0AE shape Hexagon color #000000 } element "Business" { background #91F0AE shape Hexagon color #000000 } element "Critical" { background #FF6B6B shape Hexagon color #FFFFFF stroke #FF0000 } element "Infrastructure" { background #74B9FF shape Hexagon color #000000 } element "Reference" { background #FDCB6E shape Hexagon color #000000 } element "Analytics" { background #A29BFE shape Hexagon color #000000 } element "Zeebe Worker" { background #B4D8E7 stroke #0066CC strokeWidth 3 } element "ProcessEngine" { background #00D084 shape RoundedBox color #000000 } element "Core" { background #00D084 stroke #008F5B strokeWidth 3 } element "Gateway" { background #FFD93D shape Pipe color #000000 } element "Frontend" { background #6C5CE7 shape WebBrowser color #FFFFFF } element "Web Browser" { shape WebBrowser } element "Database" { background #636E72 shape Cylinder color #FFFFFF } element "NoSQL" { background #00B894 shape Cylinder color #FFFFFF } element "SQL" { background #0984E3 shape Cylinder color #FFFFFF } element "Cache" { background #E17055 shape Cylinder color #FFFFFF } element "MessageBroker" { background #FDCB6E shape Pipe color #000000 } element "SchemaRegistry" { background #FD79A8 shape Component color #000000 } element "Security" { background #2D3436 shape RoundedBox color #FFFFFF } element "IdentityProvider" { background #2D3436 stroke #74B9FF strokeWidth 3 color #FFFFFF } element "Observability" { background #636E72 shape Robot color #FFFFFF } element "Tracing" { background #636E72 stroke #00B894 strokeWidth 3 color #FFFFFF } element "Metrics" { background #636E72 stroke #FDCB6E strokeWidth 3 color #FFFFFF } element "Logging" { background #636E72 stroke #FD79A8 strokeWidth 3 color #FFFFFF } element "Visualization" { background #636E72 stroke #A29BFE strokeWidth 3 color #FFFFFF } element "User" { background #74B9FF shape Person color #000000 } element "Admin" { background #E17055 shape Person color #FFFFFF } element "Authentication" { background #ff6b35 color #ffffff } element "Workflow" { background #9b59b6 color #ffffff } element "Service" { background #34495e color #ffffff } element "UI" { background #e74c3c color #ffffff } element "External" { background #DDDDDD shape RoundedBox color #000000 stroke #999999 } relationship "Relationship" { color #000000 thickness 2 } relationship "HTTPS/REST" { color #0984E3 thickness 3 } relationship "gRPC" { color #00B894 thickness 3 } relationship "Kafka Protocol" { color #FDCB6E thickness 3 } relationship "OAuth2" { color #2D3436 thickness 2 dashed true } relationship "OIDC" { color #74B9FF thickness 2 dashed true } } } }