Forma3D.Connect — Implementation Plan¶

Version: 2.6
Date: January 19, 2026
Status: Active
Related Documents: Vision | Requirements | Architecture

1. Executive Summary¶

This document outlines the phased implementation plan for Forma3D.Connect, detailing the features to be developed, their dependencies, and the recommended development sequence. The plan is designed to deliver incremental value while building toward a fully automated print-on-demand integration.

2. Implementation Phases Overview¶

Phase 0:  Foundation        [2 weeks]   → Infrastructure & Setup           ✅ COMPLETE
Phase 1:  Shopify Inbound   [3 weeks]   → Order Reception & Storage        ✅ COMPLETE
Phase 1b: Observability     [1 week]    → Sentry, OpenTelemetry, Logging   ✅ COMPLETE
Phase 1c: Staging Deployment[1 week]    → Docker, Traefik, DigitalOcean    ✅ COMPLETE
Phase 1d: Acceptance Testing[0.5 week]  → Playwright, Gherkin, CI          ✅ COMPLETE
Phase 2:  SimplyPrint Core  [3 weeks]   → Print Job Automation             ✅ COMPLETE
Phase 3:  Fulfillment Loop  [2 weeks]   → Complete Automation Cycle        ✅ COMPLETE (MVP!)
Phase 4:  Dashboard MVP     [3 weeks]   → Administrative Interface         ✅ COMPLETE
Phase 5:  Shipping          [2 weeks]   → Sendcloud Integration            ✅ COMPLETE
Phase 5b: Domain Boundaries [1 week]    → Microservices Preparation        ✅ COMPLETE
Phase 5c: Webhook Idempotency[0.5 week] → Tech Debt TD-001 Resolution      ✅ COMPLETE
Phase 5d: Frontend Tests    [1 week]    → Tech Debt TD-002 Resolution      ✅ COMPLETE
Phase 5e: JSON Schemas      [0.5 week]  → Tech Debt TD-003 Resolution      ✅ COMPLETE
Phase 5f: Shared Types      [0.5 week]  → Tech Debt TD-004 Resolution      ✅ COMPLETE
Phase 5g: Structured Logging[0.5 week]  → Tech Debt TD-005 Resolution      ✅ COMPLETE
Phase 5h: Controller Tests  [0.5 week]  → Tech Debt TD-006 Resolution      ✅ COMPLETE
Phase 5i: Domain Contracts  [0.5 week]  → Tech Debt TD-007 Resolution      ✅ COMPLETE
Phase 5j: Error Types       [0.5 week]  → Tech Debt TD-008 Resolution      ✅ COMPLETE
Phase 5k: Configuration     [0.5 week]  → Tech Debt TD-009 Resolution      ✅ COMPLETE
Phase 6:  Hardening         [2 weeks]   → Production Readiness             ✅ COMPLETE
Phase 7:  PWA               [1 week]    → Cross-Platform Mobile/Desktop    ✅ COMPLETE
                            ─────────
                            26.5 weeks total

Current Status (January 19, 2026): All phases 0-7 and tech debt phases 5e-5k complete. System is production-ready with full PWA support for cross-platform mobile and desktop access.

3. Phase 0: Foundation (Weeks 1-2)¶

3.1 Objectives¶

• Establish project infrastructure
• Set up development environment
• Create base application structure
• Configure CI/CD pipeline

3.2 Features¶

F0.1: Nx Monorepo Setup¶

Tasks:

1. Initialize Nx workspace with pnpm
2. Create apps/api - NestJS backend application
3. Create apps/web - React 19 frontend application
4. Create libs/domain - Shared domain types and entities
5. Create libs/api-client - Typed API client
6. Create libs/utils - Shared utilities
7. Configure TypeScript strict mode
8. Set up ESLint and Prettier

Deliverables:

• Working monorepo structure
• All projects compile successfully
• Lint passes on all projects

F0.2: Database Setup¶

Tasks:

1. Create prisma/schema.prisma with core entities
2. Configure database connection
3. Create initial migration
4. Set up Prisma Client generation
5. Create database seed script for development

Schema Entities:

// Core entities to create:
- Order
- LineItem
- PrintJob
- ProductMapping
- EventLog
- SystemConfig

Deliverables:

• Prisma schema defined
• Database migrations created
• Development database seeded

F0.3: CI/CD Pipeline¶

Tasks:

1. Create .github/workflows/ci.yml
2. Configure lint job
3. Configure test job
4. Configure build job
5. Set up deployment workflow (staging)

Deliverables:

• CI runs on all PRs
• Lint and build must pass to merge
• Deployment to staging automated

F0.4: Environment Configuration¶

Tasks:

1. Create .env.example with all required variables
2. Configure environment validation on startup
3. Document environment setup in README
4. Set up local development environment

Environment Variables:

# Database
DATABASE_URL=

# Shopify
SHOPIFY_SHOP_DOMAIN=
SHOPIFY_API_KEY=
SHOPIFY_API_SECRET=
SHOPIFY_ACCESS_TOKEN=
SHOPIFY_WEBHOOK_SECRET=

# SimplyPrint
SIMPLYPRINT_API_URL=
SIMPLYPRINT_API_KEY=

# Sendcloud
SENDCLOUD_PUBLIC_KEY=
SENDCLOUD_SECRET_KEY=

# App
APP_URL=
APP_PORT=
NODE_ENV=

Deliverables:

• Environment template documented
• Validation on startup
• Local development works

3.3 Phase 0 Exit Criteria¶

• Nx monorepo builds successfully ✅
• Database schema created and migrations run ✅
• CI pipeline executes on all PRs ✅
• Development environment documented ✅

Status: Phase 0 COMPLETE ✅

4. Phase 1: Shopify Inbound (Weeks 3-5)¶

4.1 Objectives¶

• Establish Shopify API connection
• Receive and store orders via webhooks
• Create product mapping system

4.2 Features¶

F1.0: OpenAPI/Swagger Documentation ✅¶

Implementation:

1. Installed @nestjs/swagger package
2. Configured Swagger in main.ts with DocumentBuilder
3. Added API decorators to all controllers:
4. @ApiTags for grouping endpoints
5. @ApiOperation for endpoint descriptions
6. @ApiResponse for response documentation
7. @ApiParam and @ApiQuery for parameter documentation
8. Added @ApiProperty decorators to all DTOs
9. Swagger UI available at /api/docs in non-production environments

Access:

• Development: http://localhost:3000/api/docs
• Staging: https://staging-api.forma3d.be/api/docs

Features:

• Interactive API testing directly from documentation
• Auto-generated OpenAPI 3.0 specification
• Request/response schema documentation
• Grouped by feature (Health, Orders, Product Mappings, Shopify Webhooks)

Deliverables:

• ✅ Swagger UI accessible at /api/docs
• ✅ All endpoints documented
• ✅ All DTOs with property descriptions
• ✅ OpenAPI JSON available at /api/docs-json

F1.0b: Aikido Security Platform Integration ✅¶

