Architecture Decision Records (ADR)¶

Project: Forma3D.Connect
Version: 4.5
Last Updated: March 22, 2026

This document captures the significant architectural decisions made during the development of Forma3D.Connect.

Table of Contents¶

1. ADR-001: Monorepo with Nx
2. ADR-002: NestJS for Backend Framework
3. ADR-003: React 19 with Vite for Frontend
4. ADR-004: PostgreSQL with Prisma ORM
5. ADR-005: TypeScript Strict Mode
6. ADR-006: Azure DevOps for CI/CD
7. ADR-007: Layered Architecture with Repository Pattern
8. ADR-008: Event-Driven Internal Communication
9. ADR-009: OpenAPI/Swagger for API Documentation
10. ADR-010: HMAC Verification for Webhooks
11. ADR-011: Idempotent Webhook Processing
12. ADR-012: Assembly Parts Model for Product Mapping
13. ADR-013: Shared Domain Library
14. ADR-014: SimplyPrint as Unified Print Farm Controller
15. ADR-015: Aikido Security Platform (Superseded)
16. ADR-016: Sentry Observability with OpenTelemetry
17. ADR-017: Docker + Traefik Deployment Strategy
18. ADR-018: Nx Affected Conditional Deployment Strategy
19. ADR-019: SimplyPrint Webhook Verification
20. ADR-020: Hybrid Status Monitoring (Polling + Webhooks)
21. ADR-021: Retry Queue with Exponential Backoff
22. ADR-022: Event-Driven Fulfillment Architecture
23. ADR-023: Email Notification Strategy
24. ADR-024: API Key Authentication for Admin Endpoints
25. ADR-025: Cosign Image Signing for Supply Chain Security
26. ADR-026: CycloneDX SBOM Attestations
27. ADR-027: TanStack Query for Server State Management
28. ADR-028: Socket.IO for Real-Time Dashboard Updates
29. ADR-029: API Key Authentication for Dashboard
30. ADR-030: Sendcloud for Shipping Integration
31. ADR-031: Automated Container Registry Cleanup
32. ADR-032: Domain Boundary Separation with Interface Contracts
33. ADR-033: Database-Backed Webhook Idempotency
34. ADR-034: Docker Log Rotation & Resource Cleanup
35. ADR-035: Progressive Web App (PWA) for Cross-Platform Access
36. ADR-036: localStorage Fallback for PWA Install Detection
37. ADR-037: Keep a Changelog for Release Documentation
38. ADR-038: Zensical for Publishing Project Documentation
39. ADR-039: Global API Key Authentication (Fail-Closed)
40. ADR-040: Shopify Order Backfill for Downtime Recovery
41. ADR-041: SimplyPrint Webhook Idempotency and Job Reconciliation
42. ADR-042: SendCloud Webhook Integration for Shipment Status Updates
43. ADR-043: PWA Version Mismatch Detection
44. ADR-044: Role-Based Access Control and Tenant-Ready Architecture
45. ADR-045: pgAdmin for Staging Database Administration
46. ADR-046: PostgreSQL Session Store for Persistent Authentication
47. ADR-047: Two-Tier Logging Strategy (Application + Business Events)
48. ADR-048: Shopify OAuth 2.0 Authentication
49. ADR-049: Optional SKU with Shopify Product/Variant ID Matching Priority
50. ADR-050: Apache ECharts for Dashboard Analytics
51. ADR-051: Decompose Monolithic API into Domain-Aligned Microservices
52. ADR-052: BullMQ Event Queues for Inter-Service Async Communication
53. ADR-053: Buffer-Based GridFlock Pipeline (No Local File Storage)
54. ADR-054: SimplyPrint API Files for Gcode Upload
55. ADR-055: BambuStudio CLI Slicer Container
56. ADR-056: Redis for Sessions, Event Queues, and Socket.IO Adapter
57. ADR-057: Self-Hosted Build Agent with Hybrid Pipeline Strategy
58. ADR-058: Self-Hosted Log Infrastructure (ClickHouse + Grafana via OpenTelemetry)
59. ADR-059: Nx Affected Resilience via Last-Successful-Deploy Tag
60. ADR-060: Single Source of Truth for STL Preview Generation
61. ADR-061: Plate-Level Preview Cache with Dynamic Border Assembly
62. ADR-062: Inventory Tracking and Stock Replenishment
63. ADR-063: ORDER-over-STOCK Print Queue Priority
64. ADR-064: Stock Replenishment Event Subscriber for SimplyPrint Queue
65. ADR-065: SonarCloud for Continuous Code Quality Analysis
66. ADR-066: CodeCharta City Visualization for Codebase Insight
67. ADR-067: Grype CVE Scanning with EPSS-Informed Risk Acceptance
68. ADR-068: Dependency License Compliance Check
69. ADR-069: Agent CLAUDE.md Governance — Repo as Source of Truth
70. ADR-070: Per-Agent Claude Model Selection

ADR-001: Monorepo with Nx¶

Decision¶

Use Nx (v19.x) as the monorepo management tool with pnpm as the package manager.

Rationale¶

• Unified tooling: Single command to build, test, lint all projects
• Dependency graph: Nx understands project dependencies and can run only affected tests
• Caching: Local and remote caching speeds up CI/CD pipelines
• Code sharing: Shared libraries (@forma3d/domain, @forma3d/utils, etc.) are first-class citizens
• Plugin ecosystem: Built-in support for NestJS, React, and other frameworks

Consequences¶

• ✅ Fast CI through affected commands and caching
• ✅ Consistent tooling across all projects
• ✅ Easy code sharing via path aliases
• ⚠️ Learning curve for developers unfamiliar with Nx
• ⚠️ Initial setup complexity

Alternatives Considered¶

ADR-002: NestJS for Backend Framework¶

Decision¶

Use NestJS (v10.x) as the backend framework.

Rationale¶

• Enterprise-grade: Built-in support for dependency injection, modules, guards, interceptors
• TypeScript-first: Native TypeScript support with decorators
• Modular architecture: Easy to organize code by feature
• Excellent documentation: Well-documented with active community
• Testing support: Built-in testing utilities with Jest
• OpenAPI support: First-class Swagger/OpenAPI integration via @nestjs/swagger

Consequences¶

• ✅ Clean, maintainable code structure
• ✅ Easy to add new features as modules
• ✅ Built-in validation with class-validator
• ✅ Excellent integration with Prisma
• ⚠️ Verbose compared to Express.js
• ⚠️ Decorator-heavy syntax

Alternatives Considered¶

ADR-003: React 19 with Vite for Frontend¶

Decision¶

Use React 19 with Vite as the bundler and Tailwind CSS for styling.

Rationale¶

• React 19: Latest version with improved performance and new features
• Vite: Extremely fast development server and build times
• Tailwind CSS: Utility-first CSS for rapid UI development
• TanStack Query: Excellent server state management
• React Router: Standard routing solution

Consequences¶

• ✅ Fast development experience with HMR
• ✅ Modern React features (Server Components ready)
• ✅ Consistent styling with Tailwind
• ⚠️ Tailwind learning curve for traditional CSS developers

Alternatives Considered¶

ADR-004: PostgreSQL with Prisma ORM¶

Decision¶

Use PostgreSQL 16 as the database with Prisma 5 as the ORM.

Rationale¶

• PostgreSQL: Robust, ACID-compliant, excellent JSON support
• Prisma: Type-safe database access, auto-generated client
• Schema-first: Prisma schema as single source of truth
• Migrations: Built-in migration system
• Studio: Visual database browser for development

Consequences¶

• ✅ Full type safety from database to API
• ✅ Easy schema changes with migrations
• ✅ No raw SQL in application code
• ⚠️ Prisma Client must be regenerated after schema changes
• ⚠️ Some complex queries require raw SQL

Schema Design Decisions¶

• UUIDs for primary keys (portability, no sequence conflicts)
• JSON columns for flexible data (shipping address, print profiles)
• Decimal type for monetary values (precision)
• Timestamps with timezone (audit trail)

ADR-005: TypeScript Strict Mode¶

Decision¶

Enable TypeScript strict mode with additional strict checks:

{
  "strict": true,
  "noImplicitAny": true,
  "strictNullChecks": true,
  "noUnusedLocals": true,
  "noUnusedParameters": true
}

Rationale¶

• Early error detection: Catch type errors at compile time
• Self-documenting code: Types serve as documentation
• Refactoring safety: IDE can safely refactor with full type information
• No any type: Prevents type escape hatches

Consequences¶

• ✅ Higher code quality
• ✅ Better IDE support and autocomplete
• ✅ Safer refactoring
• ⚠️ More verbose code with explicit types
• ⚠️ Stricter null checking requires careful handling

ADR-006: Azure DevOps for CI/CD with Digital Ocean Hosting¶

Decision¶

Use Azure DevOps Pipelines for CI/CD and Digital Ocean for hosting.

Rationale¶

• Azure DevOps: Existing team expertise with YAML pipelines
• Digital Ocean: Cost-effective, simple infrastructure for small-scale deployment
• Separation of concerns: CI/CD tooling separate from hosting
• Docker-based: Consistent container deployment across environments
• Managed Database: Digital Ocean managed PostgreSQL for reliability

Infrastructure¶

Pipeline Stages¶

1. Validate & Test: Lint, type check, and unit tests (parallel across 3 agents)
2. Build & Package: Detect affected, build projects, Docker images on self-hosted agents
3. Deploy Staging: Auto-deploy affected services on main branch
4. Acceptance Test: Playwright tests against staging
5. Deploy Production: Manual approval gate

Updated Feb 2026: Stages merged and agents optimized per ADR-057.

Consequences¶

• ✅ Automated quality gates
• ✅ Fast feedback on PRs
• ✅ Consistent deployments
• ✅ Cost-effective hosting
• ⚠️ Need to manage Docker deployments on Droplets

ADR-007: Layered Architecture with Repository Pattern¶

Decision¶

Implement a layered architecture with the Repository Pattern:

Layer Responsibilities¶

Rationale¶

• Testability: Each layer can be tested in isolation
• Single responsibility: Clear separation of concerns
• Flexibility: Easy to swap implementations (e.g., different databases)
• Maintainability: Changes in one layer don't affect others

Consequences¶

• ✅ Clean, maintainable code
• ✅ Easy to unit test with mocks
• ✅ Prisma isolated to repository layer
• ⚠️ More files per feature
• ⚠️ Some boilerplate code

ADR-008: Event-Driven Internal Communication¶

Decision¶

Use NestJS EventEmitter for internal event-driven communication.

Events Defined¶

Order Events (ORDER_EVENTS)¶

Print Job Events (PRINT_JOB_EVENTS)¶

Orchestration Events (ORCHESTRATION_EVENTS)¶

SimplyPrint Events (SIMPLYPRINT_EVENTS)¶

Shipment Events (SHIPMENT_EVENTS)¶

SendCloud Webhook Events (SENDCLOUD_WEBHOOK_EVENTS)¶

Fulfillment Events (FULFILLMENT_EVENTS)¶

Event Flow Diagram¶

Shopify Webhook → OrdersService → order.created
                                       ↓
                              OrchestrationService
                                       ↓
                              PrintJobsService → printjob.created
                                       ↓
                              SimplyPrint API

