Architecture Documentation¶

This folder contains the Architecture Decision Records (ADR) and C4 model diagrams for Forma3D.Connect.

Architecture Overview¶

Forma3D.Connect uses a microservice architecture with domain-aligned services communicating via BullMQ event queues (Redis) and internal HTTP APIs:

Infrastructure:

• Redis 7 — BullMQ event queues, session store, Socket.IO adapter
• PostgreSQL 16 — Shared database via Prisma
• Uptime Kuma — Health endpoint monitoring
• Dozzle — Real-time Docker log viewer

Contents¶

Technology Stack¶

Architecture Decision Records¶

C4 Model Diagrams¶

Behavioral Diagrams¶

EventCatalog (Runtime Interaction Documentation)¶

EventCatalog complements the C4 model by documenting runtime interactions (events, commands, queries) rather than structural decomposition. It provides:

• 6 domains with subdomains (Orders, Printing, Shipping, GridFlock, Platform, Inventory)
• 6 services with publish/subscribe metadata
• 13 BullMQ events with TypeScript schemas and example payloads
• 8 inter-service HTTP commands and 7 queries
• Auto-generated service dependency visualizations
• AI-queryable via MCP server (Cursor integration)

C4 Model Diagrams¶

The diagrams use C4-PlantUML which combines the C4 model for software architecture with PlantUML.

Rendering the Diagrams¶

Option 1: VS Code with PlantUML Extension¶

1. Install the PlantUML extension for VS Code
2. Open any .puml file
3. Press Alt+D to preview the diagram

Option 2: Online PlantUML Server¶

1. Go to PlantUML Web Server
2. Copy the contents of any .puml file
3. Paste into the editor to render

Option 3: Command Line¶

# Install PlantUML (macOS)
brew install plantuml

# Render all diagrams to PNG
find . -name "*.puml" -exec plantuml {} \;

# Or render to SVG
find . -name "*.puml" -exec plantuml -tsvg {} \;

Option 4: IntelliJ IDEA¶

1. Install the PlantUML Integration plugin
2. Open any .puml file
3. The diagram preview appears automatically

C4 Model Levels¶

Diagram Details¶

1. System Context (c4-model/1-context/)¶

Shows Forma3D.Connect in the context of:

• Actors: Operators (admin users) and Customers (shoppers)
• External Systems: Shopify, SimplyPrint (with edge device for LAN printer control), Sendcloud (shipping platform), Sentry (observability platform)

2. Containers (c4-model/2-container/)¶

Shows the microservice architecture:

• Progressive Web App: React 19 + Vite + Tailwind CSS + PWA (installable on desktop and mobile)
• API Gateway: NestJS — Auth, routing, WebSocket, sessions (Redis)
• Order Service: NestJS — Orders, mappings, orchestration, fulfillment, inventory
• Print Service: NestJS — Print jobs, SimplyPrint integration
• Shipping Service: NestJS — Shipments, Sendcloud integration
• GridFlock Service: NestJS — Parametric STL generation, slicing pipeline
• Slicer Container: BambuStudio CLI — Headless slicing
• Redis 7: BullMQ event queues, session store, Socket.IO adapter
• Database: PostgreSQL 16 via Prisma

3. Components (c4-model/3-component/)¶

Details each service's internals:

• API Gateway: Proxy service, auth module, WebSocket gateway, health aggregation
• Order Service: Shopify webhooks, order CRUD, orchestration, fulfillment, cancellation, inventory tracking, stock replenishment, retry queue, notifications
• Print Service: Print job management, SimplyPrint client, webhook handling, status polling
• Shipping Service: Sendcloud client, shipment management, tracking sync
• GridFlock Service: STL generation, pipeline orchestration, internal API, event publishing

4. Deployment (c4-model/deployment/)¶

Shows the infrastructure:

• Development: Local Docker Compose with PostgreSQL, Redis, and Slicer
• Reverse Proxy: Traefik v3 with automatic Let's Encrypt TLS
• Containers: Docker Compose on DigitalOcean Droplet (4 GB)
• Container Registry: DigitalOcean Container Registry
• Database: DigitalOcean Managed PostgreSQL with TLS
• CI/CD: Azure DevOps Pipelines (build → push → deploy via SSH)
• Security: Syft (CycloneDX SBOM generation) + Grype (CVE scanning) — open-source tools by Anchore, run in CI/CD
• Observability: Sentry (error tracking, performance monitoring, distributed tracing)
• Monitoring: Uptime Kuma (health checks), Dozzle (container logs)
• Print Farm: On-premises SimplyPrint edge device with LAN-connected printers

Staging URLs:

• Gateway: https://staging-connect-api.forma3d.be
• Web: https://staging-connect.forma3d.be

5. Database (c4-model/deployment/)¶

Shows the Prisma schema:

• orders: Customer orders from Shopify
• line_items: Individual products in orders
• product_mappings: Product to print file mappings
• assembly_parts: Multi-part product configurations
• print_jobs: Print job tracking
• shipments: Shipping label and tracking data
• gridflock_jobs: Async STL generation job tracking
• gridflock_presets: Reusable baseplate parameter presets
• stock_batches: Stock replenishment batch tracking
• inventory_transactions: Immutable inventory change ledger
• event_logs: Audit trail