Implementation:

1. Integrated Aikido Security Platform into the development pipeline
2. Configured automated security scanning for all code changes
3. Enabled SBOM (Software Bill of Materials) generation
4. Set up monitoring dashboards for security compliance

Security Checks Enabled:

Future Enhancements:

• Code quality analysis will be enabled in a subsequent phase

Deliverables:

• ✅ Aikido integrated into CI/CD pipeline
• ✅ All security checks active and compliant
• ✅ SBOM generation enabled
• ✅ Security monitoring dashboard available

F1.1: Shopify API Client¶

Tasks:

1. Create Shopify client module in libs/api-client
2. Implement authentication (OAuth/API key)
3. Create typed DTOs for Shopify entities
4. Implement order retrieval methods
5. Implement fulfillment creation methods
6. Add request rate limiting
7. Add error handling and retry logic
8. Write unit tests

API Methods:

interface ShopifyClient {
  // Orders
  getOrder(orderId: string): Promise<ShopifyOrder>;
  getOrders(params: OrderQueryParams): Promise<ShopifyOrder[]>;

  // Fulfillment
  createFulfillment(orderId: string, data: FulfillmentInput): Promise<Fulfillment>;

  // Products
  getProducts(): Promise<ShopifyProduct[]>;
  getProductVariants(productId: string): Promise<ShopifyVariant[]>;

  // Webhooks
  registerWebhook(topic: string, address: string): Promise<Webhook>;
  listWebhooks(): Promise<Webhook[]>;
}

Deliverables:

• Typed Shopify client
• 100% test coverage for client
• Error handling documented

F1.2: Webhook Receiver¶

Tasks:

1. Create webhook controller in NestJS
2. Implement HMAC signature verification
3. Create webhook payload parsers
4. Handle orders/create events
5. Handle orders/updated events
6. Handle orders/cancelled events
7. Implement idempotency (prevent duplicate processing)
8. Add comprehensive logging
9. Write integration tests

Endpoint:

POST /api/v1/webhooks/shopify
Headers:
  X-Shopify-Topic: orders/create
  X-Shopify-Hmac-SHA256: <signature>
  X-Shopify-Shop-Domain: <shop>

Deliverables:

• Webhook endpoint operational
• HMAC verification working
• All webhook topics handled

F1.3: Order Storage Service¶

Tasks:

1. Create Order repository (Prisma)
2. Create LineItem repository
3. Create Order service with business logic
4. Implement order creation from webhook
5. Implement order status transitions
6. Implement order queries (by status, date, etc.)
7. Add event logging for all state changes
8. Write unit and integration tests

Order State Machine:

pending → processing → completed
    │         │            │
    └────────▼────────────▼
           cancelled

           failed (from any state)

Deliverables:

• Order service operational
• State transitions enforced
• Event logging working

F1.4: Product Mapping System¶

Tasks:

1. Create ProductMapping repository
2. Create ProductMapping service
3. Implement CRUD operations for mappings
4. Implement SKU-based lookup
5. Handle unmapped product detection
6. Create mapping validation
7. Write tests

Mapping Structure:

interface ProductMapping {
  id: string;
  shopifyProductId: string;
  shopifyVariantId: string;
  sku: string;
  simplyPrintFileId: string;
  printProfile: {
    material?: string;
    quality?: string;
    infill?: number;
    supports?: boolean;
  };
  isActive: boolean;
}

Deliverables:

• Mapping service operational
• Lookup by SKU working
• Unmapped products flagged

4.3 Phase 1 Exit Criteria¶

• OpenAPI/Swagger documentation available ✅
• Aikido Security Platform integrated ✅
• Shopify webhooks received and verified ✅
• Orders stored in database ✅
• Order status tracking working ✅
• Product mappings configurable ✅
• Integration tests passing ✅

Status: Phase 1 COMPLETE ✅

Implemented Components:

• apps/api/src/shopify/ — Shopify webhook receiver and API client
• apps/api/src/orders/ — Order service, repository, controller, and DTOs
• apps/api/src/product-mappings/ — Product mapping CRUD operations
• apps/api/src/event-log/ — Event logging service
• apps/api-e2e/src/ — E2E tests for orders, product-mappings, and shopify-webhooks
• Unit tests for all services with Jest
• Aikido Security Platform — Continuous security monitoring and SBOM generation

4b. Phase 1b: Sentry Observability (Week 6) ✅¶

4b.1 Objectives¶

• ✅ Integrate Sentry for error tracking and performance monitoring
• ✅ Implement structured logging with correlation IDs
• ✅ Set up OpenTelemetry-first architecture for vendor neutrality
• ✅ Add React error boundaries for graceful error handling

4b.2 Features¶

F1b.1: Backend Observability ✅¶

Tasks:

1. Create libs/observability shared library
2. Install Sentry and OpenTelemetry dependencies
3. Create instrument.ts for Sentry initialization (must run first)
4. Create ObservabilityModule with Pino logger
5. Create SentryExceptionFilter for error capture
6. Create LoggingInterceptor with correlation IDs
7. Update Prisma service with Sentry breadcrumbs
8. Configure environment variables
9. Write unit tests

Deliverables:

• Errors captured and sent to Sentry
• Performance traces recorded
• Structured JSON logs with correlation IDs
• Prisma query tracing

F1b.2: Frontend Observability ✅¶

Tasks:

1. Install @sentry/react dependencies
2. Create sentry.ts initialization file
3. Create ErrorBoundary component with Sentry integration
4. Update main.tsx to initialize Sentry and wrap app
5. Add performance monitoring for routes
6. Write unit tests

Deliverables:

• React errors captured with component stack
• Error boundary with user-friendly fallback UI
• Performance traces for page navigation

F1b.3: Structured Logging ✅¶

Tasks:

1. Install pino, pino-pretty, nestjs-pino
2. Configure Pino with JSON format for production
3. Add correlation ID generation and propagation
4. Configure sensitive field redaction
5. Update logging across all services

Deliverables:

• JSON logs with consistent structure
• Correlation IDs in all log entries
• Sensitive data automatically redacted

F1b.4: Observability Library ✅¶

Tasks:

1. Create libs/observability Nx library
2. Define Sentry configuration types and defaults
3. Define OpenTelemetry configuration
4. Export constants and utilities
5. Write unit tests

Deliverables:

• Shared observability library
• Consistent configuration across apps
• Free Tier compatible sampling defaults

4b.3 Phase 1b Exit Criteria ✅¶

• Sentry SDK integrated in backend and frontend
• Errors captured with context and stack traces
• Performance monitoring enabled
• Structured JSON logging with correlation IDs
• Prisma queries traced
• 100% sampling (adjustable when traffic increases)
• Sensitive data scrubbed from logs and Sentry
• Unit tests passing
• Documentation updated in README.md
• Test endpoints for observability verification

4c. Phase 1c: Staging Deployment (Week 7) ✅¶

4c.1 Objectives¶