SimplyPrint Webhook → SimplyPrintService → simplyprint.job-status-changed
                                                  ↓
                                          PrintJobsService → printjob.status-changed
                                                  ↓                    ↓
                                          printjob.completed    printjob.failed
                                                  ↓                    ↓
                                          OrchestrationService ←───────┘
                                                  ↓
                                          order.ready-for-fulfillment
                                                  ↓
                                ┌─────────────────┴─────────────────┐
                                ↓                                   ↓
                        SendcloudService                   FulfillmentService
                                ↓                                   ↓
                        shipment.created ──────────────────→ Shopify Fulfillment
                                ↓
                        SendCloud Webhook → sendcloud.shipment.status_changed

Rationale¶

• Decoupling: Services don't directly depend on each other
• Extensibility: Easy to add new listeners
• Async processing: Events can be processed asynchronously
• Audit trail: Events naturally support logging
• Orchestration: Clean separation between job creation and completion tracking
• Real-time updates: EventsGateway broadcasts to dashboard via Socket.IO
• Push notifications: PushService sends alerts to subscribed PWA clients

Consequences¶

• ✅ Loose coupling between modules
• ✅ Easy to add new functionality
• ✅ Clear event flow
• ✅ Enables reactive order completion tracking
• ✅ Real-time dashboard updates via Socket.IO
• ✅ Push notifications for mobile/desktop PWA
• ⚠️ Harder to trace execution flow (mitigated by correlation IDs and logging)
• ⚠️ Eventual consistency considerations

ADR-009: OpenAPI/Swagger for API Documentation¶

Decision¶

Use @nestjs/swagger for OpenAPI 3.0 documentation with Swagger UI.

Implementation¶

• Swagger UI: Available at /api/docs
• OpenAPI JSON: Available at /api/docs-json
• Environment restriction: Only enabled in non-production
• Decorator-based: All endpoints documented via decorators

Decorators Used¶

Consequences¶

• ✅ Interactive API testing
• ✅ Auto-generated documentation
• ✅ Type-safe documentation
• ⚠️ Must keep decorators in sync with code

ADR-010: HMAC Verification for Webhooks¶

Decision¶

Implement HMAC-SHA256 signature verification for all Shopify webhooks.

Implementation¶

// ShopifyWebhookGuard
const hash = crypto.createHmac('sha256', webhookSecret).update(rawBody, 'utf8').digest('base64');

return crypto.timingSafeEqual(Buffer.from(hash), Buffer.from(hmacHeader));

Rationale¶

• Security: Prevents forged webhook requests
• Shopify standard: Required by Shopify webhook specification
• Timing-safe comparison: Prevents timing attacks
• Raw body access: NestJS configured to preserve raw body

Consequences¶

• ✅ Secure webhook endpoint
• ✅ Compliant with Shopify requirements
• ⚠️ Requires raw body access (special NestJS configuration)

ADR-011: Idempotent Webhook Processing¶

Decision¶

Implement idempotent webhook processing using:

1. Webhook ID tracking (in-memory Set)
2. Database unique constraints (shopifyOrderId)

Implementation¶

// ShopifyService
private readonly processedWebhooks = new Set<string>();

if (this.processedWebhooks.has(webhookId)) {
  return; // Skip duplicate
}
this.processedWebhooks.add(webhookId);

// OrdersService
const existing = await this.ordersRepository.findByShopifyOrderId(id);
if (existing) {
  return existing; // Return existing, don't create duplicate
}

Consequences¶

• ✅ No duplicate orders created
• ✅ Safe to retry failed webhooks
• ⚠️ In-memory Set resets on restart (database constraint is primary guard)

ADR-012: Assembly Parts Model for Product Mapping¶

Decision¶

Implement ProductMapping → AssemblyPart one-to-many relationship.

Data Model¶

Fields¶

• ProductMapping: shopifyProductId, SKU (optional), defaultPrintProfile
• AssemblyPart: partName, partNumber, simplyPrintFileId, quantityPerProduct

Rationale¶

• Flexibility: Support both single-part (1 part) and multi-part products
• Quantity support: quantityPerProduct for parts needed multiple times (e.g., 4 wheels)
• Print profiles: Override default profile per part if needed

Consequences¶

• ✅ Supports complex assemblies
• ✅ Clear part ordering via partNumber
• ✅ Flexible print settings per part
• ⚠️ More complex order processing logic

ADR-013: Shared Domain Library¶

Decision¶

Create a shared @forma3d/domain library containing:

• Entity types
• Enums
• Shopify types
• Common interfaces

Structure¶

libs/domain/src/
├── entities/
│   ├── order.ts
│   ├── line-item.ts
│   ├── print-job.ts
│   └── product-mapping.ts
├── enums/
│   ├── order-status.ts
│   ├── line-item-status.ts
│   └── print-job-status.ts
├── shopify/
│   ├── shopify-order.entity.ts
│   └── shopify-product.entity.ts
└── index.ts

Rationale¶

• Single source of truth: Types defined once, used everywhere
• Type safety: Frontend and backend share exact same types
• Nx integration: Clean imports via path aliases

Consequences¶

• ✅ Consistent types across codebase
• ✅ No type drift between frontend/backend
• ✅ Easy to update types in one place
• ⚠️ Must rebuild library on changes

ADR-014: SimplyPrint as Unified Print Farm Controller¶

Decision¶

Use SimplyPrint as the unified print farm management solution with an edge device connecting to all printers via LAN.

Architecture¶

Rationale¶

• Unified API: Single integration point for all printer brands
• LAN mode: Direct communication with printers, no cloud dependency for print control
• Edge device: Handles printer communication, buffering, and monitoring
• Multi-brand support: Prusa and Bambu Lab printers managed together
• No Bambu Cloud dependency: Avoids Bambu Lab Cloud API limitations

Printer Support¶

Implementation Details (Phase 2)¶

API Client (apps/api/src/simplyprint/simplyprint-api.client.ts):

• HTTP Basic Authentication with Company ID and API Key
• Typed methods for files, jobs, printers, and queue operations
• Automatic connection verification on startup
• Sentry integration for 5xx error tracking

Webhook Controller (apps/api/src/simplyprint/simplyprint-webhook.controller.ts):

• Endpoint: POST /webhooks/simplyprint
• X-SP-Token verification via guard
• Event-driven status updates

Print Jobs Service (apps/api/src/print-jobs/print-jobs.service.ts):

• Creates print jobs in SimplyPrint when orders arrive
• Updates local status based on SimplyPrint events
• Supports cancel and retry operations

API Endpoints Used:

Consequences¶

• ✅ Single API for all printers
• ✅ No dependency on Bambu Lab Cloud
• ✅ Local network resilience
• ✅ Real-time printer status via edge device
• ✅ Typed API client with full error handling
• ✅ Webhook and polling support for status updates
• ⚠️ Requires edge device on print farm network
• ⚠️ SimplyPrint subscription required

ADR-015: Aikido Security Platform for Continuous Security Monitoring¶

Decision¶

Use Aikido Security Platform as the centralized security monitoring and compliance solution integrated into the CI/CD pipeline.

Security Checks Implemented¶

Rationale¶

• Comprehensive coverage: Single platform covers multiple security domains
• CI/CD integration: Automated scanning on every code change
• SBOM generation: Critical for supply chain security and compliance
• License compliance: Automated license validation prevents legal issues
• Developer-friendly: Clear dashboards and actionable remediation guidance
• Proactive detection: Continuous monitoring catches issues before production

Future Enhancements¶

• Code Quality Analysis: Will be enabled in a subsequent phase to complement security scanning

Consequences¶

• ✅ Continuous security visibility across the codebase
• ✅ Automated vulnerability detection in dependencies
• ✅ SBOM generation for supply chain transparency
• ✅ License compliance validation
• ✅ Secrets exposure prevention
• ⚠️ Requires Aikido platform subscription
• ⚠️ May flag false positives requiring triage

Alternatives Considered¶

ADR-016: Sentry Observability with OpenTelemetry ✅¶

Decision¶

Use Sentry as the observability platform with an OpenTelemetry-first architecture for vendor neutrality.

Architecture¶

Implementation Details¶

Backend (NestJS):

• @sentry/nestjs for error tracking and performance
• @sentry/profiling-node for profiling
• nestjs-pino for structured JSON logging
• OpenTelemetry auto-instrumentation for Prisma queries
• Global exception filter with Sentry capture
• Logging interceptor with correlation IDs

Frontend (React):

• @sentry/react for error tracking
• Custom ErrorBoundary component with Sentry integration
• Browser tracing for page navigation
• User-friendly error fallback UI

Sampling Configuration (Free Tier Compatible):

Rationale¶

• Sentry: Industry-leading error tracking with excellent stack trace support
• OpenTelemetry: Vendor-neutral instrumentation standard, future-proof
• Structured Logging: JSON logs enable log aggregation and searching
• Correlation IDs: End-to-end request tracing across frontend and backend
• Free Tier: Sufficient for small-scale production (10K errors/month)

Data Privacy¶

Sensitive data is automatically scrubbed:

• Authorization headers
• Cookies
• API tokens
• Passwords
• Shopify access tokens

Implementation Details (Phase 1b)¶

Backend (apps/api):

• instrument.ts - Sentry initialization with profiling (imported first in main.ts)
• ObservabilityModule - Global module with Pino logger and Sentry integration
• SentryExceptionFilter - Captures all exceptions with request context
• LoggingInterceptor - Request/response logging with correlation IDs
• ObservabilityController - Test endpoints for verifying observability (non-prod only)
• Prisma service enhanced with Sentry breadcrumbs for query tracing

Frontend (apps/web):

• sentry.ts - Sentry initialization with browser tracing and session replay
• ErrorBoundary.tsx - React error boundary with Sentry integration

Shared Library (libs/observability):

• sentry.config.ts - Shared Sentry configuration with 100% sampling
• otel.config.ts - OpenTelemetry configuration
• constants.ts - Trace/request ID header constants

Sampling Decision:

• 100% sampling for all environments (traces and profiles)
• Rationale: Full visibility needed during early development
• Can be reduced when traffic increases and limits are reached

Consequences¶

• ✅ Comprehensive error visibility with stack traces and context
• ✅ Performance monitoring for API endpoints and database queries
• ✅ Distributed tracing across frontend and backend
• ✅ Structured logs with correlation IDs for debugging
• ✅ Vendor-neutral instrumentation via OpenTelemetry
• ✅ Test endpoints for verifying observability in development
• ⚠️ Requires Sentry account (free tier available)
• ⚠️ Must initialize Sentry before other imports in main.ts
• ⚠️ 100% sampling may hit free tier limits with high traffic

Alternatives Considered¶

ADR-017: Docker + Traefik Deployment Strategy¶

Decision¶

Use Docker Compose with Traefik reverse proxy for deploying to DigitalOcean Droplets.

Architecture¶

Deployment Components¶

Traefik Configuration¶

Staging URLs¶

Pipeline Integration¶

Image Tagging Strategy¶

Database Migration Strategy¶

Prisma migrations run before container deployment:

# Executed in pipeline before docker compose up
docker compose run --rm api npx prisma migrate deploy

Rationale¶

• Traefik: Automatic TLS, Docker-native, label-based configuration
• Docker Compose: Simple, declarative, easy to understand
• SSH deployment: Direct control, no additional orchestration overhead
• Managed PostgreSQL: Reliability, automated backups, TLS built-in
• Let's Encrypt: Free, automated TLS certificates

Zero-Downtime Deployment¶

# Pull new images
docker compose pull

# Run migrations (idempotent)
docker compose run --rm api npx prisma migrate deploy

