Skip to content

System Architecture & User Stories Mapping (Architektura Systému a Mapování Backlogu)

Dokumentová metadata 🗓️ Datum vytvoření / aktualizace: Září 2026 👤 Autor / Architekt: @Jules / Platform Engineering Team 🏷️ Stav: Schváleno (Living Reference Document) 🔗 Vazba na backlog: User Story #27 (CAD Product Studio & Multi-Publishing), User Story #17 (Správa 3D Šablon & Import Dat), User Story #16 (Asynchronní SignalR Pipeline & Worker Mesh), User Story #15 (Objednávkový Orchestrátor & Výrobní Dokumentace), User Story #14 (Webový 3D Konfigurátor & Three.js Event Bus)

1. Globální Architektura Systému (Global System Architecture)

Platforma COVEROQ CAD Platform je navržena jako distribuovaný, vrstvený a událostmi řízený ekosystém. Zajišťuje bezproblémový tok dat od vývojového CAD prostředí (FreeCAD 1.1) přes cloudovou API gateway, distribuovanou síť workerů na fyzické stanici pc-jakub až po e-commerce storefront (Medusa.js) a webový 3D configurator / studio (Three.js WebGL).

1.1 Vrstvený Diagram Systému (Layered C4 Architecture)

graph TD
    %% Klientská vrstva
    subgraph Client_Layer ["1. Klientská & Front-end Vrstva (Client Layer)"]
        Webapp["Web 3D Konfigurátor (webapp/index.html & inspector.html)"]
        Studio["CAD Product Studio (webapp/studio.html)"]
        LogsUI["Real-time Log & DAG Viewer (webapp/logs.html)"]
        MedusaStore["Medusa.js E-Commerce Storefront"]
    end

    %% API Gateway vrstva (.NET 10 Clean Architecture)
    subgraph Gateway_Layer ["2. API Gateway & Orchestrace (Coveroq.Cad.Api & Application)"]
        API_Main["ASP.NET Core Minimal API (Coveroq.Cad.Api)"]
        Auth_Dep["AdminTokenAuthHandler & Security Policies"]

        subgraph Endpoints ["Minimal API Endpoints"]
            R_Models["/api/models (ModelEndpoints.cs)"]
            R_Publish["/api/publishing (PublishingEndpoints.cs)"]
            R_Orders["/api/orders (OrderEndpoints.cs)"]
            R_CadHub["/hubs/cad (CadHub SignalR)"]
            R_Logs["/api/logs & /hubs/telemetry (LogEndpoints.cs)"]
        end

        subgraph Application ["CQRS Handlers & Behaviors (Coveroq.Cad.Application)"]
            InspectCmd["InspectUploadedModelCommandHandler"]
            ConfirmCmd["ConfirmModelImportCommandHandler"]
            ConfigureCmd["ConfigureModelCommandHandler"]
            PublishCmd["PublishAssemblyToMedusaCommandHandler"]
            WorkerGateway["RemoteCadWorkerGateway (Infrastructure)"]
            TracingBeh["TracingBehavior & LogContextKeys"]
        end
    end

    %% Datová & Repozitářová vrstva
    subgraph Data_Layer ["3. Datová & Repozitářová Vrstva (Coveroq.Cad.Infrastructure)"]
        ModelRepo["ModelRepository (EF Core)"]
        OrderRepo["OrderRepository (EF Core)"]
        AssemblyRepo["AssemblyRepository (EF Core)"]
        LogSink["InMemoryLogSink (Telemetry Ring Buffer)"]
        DB["CadDbContext (PostgreSQL / SQLite)"]
        LocalStorage["Local Storage (/storage/ orders, models, thumbnails)"]
    end

    %% Worker Mesh & CAD Solver vrstva (.NET 10 Worker)
    subgraph Worker_Layer ["4. Distribuovaný CAD Worker (Coveroq.Cad.Worker na pc-jakub)"]
        WorkerService["BackgroundService (Coveroq.Cad.Worker)"]
        SignalRClient["CadSignalRClient (SignalR Client /hubs/cad)"]
        WorkerDispatcher["WorkerJobDispatcher"]
        ProcessRunner["FreeCadProcessRunner"]
        FreeCADCmd["FreeCAD Headless CLI (freecadcmd & Python runner.py / inspect_model.py)"]
    end

    %% Externí Služby
    subgraph External_Layer ["5. Externí Úložiště & Integrace (External Cloud Services)"]
        MedusaAdmin["Medusa.js Admin REST API"]
    end

    %% Propojení Klientská -> Gateway
    Webapp -->|HTTP REST / JSON| R_Models
    Webapp -->|HTTP REST / JSON| R_Orders
    Studio -->|HTTP POST / Multipart| R_Models
    Studio -->|HTTP POST / JSON| R_Publish
    LogsUI -->|SignalR / REST| R_Logs
    MedusaStore -->|Storefront API| API_Main

    %% Gateway vnitřní směrování
    R_Models --> InspectCmd
    R_Models --> ConfirmCmd
    R_Orders --> ConfigureCmd
    R_Publish --> PublishCmd
    R_CadHub <-->|SignalR Protocol| WorkerGateway

    %% CQRS & Orchestrace
    InspectCmd --> WorkerGateway
    ConfigureCmd --> WorkerGateway
    PublishCmd --> MedusaAdmin
    ConfirmCmd --> ModelRepo

    %% Repozitáře -> Databáze
    ModelRepo --> DB
    OrderRepo --> DB
    AssemblyRepo --> DB
    TraceRepo --> LocalStorage
    WorkerGateway --> LocalStorage

    %% Worker Mesh Komunikace
    R_CadHub <-->|SignalR Hub Events| SignalRClient
    WorkerService --> SignalRClient
    SignalRClient --> WorkerDispatcher
    WorkerDispatcher --> ProcessRunner
    ProcessRunner --> FreeCADCmd