• ✅ Implement automated Docker image building and publishing
• ✅ Deploy to staging environment on DigitalOcean
• ✅ Configure Traefik reverse proxy with TLS
• ✅ Establish zero-downtime deployment pipeline

4c.2 Features¶

F1c.1: Docker Image Build ✅¶

Tasks:

1. ✅ Create API Dockerfile with multi-stage build
2. ✅ Create Web Dockerfile with Nginx
3. ✅ Add Docker labels for traceability
4. ✅ Configure image tagging with pipeline instance name

Deliverables:

• ✅ API and Web Dockerfiles
• ✅ Images tagged with YYYYMMDDhhmmss format
• ✅ Labels include git commit, build date, version

F1c.2: Container Registry Push ✅¶

Tasks:

1. ✅ Configure registry authentication in pipeline
2. ✅ Push images with version tag and latest tag
3. ✅ Verify image availability in registry

Deliverables:

• ✅ Images pushed to DigitalOcean registry
• ✅ Authentication via Secure Files

F1c.3: Staging Deployment ✅¶

Tasks:

1. ✅ Create Docker Compose for staging stack
2. ✅ Configure SSH deployment in pipeline
3. ✅ Run Prisma migrations before deployment
4. ✅ Implement zero-downtime container replacement
5. ✅ Add deployment verification (acceptance test stage)

Deliverables:

• ✅ Docker Compose configuration
• ✅ Deployment script
• ✅ Automated migration handling

F1c.4: Traefik Configuration ✅¶

Tasks:

1. ✅ Create Traefik configuration
2. ✅ Configure Let's Encrypt certificate resolver
3. ✅ Set up HTTP to HTTPS redirection
4. ✅ Configure routing labels for API and Web
5. ✅ Add health check endpoints

Deliverables:

• ✅ Traefik configuration file
• ✅ Automatic TLS certificate issuance
• ✅ Secure routing for API and Web

4c.3 Staging URLs¶

4c.4 Phase 1c Exit Criteria ✅¶

• Docker images build with correct tags and labels ✅
• Images pushed to DigitalOcean Container Registry ✅
• Traefik issues TLS certificates via Let's Encrypt ✅
• Database migrations run before container deployment ✅
• Zero-downtime deployments working ✅
• API accessible at staging URL ✅
• Web accessible at staging URL ✅
• Health checks pass for all services ✅
• Pipeline deploys automatically on main/develop branch ✅

Status: Phase 1c COMPLETE ✅

Implemented Components:

• apps/api/Dockerfile — Multi-stage API Docker build
• apps/web/Dockerfile — Multi-stage Web Docker build with Nginx
• deployment/staging/docker-compose.yml — Staging stack configuration
• deployment/staging/traefik.yml — Traefik reverse proxy with ACME
• azure-pipelines.yml — Full CI/CD pipeline with Package & Deploy stages
• Acceptance Test stage with health check verification

4d. Phase 1d: Acceptance Testing (Week 7.5) ✅¶

4d.1 Objectives¶

• ✅ Implement automated acceptance testing with Playwright and Gherkin
• ✅ Create readable Given/When/Then test scenarios
• ✅ Integrate acceptance tests into Azure DevOps pipeline
• ✅ Ensure deployment verification before proceeding

4d.2 Features¶

F1d.1: Acceptance Test Project ✅¶

Tasks:

1. Create apps/acceptance-tests Nx project
2. Install Playwright and Gherkin dependencies
3. Configure Playwright for BDD testing
4. Create project.json with test targets
5. Set up environment configuration

Deliverables:

• Acceptance test project structure
• Playwright + Gherkin integration working
• Test targets for local and staging

F1d.2: Gherkin Feature Files ✅¶

Tasks:

1. Create health-check.feature for API health verification
2. Create api-docs.feature for Swagger UI verification
3. Create web-dashboard.feature for frontend smoke tests
4. Apply appropriate tags (@smoke, @critical, @api, @web)

Deliverables:

• Feature files with Given/When/Then scenarios
• Scenarios readable by non-developers
• Tags for test filtering

F1d.3: Playwright Step Definitions ✅¶

Tasks:

1. Create step definitions for health check scenarios
2. Create step definitions for API documentation scenarios
3. Create step definitions for web dashboard scenarios
4. Create support files (world context, hooks)
5. Implement screenshot capture on failure

Deliverables:

• All Gherkin steps implemented
• API and browser test support
• Failure screenshot capture

F1d.4: Pipeline Integration ✅¶

Tasks:

1. Add AcceptanceTests stage to azure-pipelines.yml
2. Install Playwright browsers in CI
3. Run tests against staging environment
4. Publish JUnit results to Azure DevOps
5. Publish HTML report as artifact

Deliverables:

• Acceptance test stage in pipeline
• Test results visible in Azure DevOps UI
• HTML report as pipeline artifact

4d.3 Phase 1d Exit Criteria¶

• Acceptance test project created with Playwright + Gherkin ✅
• Feature files written in Given/When/Then format ✅
• Step definitions implemented with Playwright ✅
• Tests pass against staging environment ✅
• Azure DevOps pipeline includes acceptance test stage ✅
• Test results published to Azure DevOps UI ✅
• Pipeline fails if acceptance tests fail ✅

Status: Phase 1d COMPLETE ✅

Phase 1d Implementation Notes (Completed 2026-01-14):

Feature Files: - health-check.feature — API health verification - api-docs.feature — Swagger UI verification - web-dashboard.feature — Frontend smoke tests - orders-management.feature — Order management UI tests - product-mappings.feature — Product mapping tests - activity-logs.feature — Activity logs tests - fulfillment.feature — Fulfillment flow tests - cancellation.feature — Cancellation flow tests - Plus 6 additional feature files for comprehensive coverage

5. Phase 2: SimplyPrint Core (Weeks 8-10) ✅¶

5.1 Objectives¶

• ✅ Establish SimplyPrint API connection
• ✅ Automate print job creation
• ✅ Monitor print job status

5.2 Features¶

F2.1: SimplyPrint API Client ✅¶

Tasks:

1. Research SimplyPrint API documentation thoroughly
2. Create SimplyPrint client module
3. Implement authentication
4. Create typed DTOs for SimplyPrint entities
5. Implement job creation methods
6. Implement job status retrieval
7. Implement job cancellation
8. Implement printer status retrieval
9. Implement file/queue listing
10. Add error handling and retry logic
11. Write unit tests with mocks

API Methods (Expected):

interface SimplyPrintClient {
  // Authentication
  authenticate(): Promise<void>;

  // Files
  getFiles(): Promise<PrintFile[]>;
  getFileById(fileId: string): Promise<PrintFile>;

  // Print Jobs
  createJob(params: CreateJobParams): Promise<PrintJob>;
  getJob(jobId: string): Promise<PrintJob>;
  getJobStatus(jobId: string): Promise<JobStatus>;
  cancelJob(jobId: string): Promise<void>;

  // Queue
  getQueue(): Promise<QueuedJob[]>;