# Start new containers (Compose handles replacement)
docker compose up -d --remove-orphans

# Clean up old images
docker image prune -f

Consequences¶

• ✅ Automatic TLS certificate management
• ✅ Simple deployment via SSH + Docker Compose
• ✅ Zero-downtime container replacement
• ✅ Docker labels for routing configuration
• ✅ Consistent image tagging with pipeline ID
• ⚠️ Single droplet = single point of failure (acceptable for staging)
• ⚠️ Requires manual SSH key management in Azure DevOps

Alternatives Considered¶

ADR-018: Nx Affected Conditional Deployment Strategy¶

Decision¶

Use Nx affected to detect which applications have changed and conditionally run package/deploy stages only for affected apps.

Architecture¶

Pipeline Parameters¶

How Affected Detection Works¶

The pipeline runs pnpm nx show projects --affected --type=app to identify which applications have changed compared to the base branch (origin/main).

Scenarios:

Migration Safety¶

The deployment follows a specific order to ensure database safety:

1. Pull new images (uses latest code with new Prisma schema)
2. Stop API (only if breakingMigration=true)
3. Run migrations (using new image via docker compose run --rm)
4. Start API (after migrations complete)

Migration Types:

Rationale¶

• Efficiency: Avoid building/pushing Docker images when code hasn't changed
• Cost reduction: Fewer container registry pushes, less storage used
• Faster deployments: Only affected services are restarted
• Cleaner versioning: New version tags only when actual code changes
• Nx integration: Leverages existing monorepo tooling for dependency detection

Consequences¶

• ✅ Significantly faster CI/CD for partial changes
• ✅ Reduced container registry costs
• ✅ Cleaner deployment history (versions reflect actual changes)
• ✅ Safe migration order (migrations before restart)
• ✅ Support for breaking migrations with explicit parameter
• ✅ Override available via ForceFullVersioningAndDeployment parameter
• ⚠️ First pipeline run on new branch may show all apps affected
• ⚠️ Shared library changes trigger both app deployments (by design)
• ⚠️ breakingMigration requires manual assessment of migration type

Alternatives Considered¶

ADR-019: SimplyPrint Webhook Verification¶

Decision¶

Implement X-SP-Token header verification with timing-safe comparison for all SimplyPrint webhooks.

Implementation¶

// SimplyPrintWebhookGuard
@Injectable()
export class SimplyPrintWebhookGuard implements CanActivate {
  canActivate(context: ExecutionContext): boolean {
    const request = context.switchToHttp().getRequest();
    const token = request.headers['x-sp-token'];

    if (!this.webhookSecret) {
      this.logger.warn('SimplyPrint webhook secret not configured, skipping verification');
      return true;
    }

    if (!token) {
      throw new UnauthorizedException('Missing X-SP-Token header');
    }

    // Timing-safe comparison to prevent timing attacks
    const tokenBuffer = Buffer.from(token);
    const secretBuffer = Buffer.from(this.webhookSecret);

    if (tokenBuffer.length !== secretBuffer.length) {
      throw new UnauthorizedException('Invalid SimplyPrint webhook signature');
    }

    if (!crypto.timingSafeEqual(tokenBuffer, secretBuffer)) {
      throw new UnauthorizedException('Invalid SimplyPrint webhook signature');
    }

    return true;
  }
}

Rationale¶

• Security: Prevents forged webhook requests
• SimplyPrint standard: Uses the X-SP-Token header as per SimplyPrint documentation
• Timing-safe comparison: Prevents timing attacks on secret comparison
• Graceful degradation: Allows bypassing verification in development when secret not configured

Webhook Endpoint¶

Supported Events¶

Consequences¶

• ✅ Secure webhook endpoint
• ✅ Protection against timing attacks
• ✅ Clear event-to-status mapping
• ✅ Development-friendly (optional verification)
• ⚠️ Requires SIMPLYPRINT_WEBHOOK_SECRET environment variable

ADR-020: Hybrid Status Monitoring (Polling + Webhooks)¶

Decision¶

Implement a hybrid approach using both SimplyPrint webhooks (primary) and periodic polling (fallback) for job status monitoring.

Architecture¶

┌─────────────────────────────────────────────────────────────────┐
│                     Status Update Sources                        │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│   SimplyPrint Cloud                                              │
│         │                                                        │
│         ├─── Webhooks (Primary, Real-time) ───┐                  │
│         │    • Immediate notification         │                  │
│         │    • Event: job.started/done/failed │                  │
│         │                                     ▼                  │
│         │                            SimplyPrintService          │
│         │                                     │                  │
│         └─── Polling (Fallback, 30s) ────────►│                  │
│              • @Cron every 30 seconds         │                  │
│              • Checks queue and printers      │                  │
│              • Catches missed webhooks        ▼                  │
│                                    simplyprint.job-status-changed│
│                                               │                  │
│                                               ▼                  │
│                                       PrintJobsService           │
│                                               │                  │
│                                               ▼                  │
│                                        Database Update           │
└─────────────────────────────────────────────────────────────────┘

Implementation¶

Webhook Handler (Primary):

async handleWebhook(payload: SimplyPrintWebhookPayload): Promise<void> {
  const jobData = payload.data.job;
  if (!jobData) return;

  const newStatus = this.mapWebhookEventToStatus(payload.event);
  if (!newStatus) return;

  this.eventEmitter.emit(SIMPLYPRINT_EVENTS.JOB_STATUS_CHANGED, {
    simplyPrintJobId: jobData.uid,
    newStatus,
    printerId: payload.data.printer?.id,
    printerName: payload.data.printer?.name,
    timestamp: new Date(payload.timestamp * 1000),
  });
}

Polling Fallback:

@Cron(CronExpression.EVERY_30_SECONDS)
async pollJobStatuses(): Promise<void> {
  if (!this.pollingEnabled || this.isPolling) return;

  this.isPolling = true;
  try {
    const printers = await this.simplyPrintClient.getPrinters();

    for (const printer of printers) {
      if (printer.currentJobId && printer.status === 'printing') {
        this.eventEmitter.emit(SIMPLYPRINT_EVENTS.JOB_STATUS_CHANGED, {
          simplyPrintJobId: printer.currentJobId,
          newStatus: PrintJobStatus.PRINTING,
          printerId: printer.id,
          printerName: printer.name,
          timestamp: new Date(),
        });
      }
    }
  } finally {
    this.isPolling = false;
  }
}

Configuration¶

Rationale¶

• Reliability: Webhooks can fail due to network issues, SimplyPrint outages, or configuration problems
• Real-time updates: Webhooks provide immediate notification when status changes
• Consistency: Polling catches any status changes that webhooks might miss
• Idempotency: Status updates check current status before updating, preventing duplicate updates
• Configurable: Polling can be disabled in environments where webhooks are reliable

Status Deduplication¶

The system handles duplicate status updates gracefully:

async updateJobStatus(simplyPrintJobId: string, newStatus: PrintJobStatus): Promise<PrintJob> {
  const printJob = await this.findBySimplyPrintJobId(simplyPrintJobId);

  // Skip if status unchanged (idempotent)
  if (printJob.status === newStatus) {
    return printJob;
  }

  // Update and emit events
  // ...
}

Consequences¶

• ✅ High reliability for status updates
• ✅ Real-time updates via webhooks
• ✅ Catches missed webhooks via polling
• ✅ Configurable polling interval
• ✅ Idempotent status updates
• ⚠️ Polling adds API calls every 30 seconds (minimal overhead)
• ⚠️ Potential for slight delay if only relying on polling

Alternatives Considered¶

ADR-021: Retry Queue with Exponential Backoff¶

Decision¶

Implement a database-backed retry queue with exponential backoff and jitter for all retryable operations.

Configuration¶

Implementation¶

calculateDelay(attempt: number): number {
  let delay = initialDelayMs * Math.pow(backoffMultiplier, attempt - 1);
  delay = Math.min(delay, maxDelayMs);
  const jitter = delay * 0.1 * (Math.random() * 2 - 1);
  return Math.round(delay + jitter);
}

Supported Job Types¶

Consequences¶

• ✅ Automatic recovery from transient failures
• ✅ Prevents thundering herd with jitter
• ✅ Persistent queue survives application restarts
• ✅ Failed jobs trigger operator alerts
• ⚠️ Adds database table for queue persistence

ADR-022: Event-Driven Fulfillment Architecture¶

Decision¶

Use NestJS Event Emitter to trigger fulfillment creation when the orchestration service determines all print jobs for an order are complete.

Event Flow¶

PrintJob.COMPLETED → OrchestrationService checks all jobs
                   → If all complete: emit order.ready-for-fulfillment
                   → FulfillmentService listens and creates Shopify fulfillment

Key Events¶

Consequences¶

• ✅ Loose coupling between order management and fulfillment
• ✅ Easy to add additional listeners (logging, analytics)
• ✅ Failure in fulfillment doesn't block order completion
• ⚠️ Event ordering not guaranteed (acceptable for this use case)

ADR-023: Email Notification Strategy¶

Decision¶

Implement email notifications via SMTP using Nodemailer with Handlebars templates for operator alerts.

Notification Triggers¶

Configuration¶

SMTP_HOST=smtp.example.com
SMTP_PORT=587
SMTP_USER=notifications@forma3d.be
SMTP_PASS=***
SMTP_FROM=noreply@forma3d.be
OPERATOR_EMAIL=operator@forma3d.be
NOTIFICATIONS_ENABLED=true

Consequences¶

• ✅ Operators notified of issues requiring attention
• ✅ Email templates are maintainable and customizable
• ✅ Graceful degradation if email unavailable
• ✅ Can be disabled in development
• ⚠️ Requires SMTP configuration for each environment

ADR-024: API Key Authentication for Admin Endpoints¶

Decision¶

Implement API key authentication using a custom NestJS guard for all admin endpoints that modify order state.

Implementation¶

// ApiKeyGuard
@Injectable()
export class ApiKeyGuard implements CanActivate {
  canActivate(context: ExecutionContext): boolean {
    if (!this.isEnabled) return true; // Development mode

    const request = context.switchToHttp().getRequest();
    const providedKey = request.headers['x-api-key'];

    if (!providedKey) {
      throw new UnauthorizedException('API key required');
    }

    // Timing-safe comparison to prevent timing attacks
    if (!crypto.timingSafeEqual(Buffer.from(providedKey), Buffer.from(this.apiKey))) {
      throw new UnauthorizedException('Invalid API key');
    }

    return true;
  }
}

Protected Endpoints¶

Authentication Methods Summary¶

Configuration¶

# Generate secure API key
openssl rand -hex 32

# Environment variable
INTERNAL_API_KEY="your-secure-api-key"

Security Considerations¶

1. Timing-safe comparison: Prevents timing attacks on key validation
2. Generic error messages: Returns "API key required" or "Invalid API key" to prevent information leakage
3. Audit logging: Access attempts are logged for security monitoring
4. Development mode: If INTERNAL_API_KEY not set, endpoints are accessible (development only)

Rationale¶

• IDOR Prevention: Addresses Insecure Direct Object Reference (IDOR) vulnerabilities flagged by security scanners
• Defense in Depth: Additional layer of protection for sensitive operations
• Simple Implementation: API keys are stateless and easy to rotate
• Swagger Integration: API key documented in OpenAPI spec for easy testing

Consequences¶