2. Mapování User Stories na Architekturu A Adresářovou Strukturu

Každá User Story reprezentuje ucelenou funkcionalitu systému. Následující tabulky a popisy zachycují přímé mapování backlogu na reálné modulární vrstvy kódové základny.

┌──────────────────────────────────────────────────────────────────────────────────┐
│                           MAPPING OVERVIEW TABLE                                 │
├──────────┼───────────────────────────────────────┼───────────────────────────────┤
│ Story ID │ Název User Story                      │ Hlavní Komponenty & Soubory   │
├──────────┼───────────────────────────────────────┼───────────────────────────────┤
│ #27      │ CAD Product Studio & Multi-Publishing │ PublishingEndpoints.cs        │
│          │                                       │ PublishAssemblyToMedusaCommand│
│          │                                       │ studio.html, studio_page.ts   │
├──────────┼───────────────────────────────────────┼───────────────────────────────┤
│ #17      │ Správa 3D Šablon & Import Dat         │ ModelEndpoints.cs             │
│          │                                       │ ConfirmModelImportCommand     │
│          │                                       │ ModelRepository.cs            │
├──────────┼───────────────────────────────────────┼───────────────────────────────┤
│ #16      │ Asynchronní SignalR Pipeline          │ CadHub.cs                     │
│          │                                       │ RemoteCadWorkerGateway.cs     │
│          │                                       │ CadSignalRClient.cs           │
├──────────┼───────────────────────────────────────┼───────────────────────────────┤
│ #15      │ Objednávkový Orchestrátor & BOM/DXF   │ OrderEndpoints.cs             │
│          │                                       │ ConfigureModelCommand         │
│          │                                       │ OrderRepository.cs            │
├──────────┼───────────────────────────────────────┼───────────────────────────────┤
│ #14      │ Webový 3D Konfigurátor (Three.js)     │ inspector.html, inspector_page│
│          │                                       │ viewer_facade.ts, store.ts    │
└──────────┴───────────────────────────────────────┴───────────────────────────────┘