Level 4: Code Diagrams¶

Located in c4-model/4-code/:

Domain Model (C4_Code_DomainModel.puml)¶

Shows the core domain entities and their relationships:

• Order Aggregate: Order → LineItem hierarchy
• Product Catalog: ProductMapping → AssemblyPart configuration
• Print Execution: PrintJob and Printer tracking
• Shipping: Shipment for Sendcloud integration
• GridFlock Pipeline: GridflockJob and GridflockPreset for parametric generation
• Inventory & Stock: StockBatch and InventoryTransaction for stock replenishment
• System: EventLog and SystemConfig
• Enumerations: OrderStatus, LineItemStatus, PrintJobStatus, PrintJobPurpose, StockBatchStatus, InventoryTransactionType, EventSeverity, ShipmentStatus, GridflockJobType, GridflockJobStatus

DTO/API Contracts (C4_Code_DTOContracts.puml)¶

Documents the API request/response contracts:

• Orders API: CreateOrderDto, OrderResponseDto, OrderQueryDto, OrderListResponseDto
• Product Mappings API: CreateProductMappingDto, ProductMappingResponseDto
• Shopify Webhooks: OrderWebhookPayload, WebhookHeaders
• GridFlock API: GenerateBaseplateDto, GridflockJobResponseDto, GridflockPresetResponseDto
• Inter-Service DTOs: InternalCreatePrintJobDto, InternalCreateShipmentDto, InternalGridflockGenerateDto
• BullMQ Event Payloads: OrderCreatedEvent, PrintJobCompletedEvent, ShipmentCreatedEvent, GridflockMappingReadyEvent, StockReplenishmentScheduledEvent, StockBatchCompletedEvent

State Diagrams¶

Located in state-machines/:

• Order Lifecycle (C4_Code_State_Order.puml): PENDING → PROCESSING → PARTIALLY_COMPLETED → COMPLETED/FAILED/CANCELLED (with revival: FAILED/PARTIALLY_COMPLETED/CANCELLED → PROCESSING when a job is requeued)
• LineItem Lifecycle (C4_Code_State_LineItem.puml): PENDING → PRINTING → PARTIALLY_COMPLETED → COMPLETED/FAILED
• PrintJob Lifecycle (C4_Code_State_PrintJob.puml): QUEUED → ASSIGNED → PRINTING → COMPLETED/FAILED/CANCELLED
• GridFlock Pipeline (C4_Code_State_GridflockPipeline.puml): PENDING → GENERATING_STL → SLICING → UPLOADING → CREATING_MAPPING → COMPLETE / FAILED
• StockBatch Lifecycle (C4_Code_State_StockBatch.puml): IN_PROGRESS → COMPLETED / FAILED
• Status Sync Rules (C4_Code_State_SyncRules.puml): How child statuses bubble up to parent entities

Event Catalog¶

Note: The manual event catalog at events/README.md has been superseded by EventCatalog at eventcatalog/. The legacy document is retained as a reference but is no longer the source of truth.

EventCatalog (at eventcatalog/ and live instance) provides browsable, searchable documentation for all BullMQ events, inter-service HTTP commands, and queries.

Legacy reference: events/README.md

Sequence Diagrams¶

Located in sequences/:

Architecture Decision Records (ADR)¶

ADRs document the "why" behind architectural decisions. Each ADR includes:

• Context: The situation and constraints
• Decision: What was decided
• Rationale: Why this decision was made
• Consequences: Trade-offs and implications
• Alternatives Considered: Other options and why they were rejected

Notable microservice-related ADRs:

• ADR-051: Decompose monolithic API into domain-aligned microservices
• ADR-052: BullMQ event queues for inter-service async communication
• ADR-053: Buffer-based GridFlock pipeline (no local file storage)
• ADR-054: SimplyPrint API Files for gcode upload
• ADR-055: BambuStudio CLI slicer container
• ADR-056: Redis for sessions, event queues, and Socket.IO adapter
• ADR-062: Inventory tracking and stock replenishment (hybrid fulfillment)

See adr/ADR.md for all current ADRs.

Contributing¶

When making architectural changes:

1. Add an ADR for any significant decision
2. Update diagrams to reflect changes
3. Keep diagrams in sync with the actual implementation

ADR Template¶

## ADR-XXX: Title

| Attribute   | Value                                         |
| ----------- | --------------------------------------------- |
| **ID**      | ADR-XXX                                       |
| **Status**  | Proposed / Accepted / Deprecated / Superseded |
| **Date**    | YYYY-MM-DD                                    |
| **Context** | What is the issue?                            |

### Decision

What was decided?

### Rationale

Why was this decision made?

### Consequences

What are the trade-offs?

### Alternatives Considered

What other options were evaluated?

References¶

• C4 Model - The C4 model for software architecture
• C4-PlantUML - PlantUML macros for C4 diagrams
• ADR GitHub Organization - Resources for Architecture Decision Records
• PlantUML - PlantUML documentation
• BullMQ - BullMQ documentation
• Uptime Kuma - Self-hosted monitoring
• Dozzle - Real-time Docker log viewer