• ✅ Protection against unauthorized access to admin functions
• ✅ IDOR vulnerability mitigated
• ✅ Timing-safe implementation prevents timing attacks
• ✅ Development-friendly (optional in dev mode)
• ✅ Documented in Swagger UI
• ⚠️ Requires secure key management in production
• ⚠️ Key must be rotated if compromised

Alternatives Considered¶

ADR-025: Cosign Image Signing for Supply Chain Security¶

Decision¶

Implement key-based container image signing using cosign from the Sigstore project, with attestations to track image promotions through environments.

Architecture¶

┌─────────────────────────────────────────────────────────────────────────┐
│                        Azure DevOps Pipeline                             │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                          │
│  Build & Package          Acceptance Test           Production           │
│  ┌─────────────┐          ┌─────────────┐          ┌─────────────┐      │
│  │ Build Docker│          │ Deploy to   │          │ Verify      │      │
│  │ Images      │          │ Staging     │          │ Staging     │      │
│  └──────┬──────┘          └──────┬──────┘          │ Attestation │      │
│         │                        │                 └──────┬──────┘      │
│         ▼                        ▼                        │             │
│  ┌─────────────┐          ┌─────────────┐                 ▼             │
│  │ Sign with   │          │ Run Tests   │          ┌─────────────┐      │
│  │ cosign.key  │          └──────┬──────┘          │ Deploy to   │      │
│  └──────┬──────┘                 │                 │ Production  │      │
│         │                        ▼                 └──────┬──────┘      │
│         │                 ┌─────────────┐                 │             │
│         │                 │ Create      │                 ▼             │
│         │                 │ Staging     │          ┌─────────────┐      │
│         │                 │ Attestation │          │ Create Prod │      │
│         │                 └─────────────┘          │ Attestation │      │
│         │                                          └─────────────┘      │
└─────────┼──────────────────────────────────────────────────────────────┘
          │
          ▼
┌─────────────────────────────────────┐     ┌─────────────────────┐
│   DigitalOcean Container Registry   │     │     Repository      │
│   ─────────────────────────────────│     │  ─────────────────  │
│   • Image:tag                       │     │  • cosign.pub       │
│   • Image.sig (signature)           │◄────│    (public key)     │
│   • Image.att (attestation)         │     │                     │
└─────────────────────────────────────┘     └─────────────────────┘

Implementation¶

Key-Based Signing (chosen approach):

# Azure DevOps Pipeline
- task: DownloadSecureFile@1
  name: cosignKey
  inputs:
    secureFile: 'cosign.key'

- script: |
    cosign sign \
      --key $(cosignKey.secureFilePath) \
      --annotations "build.number=$(imageTag)" \
      $(dockerRegistry)/$(imageName)@$(digest)
  env:
    COSIGN_PASSWORD: $(COSIGN_PASSWORD)

Attestation for Promotion Tracking:

{
  "_type": "https://forma3d.com/attestations/promotion/v1",
  "environment": "staging",
  "promotedAt": "2026-01-14T16:00:00+00:00",
  "build": {
    "number": "20260114160000",
    "pipeline": "forma-3d-connect",
    "commit": "abc123..."
  },
  "verification": {
    "healthCheckPassed": true,
    "acceptanceTestsPassed": true
  }
}

Key Management¶

Signing Workflow¶

Rationale¶

• Supply chain security: Cryptographic proof that images were built by the CI/CD pipeline
• Promotion tracking: Attestations provide audit trail without modifying image tags
• Tamper detection: Modifications to signed images are detectable
• Key-based over keyless: Keyless (OIDC) requires workload identity federation which adds complexity; key-based is simpler and fully functional in Azure DevOps

Why Key-Based Instead of Keyless¶

Sigstore's "keyless" signing uses OIDC tokens from identity providers (GitHub Actions, Google Cloud, etc.). While elegant, it has challenges in Azure DevOps:

We chose key-based because:

1. Azure DevOps doesn't have native OIDC integration with Sigstore
2. Device flow authentication cannot work in non-interactive CI
3. Key-based signing is well-supported and reliable

Security Considerations¶

1. Private key protection: Stored in Azure DevOps Secure Files (encrypted at rest)
2. Password protection: Private key is encrypted, password in secret variable
3. Timing-safe verification: Public key verification uses constant-time comparison
4. Key rotation: Documented procedure for rotating keys periodically (see Cosign Setup Guide)

Pipeline Parameters¶

Verification Commands¶

# Verify image signature
cosign verify --key cosign.pub \
  registry.digitalocean.com/forma-3d/forma3d-connect-api:20260114160000

# View attestations attached to image
cosign tree registry.digitalocean.com/forma-3d/forma3d-connect-api:20260114160000

# Verify and decode attestation
cosign verify-attestation --key cosign.pub --type custom \
  registry.digitalocean.com/forma-3d/forma3d-connect-api@sha256:... \
  | jq '.payload | @base64d | fromjson | .predicate'

Local Tooling¶

A script is provided to view image promotion status:

# List all images with their promotion status
./scripts/list-image-promotions.sh

# Output shows signed status and promotion level
  TAG                PROMOTION    SIGNED   UPDATED
  20260114160000     STAGING      ✓        2026-01-14
  20260114120000     none         ✓        2026-01-14

Consequences¶

• ✅ Cryptographic proof of image provenance
• ✅ Tamper detection for container images
• ✅ Audit trail for environment promotions
• ✅ Works reliably in Azure DevOps without OIDC setup
• ✅ Can verify images locally with public key
• ⚠️ Requires secure key management
• ⚠️ Keys must be rotated periodically (recommended: 6-12 months)
• ⚠️ Pipeline requires secure files and variables to be configured

Alternatives Considered¶

Related Documentation¶

• Cosign Setup Guide - Step-by-step key generation and Azure DevOps configuration
• Sigstore Documentation - Official cosign documentation
• Container Image Promotion - Usage instructions for promotion scripts

ADR-026: CycloneDX SBOM Attestations¶

Decision¶

Generate CycloneDX SBOMs using Syft and attach them as signed attestations using cosign.

Architecture¶

Each container image in the registry will have multiple attestations stored as separate OCI artifacts:

Container Image (e.g., forma3d-connect-api:20260116120000)
├── Image signature (.sig) ─────────────── cosign sign
├── SBOM attestation (.att) ────────────── cosign attest --type cyclonedx
├── Staging promotion attestation (.att) ─ cosign attest --type custom
└── Production promotion attestation (.att) cosign attest --type custom

Why CycloneDX over SPDX¶

CycloneDX was chosen because:

1. Better integration with vulnerability scanners (Grype, Trivy)
2. Native support for VEX (Vulnerability Exploitability eXchange)
3. Simpler format for debugging
4. Aligns with OWASP security practices
5. Growing adoption in DevSecOps pipelines

Implementation¶

Pipeline Step (after image signing):

- script: |
    set -e

    # Install Syft
    curl -sSfL https://raw.githubusercontent.com/anchore/syft/main/install.sh | sh -s -- -b /usr/local/bin

    # Generate CycloneDX SBOM
    syft $(dockerRegistry)/$(imageName)@$(digest) \
      --output cyclonedx-json=sbom.cdx.json

    # Attach as signed attestation
    cosign attest \
      --yes \
      --key $(cosignKey.secureFilePath) \
      --predicate sbom.cdx.json \
      --type cyclonedx \
      $(dockerRegistry)/$(imageName)@$(digest)
  displayName: 'Generate and Attach SBOM'
  env:
    COSIGN_PASSWORD: $(COSIGN_PASSWORD)

Attestation Types in Registry¶

After deployment, each image has multiple separate attestations:

Verification Commands¶

# View all attestations attached to an image
cosign tree registry.digitalocean.com/forma-3d/forma3d-connect-api:latest

# Verify and extract SBOM
cosign verify-attestation \
  --key cosign.pub \
  --type cyclonedx \
  registry.digitalocean.com/forma-3d/forma3d-connect-api@sha256:... \
  | jq -r '.payload' | base64 -d | jq '.predicate'

# Count components in SBOM
cosign verify-attestation --key cosign.pub --type cyclonedx \
  registry.digitalocean.com/forma-3d/forma3d-connect-api@sha256:... \
  | jq -r '.payload' | base64 -d | jq '.predicate.components | length'

Scanning for Vulnerabilities¶

With the SBOM attached, you can scan for vulnerabilities without pulling the full image:

# Extract SBOM and scan with Grype
cosign verify-attestation --key cosign.pub --type cyclonedx \
  registry.digitalocean.com/forma-3d/forma3d-connect-api@sha256:... \
  | jq -r '.payload' | base64 -d | jq '.predicate' > sbom.cdx.json

grype sbom:sbom.cdx.json

Rationale¶

• Supply chain transparency: SBOM provides complete visibility into image contents
• Vulnerability management: Enables scanning without pulling full images
• Compliance: Meets requirements for software transparency (US Executive Order 14028)
• Signed attestation: SBOM itself is cryptographically signed, preventing tampering
• Tool-agnostic: CycloneDX is an open standard supported by many tools

Consequences¶

• ✅ Complete visibility into image dependencies
• ✅ Enables vulnerability scanning from SBOM
• ✅ Signed attestation prevents SBOM tampering
• ✅ Supports compliance requirements
• ✅ Works with existing cosign infrastructure
• ⚠️ Adds ~10-15 seconds to pipeline per image
• ⚠️ SBOM attestation adds ~2KB manifest to registry

Alternatives Considered¶

Tools Used¶

ADR-027: TanStack Query for Server State Management¶

Decision¶

Use TanStack Query (v5.x, formerly React Query) for server state management in the dashboard.

Rationale¶

• Automatic caching: Query results are cached and deduplicated automatically
• Background refetching: Data stays fresh with configurable stale times and refetch intervals
• Loading/error states: Built-in loading, error, and success states reduce boilerplate
• Optimistic updates: Supports optimistic updates for better UX on mutations
• DevTools: React Query DevTools for debugging cache state
• TypeScript support: Excellent TypeScript integration with inferred types

Implementation¶

// Query client configuration (apps/web/src/lib/query-client.ts)
const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      staleTime: 30 * 1000, // 30 seconds
      gcTime: 5 * 60 * 1000, // 5 minutes cache
      retry: 1,
      refetchOnWindowFocus: false,
    },
  },
});

// Example hook (apps/web/src/hooks/use-orders.ts)
export function useOrders(query: OrdersQuery = {}) {
  return useQuery({
    queryKey: ['orders', query],
    queryFn: () => apiClient.orders.list(query),
  });
}

Consequences¶

• ✅ Eliminates manual loading/error state management
• ✅ Automatic cache invalidation on mutations
• ✅ Integrates well with Socket.IO for real-time updates
• ✅ Reduces API calls through intelligent caching
• ⚠️ Requires understanding of query keys for proper cache invalidation

Alternatives Considered¶

ADR-028: Socket.IO for Real-Time Dashboard Updates¶

Decision¶

Use Socket.IO for real-time WebSocket communication between backend and dashboard.

Architecture¶

Backend Events          WebSocket Gateway         React Dashboard
     │                        │                        │
     │  order.created         │                        │
     ├───────────────────────►│                        │
     │                        │  order:created         │
     │                        ├───────────────────────►│
     │                        │                        │ invalidateQueries()
     │                        │                        │ toast.success()

Implementation¶

Backend (NestJS WebSocket Gateway):

// apps/api/src/gateway/events.gateway.ts
@WebSocketGateway({ namespace: '/events' })
export class EventsGateway {
  @WebSocketServer()
  server!: Server;