2.1 User Story #27: CAD Product Studio & Multi-Publishing Pipeline

  • Byznys Cíl: Administrátorské rozhraní pro nahrání .fcstd šablony, auto-inspekci parametrické tabulky Vars a publikování do Medusa.js e-shopu a CAD DB na jedno kliknutí.
  • Mapování na vrstvy:
  • Endpoints (API): PublishingEndpoints.cs (POST /api/publishing/medusa), ModelEndpoints.cs (POST /api/models/inspect)
  • CQRS Commands: PublishAssemblyToMedusaCommand, InspectUploadedModelCommand
  • Infrastructure: MedusaApiClient.cs, RemoteCadWorkerGateway.cs
  • CAD Engine: Coveroq.Cad.Worker -> backend-dotnet/src/Coveroq.Cad.Worker/cad/scripts/inspect_model.py
  • Frontend: webapp/studio.html, webapp/src/pages/studio_page.ts, webapp/src/viewer/viewer_facade.ts

2.2 User Story #17: Správa 3D Šablon & Import Dat (Multi-template Management)

  • Byznys Cíl: Správa životního cyklu CAD šablon, verzování, extrakce parametrů a synchronizace šablon.
  • Mapování na vrstvy:
  • Endpoints (API): ModelEndpoints.cs (GET /api/models, GET /api/models/{modelId}/parameters, POST /api/models/confirm)
  • CQRS Handlers: ListModelsQueryHandler, GetModelParametersQueryHandler, ConfirmModelImportCommandHandler
  • Repositories: ModelRepository.cs, IModelRepository.cs
  • Domain Entities: ModelTemplate.cs, ParameterDefinition.cs
  • CAD Templates: storage/models/

2.3 User Story #16: Asynchronní Výpočetní Pipeline a SignalR Worker Mesh

  • Byznys Cíl: Distribuce náročných 3D výpočetních úloh (recompute, GLB export, 2D výkresy) na vzdálené workery pomocí SignalR hubu (/hubs/cad) v reálném čase.
  • Mapování na vrstvy:
  • SignalR Hub: CadHub.cs (/hubs/cad)
  • Gateway: RemoteCadWorkerGateway.cs (Dispečink úloh, heartbeat, liveness check)
  • Worker Components:
    • Coveroq.Cad.Worker (.NET 10 Console Service, coveroq-cad-worker.service na pc-jakub)
    • CadSignalRClient.cs (SignalR client s automatickým opätovným pripojením)
    • WorkerJobDispatcher.cs (Zpracování úloh a předání solveru)
    • FreeCadProcessRunner.cs (Spouštění freecadcmd runner.py s předáním kauzalitních příznaků --trace-id, --span-id, --parent-span-id)

2.4 User Story #15: Objednávkový Orchestrátor a Generování Výrobní Dokumentace

  • Byznys Cíl: Příjem klientské konfigurace, vytvoření objednávky, orchestrace generování podkladů pro výrobu (BOM kusovník, 2D DXF výkresy, GLB 3D soubory) a jejich uložení.
  • Mapování na vrstvy:
  • Endpoints (API): OrderEndpoints.cs (POST /api/orders/configure, GET /api/orders/{orderId})
  • CQRS Handlers: ConfigureModelCommandHandler, GetOrderByIdQueryHandler
  • Repositories: OrderRepository.cs, IOrderRepository.cs
  • CAD Scripts: backend-dotnet/src/Coveroq.Cad.Worker/cad/scripts/runner.py, drawing_2d.py, solid_3d.py

2.5 User Story #14: Webový 3D Konfigurátor a Klientské Rozhraní

  • Byznys Cíl: Interaktivní klientská webová aplikace s 3D viewportem (Three.js), dynamickými posuvníky parametrů, okamžitou odezvou, náhledem kusovníku a sledováním stavu zpracování.
  • Mapování na vrstvy:
  • Frontend Entry: webapp/index.html, webapp/inspector.html, webapp/src/pages/inspector_page.ts
  • State & Services: webapp/src/core/store.ts (Pub/Sub Store), webapp/src/services/order_service.ts, webapp/src/services/telemetry_service.ts
  • 3D Viewport: webapp/src/viewer/viewer_facade.ts (Three.js SceneManager, CameraController, AssetLoader)
  • UI Components: webapp/src/components/inspector_parameter_controls.ts, webapp/src/viewer/inspector_viewport_controls.ts

