Architecture Documentation¶

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

Contents¶

Architecture Decision Records¶

C4 Model Diagrams¶

Behavioral Diagrams¶

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¶

The C4 model provides four levels of abstraction:

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 technology stack:

• Progressive Web App: React 19 + Vite + Tailwind CSS + PWA (installable on desktop and mobile)
• API Server: NestJS with OpenAPI/Swagger
• Database: PostgreSQL 16 via Prisma

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

Details the API server internals:

• Health Module: Health endpoints with build info, liveness and readiness probes
• Shopify Module: Webhook handling with HMAC verification
• Orders Module: Order CRUD and status management
• Product Mappings Module: SKU to print file mapping
• Event Emitter: Internal event bus
• Observability Module: Sentry integration, structured logging, exception filters

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

Shows the infrastructure:

• Development: Local Docker Compose with PostgreSQL
• Reverse Proxy: Traefik v3 with automatic Let's Encrypt TLS
• Containers: Docker Compose on DigitalOcean Droplets
• Container Registry: DigitalOcean Container Registry
• Database: DigitalOcean Managed PostgreSQL with TLS
• CI/CD: Azure DevOps Pipelines (build → push → deploy via SSH)
• Security: Aikido Security Platform (vulnerability scanning, SBOM generation)
• Observability: Sentry (error tracking, performance monitoring, distributed tracing)
• Print Farm: On-premises SimplyPrint edge device with LAN-connected printers

Staging URLs: - API: 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: SKU to print file mappings
• assembly_parts: Multi-part product configurations
• print_jobs: Print job tracking
• 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
• System: EventLog and SystemConfig
• Enumerations: OrderStatus, LineItemStatus, PrintJobStatus, EventSeverity, ShipmentStatus

DTO/API Contracts (C4_Code_DTOContracts.puml)¶

Documents the API request/response contracts:

• Orders API: CreateOrderDto, OrderResponseDto, OrderListResponseDto, etc.
• Product Mappings API: CreateProductMappingDto, ProductMappingResponseDto, etc.
• Shopify Webhooks: OrderWebhookPayload, WebhookHeaders, Shopify data types

State Diagrams¶

Located in state-machines/:

• Order Lifecycle (C4_Code_State_Order.puml): PENDING → PROCESSING → PARTIALLY_COMPLETED → COMPLETED/FAILED/CANCELLED
• 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
• Status Sync Rules (C4_Code_State_SyncRules.puml): How child statuses bubble up to parent entities

Event Catalog¶

Located in events/:

The event catalog provides comprehensive documentation for all domain events in the system:

• Orders Domain: order.created, order.status_changed, order.cancelled, order.ready-for-fulfillment, order.fulfilled, order.failed
• Print Jobs Domain: printjob.created, printjob.status-changed, printjob.completed, printjob.failed, printjob.cancelled, printjob.retry-requested
• Orchestration Domain: order.ready-for-fulfillment, order.partially-completed, order.all-jobs-failed
• Fulfillment Domain: fulfillment.created, fulfillment.failed, fulfillment.retrying
• Shipment Domain: shipment.created, shipment.label-ready, shipment.failed, shipment.updated
• SimplyPrint Integration: simplyprint.job-status-changed

Each event is documented with its TypeScript interface, trigger conditions, and consumers. Inline PlantUML diagrams illustrate the event flows.

See events/README.md for the complete event reference.

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

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