  @OnEvent(ORDER_EVENTS.CREATED)
  handleOrderCreated(event: OrderEventPayload): void {
    this.server.emit('order:created', { ... });
  }
}

Frontend (React Context):

// apps/web/src/contexts/socket-context.tsx
socketInstance.on('order:created', (data) => {
  toast.success(`New order: #${data.orderNumber}`);
  queryClient.invalidateQueries({ queryKey: ['orders'] });
});

Rationale¶

• Already installed: Socket.IO server was already in dependencies for Phase 3
• Bidirectional: Supports future features like notifications and chat
• Automatic reconnection: Handles network interruptions gracefully
• Namespace support: Can separate different event channels
• Browser compatibility: Works across all modern browsers

Consequences¶

• ✅ Real-time updates without polling
• ✅ Toast notifications on important events
• ✅ Automatic TanStack Query cache invalidation
• ✅ Connection status visible in UI
• ⚠️ Requires WebSocket support in infrastructure

Alternatives Considered¶

ADR-029: API Key Authentication for Dashboard¶

Decision¶

Use API key authentication stored in browser localStorage for dashboard authentication.

Implementation¶

// apps/web/src/contexts/auth-context.tsx
const AUTH_STORAGE_KEY = 'forma3d_api_key';

export function AuthProvider({ children }: { children: ReactNode }) {
  const [apiKey, setApiKey] = useState<string | null>(() => {
    return localStorage.getItem(AUTH_STORAGE_KEY);
  });

  const login = (key: string) => {
    localStorage.setItem(AUTH_STORAGE_KEY, key);
    setApiKey(key);
  };
  // ...
}

// Protected routes redirect to /login if not authenticated
function ProtectedRoute({ children }: { children: ReactNode }) {
  const { isAuthenticated } = useAuth();
  if (!isAuthenticated) return <Navigate to="/login" replace />;
  return <>{children}</>;
}

Rationale¶

• Simplicity: No session management, token refresh, or OAuth complexity
• Consistent with API: Uses same API key authentication as backend (ADR-024)
• Offline-capable: Works without server validation on page load
• Single operator: System is used by single operator, not public users

Security Considerations¶

• API key stored in localStorage (acceptable for internal admin tool)
• Key sent via X-API-Key header for mutations
• HTTPS required in production
• Key should be rotated periodically

Consequences¶

• ✅ Simple implementation and user experience
• ✅ Consistent with existing API key guard on backend
• ✅ No additional authentication infrastructure needed
• ⚠️ API key visible in localStorage (acceptable for admin tool)
• ⚠️ No role-based access control (single admin role)

Alternatives Considered¶

ADR-030: Sendcloud for Shipping Integration¶

Decision¶

Use Sendcloud API (custom integration) rather than the native Sendcloud-Shopify app for shipping label generation and tracking.

Rationale¶

Why Sendcloud as a Platform¶

• Multi-carrier support: Single API for PostNL, DPD, DHL, UPS, and 80+ other carriers
• European focus: Strong presence in Belgium/Netherlands matching Forma3D's primary market
• Simple API: REST API with Basic Auth, parcel creation returns label PDF immediately
• Automatic tracking: Tracking numbers and URLs provided on parcel creation
• Webhook support: Status updates available via webhooks (for future enhancement)
• Competitive pricing: Pay-per-label pricing suitable for small business volumes
• Label formats: Supports A4, A6, and thermal printer formats

Why Custom API Integration vs Native Shopify-Sendcloud App¶

Sendcloud offers a native Shopify integration that automatically syncs orders. However, we chose a custom API integration for the following reasons:

Key insight: The native integration doesn't know when 3D printing is complete. An operator would need to:

1. Monitor SimplyPrint for job completion
2. Switch to Sendcloud dashboard
3. Find the order and create a label
4. Wait for tracking to sync back to Shopify

Our custom integration automates this entire workflow:

Print Jobs Complete → Auto-Generate Label → Auto-Fulfill with Tracking → Customer Notified

This reduces manual intervention from ~5 minutes per order to zero, which is critical for scaling order volumes.

Implementation¶

apps/api/src/
├── sendcloud/
│   ├── sendcloud-api.client.ts    # HTTP client with Basic Auth
│   ├── sendcloud.service.ts       # Business logic, event listener
│   ├── sendcloud.controller.ts    # REST endpoints
│   └── sendcloud.module.ts
├── shipments/
│   ├── shipments.repository.ts    # Prisma queries for Shipment
│   ├── shipments.controller.ts    # REST endpoints
│   └── shipments.module.ts

libs/api-client/src/
└── sendcloud/
    └── sendcloud.types.ts         # Typed DTOs for Sendcloud API

Event Flow¶

1. All print jobs complete → OrchestrationService emits order.ready-for-fulfillment
2. SendcloudService listens → creates parcel via Sendcloud API
3. Sendcloud returns label URL + tracking number
4. Shipment record stored in database
5. SendcloudService emits shipment.created event
6. FulfillmentService listens → creates Shopify fulfillment with tracking info
7. Customer receives email notification with tracking link

┌─────────────┐    ┌──────────────┐    ┌─────────────┐    ┌─────────────┐
│ SimplyPrint │───▶│ Orchestration│───▶│  Sendcloud  │───▶│ Fulfillment │
│  (prints)   │    │   Service    │    │   Service   │    │   Service   │
└─────────────┘    └──────────────┘    └─────────────┘    └─────────────┘
                         │                    │                  │
                         │ order.ready-       │ shipment.        │ Shopify
                         │ for-fulfillment    │ created          │ Fulfillment
                         ▼                    ▼                  ▼
                   [All jobs done]      [Label + tracking]  [Customer notified]

Consequences¶

• ✅ Single integration for multiple carriers
• ✅ Automatic label PDF generation
• ✅ Tracking information synced to Shopify fulfillments
• ✅ Dashboard displays shipment status and label download
• ⚠️ Dependent on Sendcloud uptime and API availability
• ⚠️ Limited to carriers supported by Sendcloud
• ⚠️ Requires Sendcloud account and sender address configuration

Environment Variables¶

SENDCLOUD_PUBLIC_KEY=xxx
SENDCLOUD_SECRET_KEY=xxx
SENDCLOUD_API_URL=https://panel.sendcloud.sc/api/v2
DEFAULT_SHIPPING_METHOD_ID=8
DEFAULT_SENDER_ADDRESS_ID=12345
SHIPPING_ENABLED=true

Alternatives Considered¶

ADR-031: Automated Container Registry Cleanup¶

Decision¶

Implement automated container registry cleanup that runs after each successful staging deployment and attestation. The cleanup uses attestation-based policies to determine which images to keep or delete.

Rationale¶

The Problem¶

Without automated cleanup, the DigitalOcean Container Registry accumulates images indefinitely:

• Each CI build creates new images with timestamped tags (e.g., 20260116120000)
• Signature and attestation artifacts add ~2KB per image
• Storage costs grow linearly with deployment frequency
• Old images provide no value after newer versions are verified in production

Attestation-Based Cleanup Policy¶

The cleanup leverages the cosign attestation system (ADR-025) to make intelligent retention decisions:

This policy ensures:

1. Rollback capability: Production-attested images are always available
2. Debugging support: Recent images preserved for investigation
3. Automatic garbage collection: Old staging/unsigned images removed

Integration with Health Endpoints¶

The cleanup script queries the /health endpoints to determine which images are currently deployed:

# API health endpoint returns current build number
curl https://staging-connect-api.forma3d.be/health
# Response: { "build": { "number": "20260116120000" }, ... }

This prevents accidental deletion of running containers.

Implementation¶

scripts/
└── cleanup-registry.sh    # Cleanup script with attestation checking

azure-pipelines.yml
└── RegistryMaintenance stage  # Runs on every main branch pipeline
    └── CleanupRegistry job    # Cleans manifests + triggers GC

Cleanup Script¶

The scripts/cleanup-registry.sh script:

1. Authenticates to DigitalOcean Container Registry via doctl
2. Queries health endpoints to find currently deployed image tags
3. Lists all images in the registry for each repository
4. Checks attestations using cosign verify-attestation with the public key
5. Applies retention policy based on attestation status
6. Deletes eligible images via doctl registry repository delete-manifest
7. Triggers garbage collection to reclaim storage space

Pipeline Integration¶

The cleanup runs in a dedicated RegistryMaintenance stage that executes on every main branch pipeline, even when no apps are affected (DeployStaging skipped):

- stage: RegistryMaintenance
  dependsOn: [Build, DeployStaging]
  condition: and(not(canceled()), eq(variables.isMain, true))

Cleanup Flow¶

┌─────────────────────────────────────────────────────────────────────┐
│                    RegistryMaintenance Stage                          │
│            (runs on every main branch pipeline)                      │
├─────────────────────────────────────────────────────────────────────┤
│                                                                      │
│                          CleanupRegistry                             │
│                               │                                      │
│                               ▼                                      │
│  ┌──────────────────────────────────────────────────────────────┐   │
│  │ 1. Query /health endpoints for deployed versions             │   │
│  │ 2. List all images in registry                               │   │
│  │ 3. For each image:                                           │   │
│  │    - Check if PRODUCTION attested → KEEP                     │   │
│  │    - Check if currently deployed → KEEP                      │   │
│  │    - Check if in top 5 recent → KEEP                         │   │
│  │    - Check if STAGING-only attested → DELETE                 │   │
│  │    - Check if no attestation → DELETE                        │   │
│  │ 4. Wait for any active GC, start new GC, verify completion   │   │
│  │ 5. EXIT trap ensures GC runs even if script crashes          │   │
│  └──────────────────────────────────────────────────────────────┘   │
│                                                                      │
└─────────────────────────────────────────────────────────────────────┘

Usage¶

Local Testing (Dry Run)¶

# Preview what would be deleted
./scripts/cleanup-registry.sh \
  --key cosign.pub \
  --api-url https://staging-connect-api.forma3d.be \
  --web-url https://staging-connect.forma3d.be \
  --dry-run \
  --verbose

Manual Cleanup¶

# Perform actual cleanup
./scripts/cleanup-registry.sh \
  --key cosign.pub \
  --api-url https://staging-connect-api.forma3d.be \
  --web-url https://staging-connect.forma3d.be \
  --verbose

Script Options¶

Consequences¶

• ✅ Automatic storage management reduces costs
• ✅ Attestation-based policy ensures production rollback capability
• ✅ Health endpoint check prevents deletion of running containers
• ✅ Dry-run mode enables safe testing
• ✅ Garbage collection reclaims space after deletion
• ⚠️ Requires health endpoints to return build information
• ⚠️ Dependent on cosign/doctl availability in pipeline

Alternatives Considered¶

ADR-032: Domain Boundary Separation with Interface Contracts¶

Context¶

As the application grows, we need to ensure domain boundaries are well-defined to:

1. Enable future microservices extraction without major refactoring
2. Reduce coupling between modules
3. Enable independent testing of domain logic
4. Provide distributed tracing capabilities

Decision¶

We implement domain boundary separation with the following patterns:

1. Domain Contracts Library (libs/domain-contracts)¶

Create a dedicated library containing:

• Interface definitions (IOrdersService, IPrintJobsService, etc.)
• DTOs for cross-domain communication (OrderDto, PrintJobDto, etc.)
• Symbol injection tokens (ORDERS_SERVICE, PRINT_JOBS_SERVICE, etc.)