3. Pravidlo Zero-Fallback (Rule 12 - Absolute Determinism)

Platforma COVEROQ CAD Platform důsledně uplatňuje Pravidlo Zero-Fallback:

  1. Zákaz Záložních / Spekulativních Pokusů:
  2. Jakékoliv záložní mechanismy (fallback retry, tiché přepnutí na sekundární CLI skript, klientské mockování dat) jsou přísně zakázány.
  3. Deterministické Selhání (Fail Fast):
  4. Pokud operace nebo předpoklad selže, systém okamžitě vrátí chybový výsledek (Result.Failure(...) nebo HTTP 4xx/5xx) a vygeneruje strukturovaný kauzalitní záznam (TraceId, CorrelationId, ElapsedMs).
  5. Jediná Cesta Spuštění:
  6. Každá služba má přesně jednu jasnou cestu vykonání. Při chybě dojde k okamžité notifikaci přes TelemetryHub a zobrazení chyby v UI bez zatajování.

4. Databázový Model a Relace (EF Core Entity Schema)

Následující diagram znázorňuje základní C# .NET 10 entitní strukturu v Coveroq.Cad.Domain:

erDiagram
    ModelTemplate ||--o{ ParameterDefinition : "obsahuje (1:N)"
    ModelTemplate ||--o{ AssemblyStructure : "skládá se ze skeletu/dílů"
    Order ||--o{ OrderComponentSnapshot : "obsahuje (1:N)"

    ModelTemplate {
        string Id PK "ModelTemplateId (Value Object)"
        string Name "Název modelu / dílu"
        string Type "Skeleton | Part | Assembly"
        string FilePath "Relativní cesta na disku (.fcstd)"
        string ThumbnailPath "Cesta k náhledu (.webp)"
        datetime CreatedAtUtc "UTC Razítko"
    }

    ParameterDefinition {
        string Key PK "Klíč bunky v tabulce Vars (např. Width)"
        string Label "Čitelný název v UI"
        string Group "Skupina parametrů"
        decimal DefaultValue "Výchozí hodnota"
        decimal MinValue "Minimální mez"
        decimal MaxValue "Maximální mez"
        decimal StepValue "Krok změny"
        string Unit "Jednotka (mm, deg, kg)"
        boolean IsReadOnly "True pro odvozené vzorce"
        boolean IsVisible "True pro zobrazení v UI"
        string ExpressionFormula "Odvozený vzorec (=Width-50)"
    }

    Order {
        string Id PK "OrderId (Value Object)"
        string Status "Pending | Processing | Completed | Failed"
        string ModelTemplateId FK "Vazba na ModelTemplate"
        decimal TotalPrice "Celková cena"
        datetime CreatedAtUtc "UTC Razítko"
    }

5. Verifikace a Kvalita (Build & QA Verification)

Pro zajištění stability a dodržování architektonických pravidel podléhá kódový základ následujícím kontrolám:

Kontrola / Audit Příkaz pro Spuštění Očekávaný Výsledek
Kompilace Dokumentace uv run python -m mkdocs build Documentation built successfully (0 chyb).
Roslyn Analyzátory (.NET 10) dotnet build backend-dotnet/Coveroq.Cad.slnx 0 Errors (vymáhání CCAD pravidel).
Frontend Typová Kontrola npm run typecheck Found 0 errors.
Frontend Testy (Vitest) npm run test Všechny Vitest testy projdou.
Backend C# Testy (xUnit) dotnet test backend-dotnet/Coveroq.Cad.slnx Všechny unit, integrační a architektonické testy projdou.

Tento dokument je živou architektonickou specifikací systému COVEROQ CAD Platform a je automaticky validován v CI/CD pipeline.