  // Printers
  getPrinters(): Promise<Printer[]>;
  getPrinterStatus(printerId: string): Promise<PrinterStatus>;
}

Deliverables:

• Typed SimplyPrint client
• Test coverage with mocks
• Error handling documented

F2.2: Print Job Creation Service ✅¶

Tasks:

1. Create PrintJob repository
2. Create PrintJob service
3. Implement job creation workflow:
4. Lookup product mapping
5. Retrieve file reference
6. Create job in SimplyPrint
7. Store job reference locally
8. Handle creation failures
9. Implement retry logic for transient failures
10. Add event logging
11. Write tests

Job Creation Flow:

Order Line Item
      │
      ▼
ProductMapping Lookup
      │
      ├─ Not Found → Flag for Review
      │
      ▼
SimplyPrint Job Create
      │
      ├─ Success → Store PrintJob
      │
      └─ Failure → Retry / Alert

Deliverables:

• Print jobs created automatically
• Failures handled gracefully
• Event logging complete

F2.3: Print Job Status Monitor ✅¶

Tasks:

1. Determine monitoring method:
2. Option A: SimplyPrint webhooks (preferred)
3. Option B: Polling-based monitoring
4. Implement webhook receiver OR polling scheduler
5. Create status update handler
6. Update local PrintJob records
7. Trigger downstream events on status change
8. Handle completion events
9. Handle failure events
10. Write tests

Status States:

enum PrintJobStatus {
  QUEUED = 'queued',
  ASSIGNED = 'assigned', // Assigned to printer
  PRINTING = 'printing', // Currently printing
  COMPLETED = 'completed', // Successfully finished
  FAILED = 'failed', // Error during print
  CANCELLED = 'cancelled', // Manually cancelled
}

Polling Configuration (if needed):

{
  interval: 30000,        // 30 seconds
  activeJobInterval: 10000, // 10 seconds for active prints
  maxConcurrentPolls: 10
}

Deliverables:

• Status changes detected within 60 seconds
• All status transitions handled
• Downstream events triggered

F2.4: Order-PrintJob Orchestration ✅¶

Tasks:

1. Create orchestration service
2. Track all line items for an order
3. Detect when all items are printed
4. Handle partial completion scenarios
5. Update order status to ready-for-fulfillment
6. Emit fulfillment trigger event
7. Write tests

Orchestration Logic:

On PrintJob Status Change:
  1. Update LineItem status
  2. Check if all LineItems for Order are complete
  3. If all complete:
     - Update Order status to 'completed'
     - Emit 'order.ready-for-fulfillment' event
  4. If any failed:
     - Update Order status to 'partially-failed'
     - Alert operator

Deliverables:

• Order completion detected
• Fulfillment event emitted
• Partial failures handled

5.3 Phase 2 Exit Criteria ✅¶

• Print jobs created in SimplyPrint from orders ✅
• Print status changes tracked ✅
• Order completion detected ✅
• Fulfillment events triggered ✅
• End-to-end flow working (order → print job) ✅

Status: Phase 2 COMPLETE ✅

Implemented Components:

• apps/api/src/simplyprint/ — SimplyPrint API client and webhook integration
• simplyprint-api.client.ts — Typed API client with HTTP Basic Auth
• simplyprint.service.ts — Status monitoring (webhook + polling)
• simplyprint-webhook.controller.ts — Webhook receiver endpoint
• guards/simplyprint-webhook.guard.ts — Token verification
• dto/ — Request/response DTOs
• apps/api/src/print-jobs/ — Print job management
• print-jobs.service.ts — Job creation and status updates
• print-jobs.repository.ts — Database operations
• print-jobs.controller.ts — REST API endpoints
• events/print-job.events.ts — Event definitions
• apps/api/src/orchestration/ — Order-job coordination
• orchestration.service.ts — Tracks job completion per order
• libs/api-client/src/simplyprint/ — Shared types for SimplyPrint API

API Endpoints Added:

• GET /api/v1/print-jobs — List print jobs with filters
• GET /api/v1/print-jobs/active — Get active jobs
• GET /api/v1/print-jobs/:id — Get job details
• GET /api/v1/print-jobs/order/:orderId — Get jobs for order
• POST /api/v1/print-jobs/:id/cancel — Cancel a job
• POST /api/v1/print-jobs/:id/retry — Retry a failed job
• POST /webhooks/simplyprint — SimplyPrint webhook receiver

6. Phase 3: Fulfillment Loop (Weeks 9-10)¶

6.1 Objectives¶

• Automate Shopify fulfillment creation
• Complete the automation loop
• Handle edge cases

6.2 Features¶

F3.1: Shopify Fulfillment Service¶

Tasks:

1. Create Fulfillment service
2. Listen for 'order.ready-for-fulfillment' events
3. Build fulfillment payload with all line items
4. Call Shopify fulfillment API
5. Handle fulfillment creation errors
6. Store fulfillment reference
7. Update order to 'fulfilled' status
8. Write tests

Fulfillment Creation:

async function createFulfillment(order: Order): Promise<void> {
  const fulfillment = await shopifyClient.createFulfillment(order.shopifyOrderId, {
    line_items: order.lineItems.map((li) => ({
      id: li.shopifyLineItemId,
      quantity: li.quantity,
    })),
    notify_customer: true,
    tracking_info: order.trackingInfo, // Added in Phase 5
  });

  await orderService.markFulfilled(order.id, fulfillment.id);
}

Deliverables:

• Fulfillment created automatically
• Customer notified via Shopify
• Order marked fulfilled

F3.2: Cancellation Handling¶

Tasks:

1. Handle orders/cancelled webhook
2. Find associated print jobs
3. Cancel queued/pending jobs in SimplyPrint
4. Flag in-progress jobs for operator review
5. Update local order status
6. Write tests

Cancellation Logic:

On Order Cancelled:
  For each PrintJob:
    If status == 'queued':
      Cancel in SimplyPrint
      Update local status to 'cancelled'
    If status == 'printing':
      Flag for operator review
      Notify operator
    If status == 'completed':
      Log warning (already printed)

Deliverables:

• Cancellations handled appropriately
• Queued jobs cancelled
• In-progress jobs flagged

F3.3: Error Recovery Service¶

Tasks:

1. Create retry queue system
2. Implement exponential backoff
3. Create failed job recovery process
4. Create failed fulfillment recovery process
5. Configure max retry attempts
6. Alert after final failure
7. Write tests

Retry Configuration:

{
  maxRetries: 5,
  initialDelay: 1000,      // 1 second
  maxDelay: 3600000,       // 1 hour
  backoffMultiplier: 2,
  retryableErrors: [
    'TIMEOUT',
    'RATE_LIMITED',
    'SERVICE_UNAVAILABLE'
  ]
}

Deliverables:

• Transient failures auto-recovered
• Permanent failures alerted
• Retry metrics available

F3.4: Event Bus and Notifications¶

Tasks:

1. Set up NestJS EventEmitter
2. Define event types and payloads
3. Create event handlers for key flows
4. Implement email notification service
5. Send alerts on critical failures
6. Write tests