2. Correlation ID Infrastructure¶

Add correlation ID propagation for distributed tracing:

• CorrelationMiddleware extracts/generates x-correlation-id headers
• CorrelationService uses AsyncLocalStorage for context propagation
• All domain events include correlationId, timestamp, and source fields

3. Repository Encapsulation¶

Repositories are internal implementation details:

• Modules stop exporting repositories
• Only interface tokens are exported for cross-domain communication
• Services implement domain interfaces

4. Event-Based Base Interfaces¶

Define base event interfaces that all domain events extend:

interface BaseEvent {
  correlationId: string;
  timestamp: Date;
  source: string;
}

Implementation¶

Interface Tokens Pattern¶

// In domain-contracts library
export const ORDERS_SERVICE = Symbol('IOrdersService');

export interface IOrdersService {
  findById(id: string): Promise<OrderDto | null>;
  updateStatus(id: string, status: OrderStatus): Promise<OrderDto>;
  // ... other methods
}

// In module
@Module({
  providers: [OrdersService, { provide: ORDERS_SERVICE, useExisting: OrdersService }],
  exports: [ORDERS_SERVICE], // No longer exports repository
})
export class OrdersModule {}

// In consumer service
@Injectable()
export class FulfillmentService {
  constructor(
    @Inject(ORDERS_SERVICE)
    private readonly ordersService: IOrdersService
  ) {}
}

Scope¶

Interface tokens (@Inject(ORDERS_SERVICE), etc.) enforce boundaries between domains. Services that live within the same domain module should inject the concrete class directly rather than going through the token indirection. For example, OrchestrationService injects PrintJobsService directly because both live inside the order-service; it injects IOrdersService via ORDERS_SERVICE because orders are a separate domain boundary.

Consequences¶

Positive:

• Clear domain boundaries enable future microservices extraction
• Reduced coupling between modules
• Better testability with interface-based mocking
• Distributed tracing via correlation IDs
• Repository details are now private implementation

Negative:

• Slight increase in boilerplate (interface definitions, DTOs)
• Need to maintain DTO mapping logic
• Some forwardRef() usages remain for circular retry patterns

Related ADRs¶

• ADR-007: Layered Architecture with Repository Pattern
• ADR-008: Event-Driven Internal Communication
• ADR-013: Shared Domain Library

ADR-033: Database-Backed Webhook Idempotency¶

Context¶

The original implementation used an in-memory Set<string> for webhook idempotency tracking:

private readonly processedWebhooks = new Set<string>();

This approach had critical problems:

1. Horizontal Scaling Failure: In a multi-instance deployment, each API instance has its own cache. Webhooks may be processed multiple times across instances.
2. Memory Leak: The Set grows unbounded as webhooks are processed, causing memory pressure in long-running instances.
3. Restart Data Loss: All idempotency data is lost on application restart, allowing duplicate processing during restarts.

Decision¶

Use a PostgreSQL table (ProcessedWebhook) for webhook idempotency instead of Redis or in-memory caching.

Rationale¶

• No additional infrastructure: Uses existing PostgreSQL database
• Transactional safety: Database unique constraint ensures race-condition-safe idempotency
• Simple cleanup: Scheduled job removes expired records hourly
• Debugging support: Records include metadata (webhook type, order ID, timestamps)
• Horizontal scaling: Works correctly across multiple API instances

Implementation¶

// Atomic check-and-mark using unique constraint
async isProcessedOrMark(webhookId: string, type: string): Promise<boolean> {
  try {
    await this.prisma.processedWebhook.create({
      data: { webhookId, webhookType: type, expiresAt }
    });
    return false; // First time processing
  } catch (error) {
    if (error.code === 'P2002') return true; // Already processed
    throw error;
  }
}

Database Schema¶

model ProcessedWebhook {
  id          String   @id @default(uuid())
  webhookId   String   @unique  // The Shopify webhook ID
  webhookType String            // e.g., "orders/create"
  processedAt DateTime @default(now())
  expiresAt   DateTime          // When this record can be cleaned up
  orderId     String?           // Associated order for debugging

  @@index([expiresAt])          // For cleanup job queries
  @@index([processedAt])        // For monitoring
}

Alternatives Considered¶

Consequences¶

Positive:

• ✅ Works correctly in multi-instance deployments
• ✅ Survives application restarts
• ✅ No memory leaks
• ✅ Auditable (can query processed webhooks)
• ✅ Race-condition safe via unique constraint

Negative:

• ⚠️ Slightly higher latency than in-memory (< 10ms)
• ⚠️ Requires cleanup job (runs hourly)

Related ADRs¶

• ADR-007: Layered Architecture with Repository Pattern
• ADR-021: Retry Queue for Resilient Operations

ADR-034: Docker Infrastructure Hardening (Log Rotation & Resource Cleanup)¶

Context¶

During staging operations, the server disk filled to 100% due to:

1. Unbounded Docker logs: The default json-file log driver has no size limits, causing container logs to grow indefinitely
2. Accumulated old images: Each deployment pulls new images but old versions remained on disk
3. Health check failures: When disk was full, Docker couldn't execute health checks, causing containers to be marked unhealthy and Traefik to stop routing traffic

Decision¶

Implement automated infrastructure hardening in the deployment pipeline:

1. Docker Log Rotation: Configure daemon-level log rotation with size limits
2. Aggressive Resource Cleanup: Remove unused images, volumes, and networks after each deployment
3. Separate Image Tags: Use independent version tags for API and Web to support partial deployments

Implementation¶

1. Docker Log Rotation Configuration¶

The pipeline automatically creates /etc/docker/daemon.json if missing:

{
  "log-driver": "json-file",
  "log-opts": {
    "max-size": "10m",
    "max-file": "3"
  }
}

This limits each container to:

• Maximum 10MB per log file
• Maximum 3 rotated files
• Total: 30MB per container (90MB for all 3 containers)

2. Deployment Cleanup Steps¶

After container restart, the pipeline runs:

# Remove dangling images
docker image prune -f

# Remove unused images older than 24h
docker image prune -a -f --filter "until=24h"

# Clean up unused volumes and networks
docker volume prune -f
docker network prune -f

3. Separate Image Tags¶

docker-compose.yml now uses independent tags:

api:
  image: ${REGISTRY_URL}/forma3d-connect-api:${API_IMAGE_TAG:-latest}

web:
  image: ${REGISTRY_URL}/forma3d-connect-web:${WEB_IMAGE_TAG:-latest}

This allows:

• Deploying only API without changing Web version
• Deploying only Web without changing API version
• Independent rollbacks for each service

Consequences¶

Positive:

• ✅ Prevents disk exhaustion from unbounded log growth
• ✅ Reduces disk usage by cleaning old images after deployment
• ✅ Supports independent versioning for API and Web
• ✅ Self-healing: Pipeline automatically configures log rotation if missing
• ✅ No manual intervention required

Negative:

• ⚠️ Docker daemon restart required if log rotation config is missing (brief container interruption)
• ⚠️ Log history limited to ~30MB per container (may need external log aggregation for production)

Configuration Summary¶

Related ADRs¶

• ADR-017: Docker + Traefik Deployment Strategy
• ADR-031: Automated Container Registry Cleanup

ADR-035: Progressive Web App (PWA) for Cross-Platform Access¶

Decision¶

Adopt Progressive Web App (PWA) technology for the existing React web application, replacing the planned Tauri (desktop) and Capacitor (mobile) native shell applications.

The web application will be enhanced with:

1. Web App Manifest for installability
2. Service Worker for offline caching and push notifications
3. Web Push API for real-time alerts on print job status

Rationale¶

PWA Suitability for Admin Dashboards¶

Research conducted in January 2026 confirms PWA is an ideal fit for Forma3D.Connect:

• Application type: Admin dashboards and SaaS tools are PWA's primary use case
• Feature requirements: Order management, real-time updates, and push notifications are fully supported
• Device features: No deep hardware integration (Bluetooth, NFC, sensors) required

iOS/Safari PWA Support (2026)¶

Apple has significantly improved PWA support:

Cost-Benefit Analysis¶

Estimated savings: 80-150 hours initial + ongoing maintenance reduction

Tauri/Capacitor Provided No Real Advantage¶

Both planned native apps were WebView wrappers:

• Container(desktop, "Tauri, Rust", "Native desktop shell wrapping the web application")
• Container(mobile, "Capacitor", "Mobile shell for on-the-go monitoring")

PWA provides the same experience (installable, app-like, offline capable) without:

• Separate build pipelines
• Platform-specific debugging
• App store management
• Code signing certificates

Implementation¶

Phase 1: PWA Foundation¶

1. Add vite-plugin-pwa to the web application
2. Create manifest.json with app metadata and icons
3. Configure service worker for asset caching
4. Enable HTTPS (already implemented)

{
  "name": "Forma3D.Connect",
  "short_name": "Forma3D",
  "start_url": "/",
  "display": "standalone",
  "background_color": "#ffffff",
  "theme_color": "#0066cc"
}

Phase 2: Push Notifications¶

1. Implement Web Push API in frontend
2. Add VAPID key configuration to API
3. Create notification service (integrate with existing email notifications)
4. User permission flow in dashboard settings

Phase 3: Enhanced Offline Support¶

1. IndexedDB for offline data caching
2. Background sync for queued actions
3. Optimistic UI updates

Consequences¶

Positive:

• ✅ Significant reduction in development and maintenance effort
• ✅ Single codebase, single deployment target
• ✅ Instant updates for all users (no app store delays)
• ✅ No platform-specific bugs or WebView inconsistencies
• ✅ No code signing or app store management
• ✅ Works on any device with a modern browser

Negative:

• ⚠️ iOS requires Home Screen install for full PWA features
• ⚠️ No notification sounds on iOS PWA (visual only)
• ⚠️ Limited system tray integration on desktop

Removed from Project:

• ❌ apps/desktop (Tauri) - removed from roadmap
• ❌ apps/mobile (Capacitor) - removed from roadmap

Updated Architecture¶

The C4 Container diagram has been updated to reflect the PWA-only architecture:

Before:
├── Web Application (React 19)
├── Desktop App (Tauri) [future]
├── Mobile App (Capacitor) [future]
└── API Server (NestJS)

After:
├── Progressive Web App (React 19 + PWA)
└── API Server (NestJS)

Alternatives Considered¶

Related Documents¶

• PWA Feasibility Study - Detailed research and analysis
• C4 Container Diagram - Updated architecture diagram

ADR-036: localStorage Fallback for PWA Install Detection¶

Decision¶

Use a dual detection strategy combining the getInstalledRelatedApps() API with localStorage persistence as a fallback for PWA installation detection.

Rationale¶

The Problem¶

When a user installs a PWA and later visits the same site in a regular browser:

• The browser doesn't know the PWA is installed
• The site shows "Install App" even though it's already installed
• This creates a confusing user experience

API Limitations¶

The navigator.getInstalledRelatedApps() API can detect installed PWAs, but has limitations:

Even where supported, the API can be unreliable due to:

• Scope restrictions (must be same origin/scope)
• Timing issues during page load
• Browser implementation quirks

Dual Detection Strategy¶

1. Primary: getInstalledRelatedApps() API
2. Query the browser for installed related apps

3. Works when supported and correctly configured

4. Fallback: localStorage persistence

5. Store pwa-installed: true when:
   • User installs via appinstalled event
   • App is opened in standalone mode
   • API successfully detects installation
6. Check localStorage on page load

Implementation¶

// Detection flow
useEffect(() => {
  // 1. Check standalone mode (running inside PWA)
  const isStandalone = window.matchMedia('(display-mode: standalone)').matches;
  if (isStandalone) {
    setIsInstalled(true);
    localStorage.setItem('pwa-installed', 'true');
    return;
  }

  // 2. Check localStorage fallback
  if (localStorage.getItem('pwa-installed') === 'true') {
    setIsInstalled(true);
  }

  // 3. Try getInstalledRelatedApps API
  if (navigator.getInstalledRelatedApps) {
    navigator.getInstalledRelatedApps().then((apps) => {
      if (apps.some((app) => app.platform === 'webapp')) {
        setIsInstalled(true);
        localStorage.setItem('pwa-installed', 'true');
      }
    });
  }
}, []);

// Persist on install
window.addEventListener('appinstalled', () => {
  localStorage.setItem('pwa-installed', 'true');
});

Consequences¶

Positive:

• ✅ Works across all browsers and platforms
• ✅ Provides consistent UX when switching between PWA and browser
• ✅ No false "Install App" prompts when already installed
• ✅ Gracefully degrades when API not supported

Negative:

• ⚠️ localStorage can become stale if user uninstalls PWA externally
• ⚠️ No automatic cleanup mechanism for uninstalled apps
• ⚠️ Per-browser storage (installing in Chrome won't reflect in Firefox)

Trade-off Accepted:

The risk of showing "Installed" for an uninstalled app is acceptable because:

• Users rarely uninstall and then want to reinstall immediately
• Clearing site data will reset the state
• Better UX than constantly prompting to install an already-installed app

Alternatives Considered¶

Related Documents¶

• ADR-035: Progressive Web App (PWA)
• apps/web/src/hooks/use-pwa-install.ts - Implementation

ADR-037: Keep a Changelog for Release Documentation¶

Decision¶

Adopt the Keep a Changelog format for documenting all notable changes to the project, combined with Semantic Versioning for version numbers.

Rationale¶

Why Keep a Changelog?¶

1. Human-readable: Written for humans, not machines - focuses on what matters to users
2. Standardized format: Well-known convention reduces cognitive load
3. Categorized changes: Clear sections (Added, Changed, Deprecated, Removed, Fixed, Security)
4. Release-oriented: Groups changes by version, making it easy to see what's in each release
5. Unreleased section: Accumulates changes before a release, making release notes easy

Why Semantic Versioning?¶

• MAJOR.MINOR.PATCH format communicates impact:
• MAJOR: Breaking changes
• MINOR: New features (backward compatible)
• PATCH: Bug fixes (backward compatible)
• Industry standard, well understood by developers
• Enables automated tooling and dependency management

Benefits for AI-Generated Codebase¶

This project is primarily AI-generated, making structured documentation critical:

1. Context for AI: Changelog provides history context for future AI sessions
2. Audit trail: Documents what was added/changed in each phase
3. Stakeholder communication: Non-technical stakeholders can understand progress
4. Debugging aid: When issues arise, changelog helps identify when changes were introduced

Implementation¶

File location: CHANGELOG.md in repository root

Format:

# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [Unreleased]

## [0.7.0] - 2026-01-19

### Added

- Feature description

### Changed

- Change description

### Fixed

- Bug fix description

### Security

- Security fix description

Change categories (use only those that apply):

• Added: New features
• Changed: Changes to existing functionality
• Deprecated: Features marked for removal
• Removed: Features removed
• Fixed: Bug fixes
• Security: Vulnerability fixes

Guidelines¶

1. Update with every PR: Add changelog entry as part of the PR
2. Write for humans: Describe the user impact, not implementation details
3. Link to issues/PRs: Reference related issues where helpful
4. Keep Unreleased current: Move entries to versioned section on release
5. One entry per change: Don't combine unrelated changes

Consequences¶

Positive:

• ✅ Clear release history for all stakeholders
• ✅ Standardized format reduces documentation overhead
• ✅ Supports both manual reading and automated parsing
• ✅ Integrates well with CI/CD release workflows
• ✅ Provides context for AI-assisted development sessions

Negative:

• ⚠️ Requires discipline to update with each change
• ⚠️ Can become verbose if too granular

Alternatives Considered¶

Related Documents¶

• CHANGELOG.md - The changelog file
• Semantic Versioning
• Keep a Changelog

ADR-038: Zensical for Publishing Project Documentation¶

Decision¶

Publish the repository documentation in docs/ as a static website built with Zensical.

The docs site is:

• Built from docs/ with configuration in zensical.toml
• Rendered with PlantUML pre-rendering (SVG/PNG) for existing diagrams
• Packaged as a container image forma3d-connect-docs and published to the existing container registry
• Deployed to staging behind Traefik at https://staging-connect-docs.forma3d.be
• Managed by the existing Azure DevOps pipeline using docsAffected detection

Rationale¶

• Single source of truth: docs live next to the code they describe (docs/)
• Static output: simple, fast, cacheable; no backend runtime required
• Pipeline parity: follows the same build/sign/SBOM/deploy controls as api and web
• Diagram support: preserves existing PlantUML investment via deterministic CI rendering

Implementation¶

• Config: zensical.toml (sets site name, logo, PlantUML markdown extension)
• Container build: deployment/docs/Dockerfile (builds site + serves via Nginx)
• Staging service: deployment/staging/docker-compose.yml (docs service + Traefik labels)
• CI/CD: azure-pipelines.yml
• Detect changes to docs/** or zensical.toml via docsAffected
• Build/push/sign/SBOM the forma3d-connect-docs image
• Deploy conditionally to staging

Consequences¶

Positive:

• ✅ Documentation changes can be delivered independently of API/Web
• ✅ Consistent hosting model (Traefik + container) across services
• ✅ PlantUML diagrams render in the published docs site

Negative:

• ⚠️ Docs builds can be slower due to diagram rendering (mitigated by caching)
• ⚠️ Local preview requires Zensical + Java/Graphviz (documented in developer workflow)

Alternatives Considered¶

Related Documents¶

• docs/README.md - Documentation index
• docs/05-deployment/staging-deployment-guide.md - Staging deployment guide
• Zensical: Get started
• Zensical: Logo and icons

ADR-039: Global API Key Authentication (Fail-Closed)¶

Decision¶

Enforce API key authentication globally for the API application, with explicit public exceptions.

• All HTTP routes require X-API-Key by default
• Only the following are public:
• /health/** (orchestration/monitoring probes)
• External webhook receivers (secured by their own verification guards)
• Authentication is fail-closed:
• If INTERNAL_API_KEY is not configured, non-public endpoints return an error (no “development bypass”)
• Real-time channel is also secured:
• Socket.IO /events requires the same internal API key during handshake

Rationale¶

• Default-secure posture: avoids accidental exposure in development/staging due to missing env vars
• Consistency: one policy applied across all controllers (no “forgot to add @UseGuards” drift)
• Clear separation: health/webhooks remain reachable for infrastructure and external platforms
• Parity with dashboard: matches the operator dashboard’s expectation that API access is gated

Implementation¶

• Global guard: register API key guard as an APP_GUARD in apps/api
• Public routes: introduce @Public() decorator to opt out for /health/** and webhook controllers
• Fail-closed config: if INTERNAL_API_KEY is missing, non-public HTTP routes are rejected
• WebSocket guard: add WsApiKeyGuard to EventsGateway for the /events namespace
• Webhook verification: require SIMPLYPRINT_WEBHOOK_SECRET for SimplyPrint inbound verification (fail-closed)

Consequences¶

Positive:

• ✅ Eliminates unauthenticated access to operational/admin API endpoints
• ✅ Prevents misconfiguration from silently reducing security
• ✅ Makes “secure endpoints” the default, with explicit public exceptions
• ✅ Secures both REST and realtime update channels consistently

Negative:

• ⚠️ Local development now requires configuring INTERNAL_API_KEY to use non-health endpoints
• ⚠️ Clients (dashboard, tools) must always send X-API-Key for non-public routes

Alternatives Considered¶

Related Documents¶

• ADR-024 / ADR-029 (previous API key authentication decisions)
• apps/api/src/common/guards/api-key.guard.ts
• apps/api/src/common/decorators/public.decorator.ts

ADR-040: Shopify Order Backfill for Downtime Recovery¶

Decision¶

Implement a scheduled backfill service that periodically polls Shopify's Orders API to catch any orders missed during webhook delivery failures.

Strategy:

• Store a durable since_id watermark in the SystemConfig table
• Every 5 minutes (configurable), fetch orders from Shopify with since_id pagination
• For each order not in our database, create it using the same mapping logic as webhooks
• Advance watermark only after successful processing (not before, unlike webhook path)
• Provide admin endpoints for manual backfill trigger, status check, and watermark reset

Rationale¶

• Shopify retry window is limited: Webhooks are retried only 8 times over ~4 hours (as of September 2024)
• Downtime recovery: If service is down longer than 4 hours, orders would be permanently lost without backfill
• Idempotent by design: Order creation is already deduplicated by shopifyOrderId, so re-processing is safe
• Operational visibility: Admin endpoints allow operators to trigger backfill after incidents
• Consistent mapping: Reuses the same ShopifyService.buildCreateOrderInput() method as webhooks

Implementation¶

• SystemConfigService: New service for persisting key-value configuration (watermarks, etc.)
• ShopifyBackfillService: Scheduled job with @Cron(EVERY_5_MINUTES) plus startup run
• ShopifyAdminController: Admin endpoints at /api/v1/admin/shopify/backfill/*
• Shared mapping: Extracted buildCreateOrderInput() and checkUnmappedSkus() in ShopifyService (uses findUnmappedLineItems() with product/variant ID + SKU matching)

Configuration¶

Consequences¶

Positive:

• ✅ Guarantees order recovery after extended downtime (not dependent on webhook retry window)
• ✅ Uses existing idempotency (no duplicates even with aggressive backfill)
• ✅ Operators can manually trigger backfill after incidents
• ✅ Observable via event logs and admin status endpoint

Negative:

• ⚠️ Adds Shopify API calls even during normal operation (rate limit aware)
• ⚠️ Does not reconstruct intermediate webhook events (e.g., multiple orders/updated during downtime)
• ⚠️ Initial backfill on existing system may take time to paginate through history

Alternatives Considered¶

Related Documents¶

• ADR-011 (Idempotent Webhook Processing)
• ADR-033 (Database-Backed Webhook Idempotency)
• apps/api/src/shopify/shopify-backfill.service.ts
• apps/api/src/config/system-config.service.ts

ADR-041: SimplyPrint Webhook Idempotency and Job Reconciliation¶

Decision¶

Add database-backed webhook idempotency to SimplyPrint webhook handling and implement a job reconciliation service that periodically syncs print job statuses with SimplyPrint's API.

Webhook Idempotency:

• Reuse the existing WebhookIdempotencyRepository (same as Shopify)
• Deduplicate by webhook_id from SimplyPrint payload
• Key format: simplyprint/{event} (e.g., simplyprint/job.started)

Job Reconciliation:

• Scheduled job runs every minute to check active print jobs
• Query all print jobs with simplyPrintJobId in non-terminal states (QUEUED, ASSIGNED, PRINTING)
• Compare local status with SimplyPrint's queue and printer states
• Emit JOB_STATUS_CHANGED events for discrepancies

Rationale¶

• Webhook idempotency: SimplyPrint may retry webhooks on timeout; duplicate events could cause issues
• Existing polling was limited: Only detected PRINTING status via printer polling
• History-based terminal state detection: If COMPLETED/FAILED/CANCELLED webhooks are missed, the reconciliation service queries SimplyPrint's print history API (GET /{id}/jobs/Get) after a 5-minute grace period to detect terminal states automatically
• Hybrid approach: Webhooks for real-time + reconciliation for reliability (belt and suspenders)

Implementation¶

• SimplyPrintService.handleWebhook(): Added idempotency check using WebhookIdempotencyRepository
• SimplyPrintReconciliationService: New service with @Cron(EVERY_MINUTE) that reconciles job statuses
• SimplyPrintReconciliationService.handleMissingJob(): Two-step lookup for missing jobs — getJob() (GetDetails) then getJobHistory() (history list) — with grace period (5 min), rate limiting (max 10/cycle), and escalation logging (30 min)
• SimplyPrintApiClient.getJobHistory(): Queries the print history endpoint to find completed/failed/cancelled jobs no longer in the queue or on a printer
• Direct Prisma access: Reconciliation uses PrismaService directly to avoid circular dependency with PrintJobsModule

SimplyPrint Job ID Resolution¶

SimplyPrint uses three different identifiers for the same logical job:

When a job is queued, we store created_id as both simplyPrintJobId (mutable) and simplyPrintQueueItemId (persistent). When the first job.started webhook arrives, simplyPrintJobId is updated to the job UID for fast future lookups, but simplyPrintQueueItemId is never overwritten.

Lookup chain in PrintJobsService.handleSimplyPrintStatusChange():

1. Primary: Find by simplyPrintJobId = webhook job UID
2. Fallback 1: Find by simplyPrintJobId = webhook numeric job ID
3. Fallback 2: Call GetDetails API for the job's queued.id, find by simplyPrintJobId = queued.id
4. Fallback 3: Find by simplyPrintQueueItemId = queued.id (handles re-queued jobs where simplyPrintJobId was already overwritten with the first job's UID)

Fallback 3 includes a safety check: before adopting the matched print job, it verifies that the new job UID is not already linked to another print job in the database (prevents accidentally hijacking a webhook for a different order's job).

Re-queue scenario: When SimplyPrint cancels a job and the operator clears the bed, SimplyPrint revives the same queue item and creates a new job with a different UID but the same queued.id. Fallback 3 matches via simplyPrintQueueItemId and adopts the cancelled print job, updating its simplyPrintJobId to the new UID.

Configuration¶

Consequences¶

Positive:

• ✅ Prevents duplicate event processing from webhook retries
• ✅ Catches missed PRINTING status changes via reconciliation
• ✅ Uses existing idempotency infrastructure (no new tables)
• ✅ Observable via event logs
• ✅ Re-queued jobs are automatically matched back to their original print job via persistent simplyPrintQueueItemId

Negative:

• ⚠️ Reconciliation cannot detect COMPLETED/FAILED from SimplyPrint API alone (relies on webhooks for terminal states)
• ⚠️ Adds API calls to SimplyPrint every minute (rate limit aware)
• ⚠️ Jobs "missing" from SimplyPrint are logged but not auto-updated (avoids incorrect state changes)

Alternatives Considered¶

Related Documents¶

• ADR-033 (Database-Backed Webhook Idempotency)
• ADR-040 (Shopify Order Backfill)
• apps/api/src/simplyprint/simplyprint.service.ts
• apps/api/src/simplyprint/simplyprint-reconciliation.service.ts

ADR-042: SendCloud Webhook Integration for Shipment Status Updates¶

Decision¶

Implement SendCloud webhook receiver for real-time shipment status updates with HMAC-SHA256 signature verification and a reconciliation service for backfill.

Webhook Handling:

• New endpoint: POST /webhooks/sendcloud
• Verify Sendcloud-Signature header using HMAC-SHA256
• Process parcel_status_changed events
• Database-backed idempotency using existing infrastructure

Status Mapping:

Reconciliation:

• Scheduled job runs every 5 minutes
• Polls SendCloud API (getParcel) for active shipments
• Updates status for any discrepancies found

Rationale¶

• Customer visibility: Users need to see when shipments are in transit, delivered, or failed
• Operational awareness: Operators need to know if shipments encounter problems. The shipmentStatus field on every order API response enables shipping status badges and dedicated shipping filters (Ready to Ship, In Transit, Delivered, Shipping Issues) on the orders list page.
• Existing UI ready: ShippingInfo component already displays all statuses with color-coded badges. The orders list now shows a shipping badge (with truck icon) alongside the order status badge.
• Webhook reliability: SendCloud may retry webhooks; idempotency prevents duplicate processing

Implementation¶

• SendcloudWebhookGuard: Verifies HMAC-SHA256 signature
• SendcloudWebhookService: Processes status changes, maps statuses, updates shipments
• SendcloudReconciliationService: Polls SendCloud API every 5 minutes for active shipments
• IShipmentsService.findBySendcloudParcelId(): Added to interface for parcel ID lookups
• OrderResponseDto.shipmentStatus: Every order API response includes the associated shipment status (null if no shipment exists). The OrderQueryDto supports shipmentStatus filter (by exact status) and readyToShip boolean filter (completed orders with PENDING/LABEL_CREATED/ANNOUNCED shipments).
• ShipmentStatus enum: Shared via @forma3d/domain (libs/domain/src/enums/shipment-status.ts) for use across backend and frontend.

Configuration¶

Consequences¶

Positive:

• ✅ Real-time shipment status updates in UI
• ✅ Automatic detection of delivered/failed shipments
• ✅ Backfill for missed webhooks via reconciliation
• ✅ Uses existing idempotency infrastructure
• ✅ Shipping status surfaced on orders list via shipmentStatus field — operators can filter by shipping status (Ready to Ship, In Transit, Delivered, Shipping Issues) and see badges on each order row

Negative:

• ⚠️ Requires webhook configuration in SendCloud panel
• ⚠️ Additional API calls for reconciliation (rate limit aware)
• ⚠️ Webhook secret must be configured for production security

Related Documents¶

• ADR-033 (Database-Backed Webhook Idempotency)
• ADR-041 (SimplyPrint Webhook Idempotency)
• apps/api/src/sendcloud/sendcloud-webhook.service.ts
• apps/api/src/sendcloud/sendcloud-reconciliation.service.ts

ADR-043: PWA Version Mismatch Detection¶

Decision¶

Implement automatic version mismatch detection on the Settings page that compares the cached PWA version against the server version and triggers the service worker update prompt when they differ.

Rationale¶

Problem Statement¶

The PWA displays the frontend version in two places:

1. Settings page - Shows version from cached /build-info.json
2. Sidebar footer - Shows version from cached /build-info.json

When a new version is deployed:

• The service worker checks for updates hourly
• Users may have dismissed the "Update now" prompt
• The cached version can become stale

Users visiting the Settings page to check version information should be prompted to update if running an outdated version.

Solution¶

When the user navigates to the Settings page:

1. Fetch /build-info.json from the server with cache-busting headers
2. Compare the server version against the cached PWA version
3. If versions differ, call registration.update() on the service worker
4. This triggers the "New version available!" prompt

Implementation¶

New Components¶

Architecture¶

User visits Settings page
        │
        ▼
useVersionMismatchCheck({ checkOnMount: true })
        │
        ▼
fetch('/build-info.json?_=timestamp', { cache: 'no-store' })
        │
        ▼
Compare serverVersion vs cachedVersion
        │
        ▼ (if different)
serviceWorkerContext.checkForUpdates()
        │
        ▼
registration.update() detects new SW
        │
        ▼
needRefresh = true → Update prompt shown

Cache-Busting Strategy¶

const response = await fetch(`/build-info.json?_=${Date.now()}`, {
  cache: 'no-store',
  headers: {
    'Cache-Control': 'no-cache, no-store, must-revalidate',
    Pragma: 'no-cache',
  },
});

Consequences¶

Positive:

• ✅ Users are reliably prompted to update when viewing version info
• ✅ Works even if previous update prompt was dismissed
• ✅ No polling overhead - only checks when user visits Settings
• ✅ Centralized service worker state via React Context
• ✅ Reusable hooks for future version-aware features

Negative:

• ⚠️ Extra network request on Settings page load
• ⚠️ Relies on service worker being registered

Related Documents¶

• ADR-035 (Progressive Web App for Cross-Platform Access)
• ADR-036 (localStorage Fallback for PWA Install Detection)
• apps/web/src/pwa/sw-update-prompt.tsx
• apps/web/src/pages/settings/index.tsx

ADR-044: Role-Based Access Control and Tenant-Ready Architecture¶

Decision¶

Implement in-app RBAC and tenant-ready data isolation without external identity providers (no Keycloak/OpenID Connect yet).

Key Decisions¶

1. Session-Based Authentication
2. HTTP-only cookies with express-session and PostgreSQL session store
3. Argon2id password hashing with automatic rehashing

4. Legacy API key authentication preserved for backward compatibility

5. Permission-Based Authorization

6. Permissions are string constants (e.g., orders.read, orders.write)
7. Roles are named bundles of permissions (e.g., admin, operator, viewer)
8. Users can have multiple roles; effective permissions = union of all role permissions

9. Server-side enforcement via NestJS guards (SessionGuard, PermissionsGuard)

10. Tenant-Ready Data Model

11. All tenant-owned entities include tenantId foreign key
12. Repositories enforce tenant scoping in all queries
13. Single default tenant (00000000-0000-0000-0000-000000000001) for current operations

14. Architecture supports future multi-tenant expansion

15. Security Auditing

16. AuditLog table captures security-relevant actions
17. Actor identity and tenant context attached to Sentry error reports
18. No logging of sensitive data (passwords, tokens, API keys)

Database Schema Additions¶

-- Core RBAC tables
Tenant, User, Role, Permission, UserRole, RolePermission, Session, AuditLog

-- Tenant scoping on all existing tables
Order, LineItem, PrintJob, ProductMapping, AssemblyPart, Shipment, EventLog, etc.

Implementation Details¶

Backend (NestJS)¶

• SessionGuard: Global guard that validates sessions or falls back to API key
• PermissionsGuard: Route-level guard that checks required permissions
• @CurrentUser(): Decorator to inject authenticated user into controllers
• @RequirePermissions(): Decorator to specify required permissions
• @Public(): Decorator to mark routes as public (bypass authentication)
• TenantContextService: Request-scoped service providing tenant context
• AuditService: Centralized security audit logging

Frontend (React)¶

• AuthContext: Provides user state, login/logout, permission checks
• usePermissions(): Hook for permission-based UI rendering
• ProtectedRoute: Redirects unauthenticated users to login
• PermissionGatedRoute: Hides routes based on permissions

User Management UI¶

• Location: Settings page → Administration section (visible to users with users.read permission)
• Route: /admin/users (requires users.read permission to access)
• Components:
• UserFormModal: Create/edit users with email, password, and role selection
• ChangePasswordModal: Change password for existing users
• UsersPage: User list with search, filtering, and CRUD operations
• Features:
• Create new users with email, password, and role assignment
• Edit existing user email and roles
• Change user passwords (separate modal for security)
• Deactivate/reactivate users (soft delete pattern)
• Role selection with visual indicators for selected roles
• Permission-gated UI (actions hidden if user lacks users.write)