Events:

type Events = {
  'order.created': OrderCreatedEvent;
  'order.updated': OrderUpdatedEvent;
  'order.ready-for-fulfillment': OrderReadyEvent;
  'order.fulfilled': OrderFulfilledEvent;
  'order.failed': OrderFailedEvent;
  'printjob.created': PrintJobCreatedEvent;
  'printjob.status-changed': PrintJobStatusChangedEvent;
  'printjob.completed': PrintJobCompletedEvent;
  'printjob.failed': PrintJobFailedEvent;
  'system.error': SystemErrorEvent;
};

Deliverables:

• Event system operational
• Notifications sent on failures
• Events logged

6.3 Phase 3 Exit Criteria¶

• Complete automation loop: Order → Print → Fulfill ✅
• Cancellation handling working ✅
• Error recovery operational ✅
• Notifications sent on failures ✅
• End-to-end automated flow tested ✅

Status: Phase 3 COMPLETE — 🎯 MVP ACHIEVED ✅

Phase 3 Implementation Notes (Completed 2026-01-14):

7. Phase 4: Dashboard MVP (Weeks 11-13)¶

7.1 Objectives¶

• Create administrative web interface
• Enable monitoring and manual overrides
• Configure product mappings

7.2 Features¶

F4.1: Dashboard Foundation¶

Tasks:

1. Set up React 19 with Vite
2. Configure Tailwind CSS
3. Set up React Router
4. Create layout components (sidebar, header)
5. Create authentication flow (simple auth)
6. Set up TanStack Query
7. Create base API client

Pages:

/                   → Dashboard overview
/orders             → Order list
/orders/:id         → Order detail
/print-jobs         → Print job list
/mappings           → Product mappings
/settings           → System configuration
/logs               → Activity logs

Deliverables:

• Dashboard shell running
• Authentication working
• Navigation functional

F4.2: Order Management UI¶

Tasks:

1. Create Order List page
2. Table with status, date, customer, items
3. Filtering by status
4. Searching by order number
5. Pagination
6. Create Order Detail page
7. Order information display
8. Line items with print job status
9. Event timeline
10. Action buttons
11. Implement real-time updates via Socket.IO
12. Create manual action handlers:
13. Retry failed jobs
14. Cancel pending jobs
15. Force fulfill order

Order List Columns: | Column | Description | |--------|-------------| | Order # | Shopify order number | | Date | Order creation date | | Customer | Customer name | | Items | Number of line items | | Status | Current processing status | | Actions | Quick action buttons |

Deliverables:

• Order list functional
• Order detail with full info
• Manual actions working

F4.3: Product Mapping UI¶

Tasks:

1. Create Mapping List page
2. Show all Shopify products
3. Indicate mapped/unmapped status
4. Create Mapping Editor
5. Select SimplyPrint file
6. Configure print profile
7. Activate/deactivate mapping
8. Implement sync with Shopify products
9. Show unmapped products alert

Deliverables:

• All products visible
• Mappings configurable
• Unmapped products highlighted

F4.4: Real-Time Updates¶

Tasks:

1. Set up Socket.IO on backend
2. Create Socket.IO client in React
3. Emit events on order/job status changes
4. Update UI in real-time
5. Handle reconnection gracefully

Events:

// Server → Client
'order:updated'; // Order status changed
'printjob:updated'; // Print job status changed
'notification'; // Alert message

Deliverables:

• Dashboard updates in real-time
• No manual refresh needed
• Connection status visible

F4.5: Activity Logs UI¶

Tasks:

1. Create Logs page
2. Display events chronologically
3. Filter by type, severity, date
4. Link to related orders/jobs
5. Export capability

Deliverables:

• Logs viewable in dashboard
• Filtering working
• Export available

7.3 Phase 4 Exit Criteria¶

• Dashboard accessible and authenticated ✅
• Order management fully functional ✅
• Product mappings configurable via UI ✅
• Real-time updates working ✅
• Activity logs available ✅

Status: Phase 4 COMPLETE ✅

Phase 4 Implementation Notes (Completed 2026-01-14):

Frontend Libraries Added: - @headlessui/react — Accessible UI primitives - @heroicons/react — Beautiful SVG icons - date-fns — Date formatting - clsx — Conditional classNames - react-hot-toast — Toast notifications - socket.io-client — WebSocket client - @tanstack/react-query-devtools — React Query debugging

8. Phase 5: Shipping Integration (Weeks 14-15)¶

8.1 Objectives¶

• Integrate Sendcloud for shipping labels
• Automate tracking information sync
• Complete end-to-end flow

8.2 Features¶

F5.1: Sendcloud API Client¶

Tasks:

1. Create Sendcloud client module
2. Implement authentication
3. Create typed DTOs
4. Implement parcel creation
5. Implement label retrieval
6. Implement tracking retrieval
7. Write tests

API Methods:

interface SendcloudClient {
  createParcel(data: ParcelInput): Promise<Parcel>;
  getLabel(parcelId: number): Promise<LabelPDF>;
  getTracking(parcelId: number): Promise<TrackingInfo>;
  getShippingMethods(): Promise<ShippingMethod[]>;
}

Deliverables:

• Sendcloud client functional ✅
• Label generation working ✅
• Tracking retrieval working ✅

Implementation Notes (January 16, 2026):

• apps/api/src/sendcloud/sendcloud-api.client.ts — Sendcloud HTTP client with Basic Auth
• libs/api-client/src/sendcloud/sendcloud.types.ts — Typed DTOs for Sendcloud API
• Supports: createParcel, getParcel, getLabel, cancelParcel, getShippingMethods, getTracking

F5.2: Shipping Label Generation¶

Tasks:

1. Create Shipping service
2. Trigger label generation on order completion
3. Select appropriate shipping method
4. Store parcel/tracking info
5. Attach tracking to Shopify fulfillment
6. Handle label generation errors
7. Write tests

Deliverables:

• Labels generated automatically ✅
• Tracking attached to fulfillment ✅
• Errors handled ✅

Implementation Notes (January 16, 2026):

• apps/api/src/sendcloud/sendcloud.service.ts — Business logic for shipping
• apps/api/src/shipments/shipments.repository.ts — Database operations for Shipment model
• Listens to order.ready-for-fulfillment event to auto-generate labels
• Emits shipment.created event when label is ready
• FulfillmentService listens to shipment.created (when shipping enabled) to ensure tracking is included in Shopify fulfillment
• Uses retry queue for transient failures (SHIPMENT job type)

Why Custom API Integration vs Native Sendcloud-Shopify App:

We chose a custom Sendcloud API integration over the native Sendcloud-Shopify app because: - The native integration requires manual label creation in Sendcloud's dashboard - It doesn't know when 3D printing is complete - Our custom integration automates the entire flow: Print Complete → Label → Fulfill - See ADR-030 for detailed comparison

F5.3: Shipping Dashboard UI¶

Tasks:

1. Add shipping info to Order Detail
2. Show tracking number and status
3. Download label button
4. Regenerate label option
5. Shipping method override

Deliverables:

• Shipping info visible ✅
• Labels downloadable ✅
• Override available ✅

Implementation Notes (January 16, 2026):

• apps/web/src/components/orders/shipping-info.tsx — ShippingInfo component
• apps/web/src/hooks/use-shipments.ts — React Query hooks for shipping
• Shipping section added to Order Detail page (/orders/:id)
• Supports: view shipment, download label, regenerate label, cancel shipment, select shipping method

8.3 Phase 5 Exit Criteria¶

• Shipping labels generated automatically ✅
• Tracking synced to Shopify ✅
• Labels downloadable from dashboard ✅
• Complete flow: Order → Print → Label → Fulfill ✅

Status: Phase 5 COMPLETE ✅

8b. Phase 5b: Domain Boundary Separation (Week 16) ✅¶

8b.1 Objectives¶

• ✅ Prepare modular monolith for potential microservices extraction
• ✅ Establish clean domain boundaries with interface contracts
• ✅ Add correlation ID infrastructure for distributed tracing
• ✅ Encapsulate repositories as internal implementation details

8b.2 Features¶

F5b.1: Correlation ID Infrastructure ✅¶

Tasks:

1. ✅ Create CorrelationMiddleware for HTTP request handling
2. ✅ Create CorrelationService using AsyncLocalStorage
3. ✅ Extract/generate x-correlation-id headers
4. ✅ Update all domain events to include correlation metadata
5. ✅ Write unit tests

Deliverables:

• ✅ Correlation IDs propagated across all requests
• ✅ Events include correlationId, timestamp, source

F5b.2: Domain Contracts Library ✅¶

Tasks:

1. ✅ Create libs/domain-contracts Nx library
2. ✅ Define service interfaces (IOrdersService, IPrintJobsService, etc.)
3. ✅ Define DTOs for cross-domain communication
4. ✅ Define Symbol injection tokens
5. ✅ Write exports and barrel files

Deliverables:

• ✅ libs/domain-contracts library with all interfaces
• ✅ DTOs: OrderDto, LineItemDto, PrintJobDto, etc.
• ✅ Tokens: ORDERS_SERVICE, PRINT_JOBS_SERVICE, etc.

F5b.3: Repository Encapsulation ✅¶

Tasks:

1. ✅ Update modules to export interface tokens instead of repositories
2. ✅ Refactor services to implement domain interfaces
3. ✅ Update consumers to inject via interface tokens
4. ✅ Update tests to use interface mocks

Deliverables:

• ✅ Repositories are internal implementation details
• ✅ Cross-domain communication via interfaces only

F5b.4: Service Refactoring ✅¶

Tasks:

1. ✅ Update FulfillmentService to use IOrdersService
2. ✅ Update OrchestrationService to use interfaces
3. ✅ Update CancellationService to use interfaces
4. ✅ Update SendcloudService to use interfaces
5. ✅ Update all test files for new patterns
6. ✅ Verify all 355 tests pass

Deliverables:

• ✅ All services use interface-based dependencies
• ✅ All tests passing (355/355)

8b.3 Phase 5b Exit Criteria¶

• Correlation IDs propagated in all requests ✅
• Domain contracts library created with interfaces and DTOs ✅
• Repositories encapsulated (not exported from modules) ✅
• Services refactored to use interface dependencies ✅
• All tests passing (355/355) ✅
• ADR-032 documented ✅

Status: Phase 5b COMPLETE ✅

Phase 5b Implementation Notes (Completed 2026-01-17):

8c. Phase 5c: Webhook Idempotency (Week 16.5) ✅¶

8c.1 Objectives¶

• ✅ Resolve critical technical debt TD-001
• ✅ Replace in-memory webhook idempotency with database-backed solution
• ✅ Ensure horizontal scaling compatibility
• ✅ Implement automatic cleanup of expired records

8c.2 Features¶

F5c.1: Database-backed Webhook Idempotency ✅¶

Tasks:

1. ✅ Create ProcessedWebhook Prisma model with unique constraint
2. ✅ Create webhook-idempotency.repository.ts for database operations
3. ✅ Refactor shopify.service.ts to use repository
4. ✅ Add 24-hour TTL for idempotency records
5. ✅ Write unit tests

Deliverables:

• ✅ ProcessedWebhook table in database
• ✅ Race-condition safe with database unique constraint
• ✅ Horizontal scaling compatible

F5c.2: Webhook Cleanup Service ✅¶

Tasks:

1. ✅ Create webhook-cleanup.service.ts with NestJS scheduler
2. ✅ Configure hourly cleanup job
3. ✅ Add logging for cleanup operations
4. ✅ Write unit tests

Deliverables:

• ✅ Hourly scheduled cleanup job
• ✅ No memory leak from unbounded record growth

8c.3 Phase 5c Exit Criteria¶

• ProcessedWebhook model created ✅
• Repository encapsulates database operations ✅
• Shopify service refactored to use repository ✅
• Cleanup job removes records older than 24 hours ✅
• All tests passing ✅
• TD-001 marked resolved in technical debt register ✅

Status: Phase 5c COMPLETE ✅

Phase 5c Implementation Notes (Completed 2026-01-17):

8d. Phase 5d: Frontend Test Coverage (Week 17) ✅¶

8d.1 Objectives¶

• ✅ Resolve critical technical debt TD-002
• ✅ Establish frontend testing infrastructure with Vitest
• ✅ Achieve 60%+ test coverage for high-priority components
• ✅ Integrate frontend tests into CI/CD pipeline

8d.2 Features¶

F5d.1: Vitest Configuration ✅¶

Tasks:

1. ✅ Create vitest.config.ts with jsdom environment
2. ✅ Configure test setup file with jest-dom matchers
3. ✅ Add coverage thresholds (60% statements/functions/lines)
4. ✅ Configure CI reporters (JUnit, Cobertura)
5. ✅ Install dependencies (@testing-library/react, @vitest/coverage-v8)

Deliverables:

• ✅ apps/web/vitest.config.ts configuration
• ✅ apps/web/src/test/setup.ts test setup
• ✅ apps/web/src/test/test-utils.tsx custom render utilities

F5d.2: MSW API Mocking ✅¶

Tasks:

1. ✅ Create mock data factories for all API entities
2. ✅ Define request handlers for all API endpoints
3. ✅ Configure MSW server lifecycle in test setup
4. ✅ Add error response handlers

Deliverables:

• ✅ apps/web/src/test/mocks/handlers.ts API handlers
• ✅ apps/web/src/test/mocks/server.ts MSW server

F5d.3: Hook and Context Tests ✅¶

Tasks:

1. ✅ Test use-orders.ts hook (data fetching, mutations)
2. ✅ Test use-dashboard.ts hook (dashboard stats)
3. ✅ Test use-mappings.ts hook (CRUD operations)
4. ✅ Test use-logs.ts hook (filtering, pagination)
5. ✅ Test use-health.ts hook (health checks)
6. ✅ Test use-shipments.ts hook (shipping operations)
7. ✅ Test auth-context.tsx (login, logout, persistence)

Deliverables:

• ✅ 6 hook test files (61 tests)
• ✅ 1 context test file (17 tests)

F5d.4: UI Component Tests ✅¶

Tasks:

1. ✅ Test Badge component (variants, sizes)
2. ✅ Test Button component (variants, loading, disabled)
3. ✅ Test Card component (composition patterns)
4. ✅ Test Loading component (states, overlays)
5. ✅ Test Pagination component (navigation, edge cases)
6. ✅ Test API client (error handling, request construction)

Deliverables:

• ✅ 5 UI component test files (85 tests)
• ✅ 1 API client test file (37 tests)

8d.3 Phase 5d Exit Criteria¶

• Vitest configured with React Testing Library ✅
• MSW handlers for all API endpoints ✅
• 200 frontend tests created ✅
• 60%+ coverage threshold met ✅
• CI/CD pipeline integration (JUnit + Cobertura) ✅
• TD-002 marked resolved in technical debt register ✅

Status: Phase 5d COMPLETE ✅

Phase 5d Implementation Notes (Completed 2026-01-17):

Test Summary:

8e. Phase 5e: Typed JSON Schemas (Week 20.5) ✅¶

8e.1 Objectives¶

• ✅ Resolve technical debt TD-003 (Untyped JSON Columns)
• ✅ Add Zod schemas for all JSON database columns
• ✅ Implement runtime validation at read/write boundaries

8e.2 Features¶

8e.3 Exit Criteria¶

• All JSON columns have Zod schemas ✅
• Validation at repository boundaries ✅
• Schema tests passing ✅
• TD-003 marked resolved ✅

Status: Phase 5e COMPLETE ✅

8f. Phase 5f: Shared API Types (Week 21) ✅¶

8f.1 Objectives¶

• ✅ Resolve technical debt TD-004 (Duplicated DTO Definitions)
• ✅ Create shared API types in libs/domain-contracts
• ✅ Eliminate duplicate type definitions between frontend and backend

8f.2 Features¶

8f.3 Exit Criteria¶

• All API types in libs/domain-contracts ✅
• Frontend uses shared types ✅
• Backend DTOs implement interfaces ✅
• TD-004 marked resolved ✅

Status: Phase 5f COMPLETE ✅

8g. Phase 5g: Structured Logging (Week 21.5) ✅¶

8g.1 Objectives¶

• ✅ Resolve technical debt TD-005 (Console Logging in Production)
• ✅ Replace console.log with structured NestJS Logger
• ✅ Add ESLint rule to prevent future console usage

8g.2 Features¶

8g.3 Exit Criteria¶

• No console.log in production code ✅
• ESLint rule enforced ✅
• Logging guidelines documented ✅
• TD-005 marked resolved ✅

Status: Phase 5g COMPLETE ✅

8h. Phase 5h: Controller Tests (Week 22) ✅¶

8h.1 Objectives¶

• ✅ Resolve technical debt TD-006 (Missing Controller Tests)
• ✅ Add unit tests for all 10 backend controllers
• ✅ Test request validation, guards, and error handling

8h.2 Features¶

8h.3 Exit Criteria¶

• All 10 controllers have tests ✅
• API key guards verified ✅
• Request validation tested ✅
• TD-006 marked resolved ✅

Status: Phase 5h COMPLETE ✅

8i. Phase 5i: Domain Contract Cleanup (Week 22.5) ✅¶

8i.1 Objectives¶

• ✅ Resolve technical debt TD-007 (Incomplete Domain Contract Usage)
• ✅ Remove Prisma type leakage from domain layer
• ✅ Create clean domain entity interfaces

8i.2 Features¶

8i.3 Exit Criteria¶

• No Prisma imports in libs/domain ✅
• Domain entities defined ✅
• Converters at repository boundary ✅
• TD-007 marked resolved ✅

Status: Phase 5i COMPLETE ✅

8j. Phase 5j: Typed Error Hierarchy (Week 23) ✅¶

8j.1 Objectives¶

• ✅ Resolve technical debt TD-008 (Missing Error Type Definitions)
• ✅ Create typed error classes with HTTP status codes
• ✅ Implement global exception filter

8j.2 Features¶

8j.3 Exit Criteria¶

• Error hierarchy created ✅
• Consistent error response format ✅
• Services use typed errors ✅
• TD-008 marked resolved ✅

Status: Phase 5j COMPLETE ✅

8k. Phase 5k: Configuration Externalization (Week 23.5) ✅¶

8k.1 Objectives¶

• ✅ Resolve technical debt TD-009 (Hardcoded Configuration Values)
• ✅ Externalize all configuration to environment variables
• ✅ Validate configuration at startup

8k.2 Features¶

8k.3 Exit Criteria¶

• All config in environment variables ✅
• Validation at startup ✅
• .env.example documented ✅
• TD-009 marked resolved ✅

Status: Phase 5k COMPLETE ✅

9. Phase 6: Hardening (Weeks 24-26)¶

9.1 Objectives¶

• Production-ready reliability
• Performance optimization
• Documentation completion

9.2 Features¶

F6.1: Comprehensive Testing¶

Tasks:

1. Achieve 80%+ unit test coverage
2. Integration tests for all API integrations
3. E2E tests for critical paths:
4. Order → Print Job → Fulfillment
5. Cancellation flow
6. Error recovery flow
7. Performance tests
8. Load tests (500 orders/day)

Deliverables:

• Test coverage report > 80%
• All integration tests passing
• Load test results documented

F6.2: Monitoring and Alerting¶

Tasks:

1. Configure Statping-ng health checks
2. Set up error alerting (email/Slack)
3. Configure performance metrics
4. Create runbook for common issues
5. Set up log aggregation

Health Endpoints:

Health Checks:

• Database connectivity
• Shopify API connectivity
• SimplyPrint API connectivity
• Sendcloud API connectivity

Deliverables:

• Health endpoints operational with build info
• Alerts configured
• Monitoring dashboard

F6.3: Documentation¶

Documents:

1. README with setup instructions
2. API documentation (OpenAPI/Swagger) — ✅ Completed in Phase 1
3. Architecture documentation — ✅ Completed in Phase 1
4. Architecture Decision Records (13 ADRs) at docs/architecture/ADR.md
5. C4 model diagrams (PlantUML) at docs/architecture/
6. Runbook for operations
7. Troubleshooting guide
8. Environment setup guide

Note: OpenAPI/Swagger documentation and Architecture Decision Records were implemented early in Phase 1 to facilitate API development and document key decisions.

Deliverables:

• All documentation complete
• ✅ API docs generated (Phase 1)
• ✅ Architecture documentation (Phase 1)
• Runbook validated

F6.4: Security Hardening¶

Tasks:

1. Dependency vulnerability scan
2. HMAC verification audit
3. Authentication review
4. Data encryption verification
5. Rate limiting implementation
6. Security headers configuration

Deliverables:

• Security scan clean
• All endpoints secured
• Rate limiting active

9.3 Phase 6 Exit Criteria¶

• Test coverage > 80% ✅
• Load testing infrastructure created ✅
• Monitoring operational ✅
• Documentation complete ✅
• Security review passed ✅

Status: Phase 6 COMPLETE ✅

10. Phase 7: Progressive Web App (Week 26)¶

10.1 Objectives¶

• Enable installable app experience on desktop and mobile
• Implement push notifications for real-time print job alerts
• Add offline support for viewing cached order data
• Eliminate need for separate Tauri (desktop) and Capacitor (mobile) apps

10.2 Background¶

Per ADR-035, PWA was adopted to replace the originally planned native shell applications. See the PWA Feasibility Study for detailed research.

Key Decision Drivers:

• Admin dashboard is an ideal PWA use case (data-driven, no deep device integration)
• iOS PWA support matured significantly (push notifications on iOS 16.4+)
• Estimated 80-150 hours saved vs Tauri + Capacitor development
• Single codebase, instant updates, no app store management

10.3 Features¶

F7.1: PWA Foundation¶

Tasks:

1. Install vite-plugin-pwa and configure in vite.config.ts
2. Create manifest.json with app metadata
3. Generate PWA icons (192x192, 512x512) from Forma3D logo
4. Configure service worker for asset caching
5. Add install prompt component
6. Test installation on Chrome, Safari, Edge

Web App Manifest:

{
  "name": "Forma3D.Connect",
  "short_name": "Forma3D",
  "description": "3D Print Order Management Dashboard",
  "start_url": "/",
  "display": "standalone",
  "background_color": "#ffffff",
  "theme_color": "#0066cc",
  "orientation": "any",
  "icons": [
    { "src": "/icons/icon-192.png", "sizes": "192x192", "type": "image/png" },
    { "src": "/icons/icon-512.png", "sizes": "512x512", "type": "image/png" }
  ]
}

Deliverables:

• ✅ PWA installable from browser
• ✅ App appears in OS app launcher after install
• ✅ Works offline for cached pages

F7.2: Push Notifications¶

Tasks:

1. Generate VAPID keys for Web Push
2. Create push notification service in NestJS API
3. Add push subscription endpoint (POST /api/v1/push/subscribe)
4. Integrate with existing notification service (email → push)
5. Implement notification permission flow in dashboard
6. Create notification settings UI in /settings
7. Test on Android Chrome and iOS Safari (Home Screen installed)

Push Notification Events:

iOS Considerations:

• Push notifications require Home Screen install
• User gesture required for permission request
• Use Declarative Web Push for reliability (iOS 18.4+)

Deliverables:

• ✅ Push notifications working on desktop browsers
• ✅ Push notifications working on Android
• ✅ Push notifications working on iOS (Home Screen install)
• ✅ User can enable/disable push in settings

F7.3: Offline Support¶

Tasks:

1. Configure Workbox for runtime caching
2. Implement IndexedDB storage for order data
3. Add offline indicator component
4. Cache API responses with stale-while-revalidate strategy
5. Queue actions (retry, cancel) when offline
6. Sync queued actions when online
7. Test offline scenarios

Caching Strategy:

Deliverables:

• ✅ Dashboard loads when offline (cached pages)
• ✅ Offline indicator visible when disconnected
• ✅ Queued actions sync on reconnect

F7.4: App-like Experience¶

Tasks:

1. Add splash screen configuration
2. Configure status bar color for iOS/Android
3. Add badge count for unread notifications
4. Implement pull-to-refresh on mobile
5. Add "Add to Home Screen" prompt for iOS users
6. Test on various device sizes

Deliverables:

• ✅ Branded splash screen on app launch
• ✅ Badge count on app icon
• ✅ Mobile-friendly interactions

10.4 Phase 7 Exit Criteria¶

• PWA installable on Chrome, Safari, Edge
• Push notifications working on all platforms
• Offline mode shows cached data
• App icon badge shows notification count
• Documentation updated with PWA install instructions

Status: Phase 7 COMPLETE ✅

Phase 7 Implementation Notes (Completed 2026-01-19):

Environment Variables Required for Push Notifications:

Generating VAPID Keys (one-time setup):

# Generate keys using web-push CLI
npx web-push generate-vapid-keys --json

This outputs JSON with publicKey and privateKey. Add these to: 1. Local .env file for development 2. Azure DevOps forma3d-staging variable group for staging 3. Production environment when ready

Important: Use the same VAPID keys across all environments. If you regenerate keys, all existing push subscriptions become invalid.

Phase 6 Implementation Notes (Completed 2026-01-18):

Deliverables:

• ✅ Health indicators for all external services
• ✅ Helmet security headers (CSP, HSTS, XSS protection)
• ✅ Integration tests for critical flows
• ✅ K6 load testing infrastructure with pipeline integration
• ✅ Operations runbook with incident response
• ✅ Comprehensive documentation suite
• ✅ Security audit checklist for Aikido integration
• ✅ Alerting rules configuration

10. Feature Dependency Graph¶

Legend: - F1b.1 = Backend Observability (Sentry + OTEL) - F1b.2 = Frontend Observability (Sentry React) - F1b.3 = Structured Logging (Pino) - F1b.4 = Observability Library (libs/observability) - F1c.1 = Docker Image Build - F1c.2 = Container Registry Push - F1c.3 = Staging Deployment - F1c.4 = Traefik Configuration - F1d.1 = Acceptance Test Project (Playwright + Gherkin) - F1d.2 = Gherkin Feature Files - F1d.3 = Playwright Step Definitions - F1d.4 = Pipeline Integration - F5b.1 = Correlation ID Infrastructure - F5b.2 = Domain Contracts Library - F5b.3 = Repository Encapsulation - F5b.4 = Service Refactoring - F5c.1 = Database-backed Webhook Idempotency - F5c.2 = Cleanup Scheduled Job - F5d.1 = Vitest Configuration - F5d.2 = MSW API Mocking - F5d.3 = Hook and Context Tests - F5d.4 = UI Component Tests

11. Risk Mitigation¶

11.1 Technical Risks¶

11.2 Schedule Risks¶

12. Success Metrics¶

12.1 MVP Success (End of Phase 3)¶

12.2 Full Release Success (End of Phase 6)¶

13. Resource Requirements¶

13.1 Development Team¶

• 1 Full-stack Developer (primary)
• 1 Part-time QA / DevOps support

13.2 Infrastructure¶

• Development environment (local)
• Staging environment (cloud VPS)
• Production environment (cloud VPS)
• PostgreSQL database (managed)
• Domain and SSL certificates

13.3 External Accounts¶

• Shopify Partner/Custom App access
• SimplyPrint API access
• Sendcloud API access
• GitHub repository
• CI/CD (GitHub Actions)

14. Timeline Summary¶

15. Approval¶

Revision History¶