Forma3D.Connect — Requirements Document¶

Version: 1.10
Date: March 20, 2026
Status: Draft
Related Document: Vision Document

Table of Contents¶

• 1. Introduction
• 1.1 Purpose
• 1.2 Scope
• 1.3 Definitions and Acronyms
• 2. System Overview
• 2.1 System Context
• 2.2 User Classes
• 3. Functional Requirements
• 3.1 Shopify Integration
  • FR-SH-001: Webhook Registration
  • FR-SH-002: Order Reception
  • FR-SH-003: Product-to-Print Mapping
  • FR-SH-004: Order Fulfillment
  • FR-SH-005: Order Cancellation Handling
• 3.2 SimplyPrint Integration
  • FR-SP-001: Authentication
  • FR-SP-002: Print Job Creation
  • FR-SP-003: Print Job Status Monitoring
  • FR-SP-004: Print Job Completion Handling
  • FR-SP-005: Print Job Failure Handling
  • FR-SP-006: Printer Status Visibility
• 3.3 Shipping Integration
  • FR-SC-001: Shipping Label Generation
  • FR-SC-002: Tracking Information Sync
• 3.4 Administrative Dashboard
  • FR-AD-001: Order Queue View
  • FR-AD-002: Order Detail View
  • FR-AD-003: Product Mapping Management
  • FR-AD-004: System Configuration
  • FR-AD-005: Activity Logs
  • FR-AD-006: Manual Order Processing
• 3.5 Notifications
  • FR-NO-001: Error Notifications
  • FR-NO-002: Daily Summary
• 4. Non-Functional Requirements
• 4.1 Performance Requirements
  • NFR-PE-001: Order Processing Latency
  • NFR-PE-002: Fulfillment Latency
  • NFR-PE-003: Dashboard Response Time
  • NFR-PE-004: Concurrent Order Processing
• 4.2 Scalability Requirements
  • NFR-SC-001: Daily Order Volume
  • NFR-SC-002: Database Growth
• 4.3 Availability Requirements
  • NFR-AV-001: System Uptime
  • NFR-AV-002: Planned Maintenance Window
  • NFR-AV-003: Recovery Time Objective (RTO)
  • NFR-AV-004: Recovery Point Objective (RPO)
• 4.4 Security Requirements
  • NFR-SE-001: API Authentication
  • NFR-SE-002: Data Encryption in Transit
  • NFR-SE-003: Data Encryption at Rest
  • NFR-SE-004: Access Control
  • NFR-SE-005: Audit Logging
  • NFR-SE-006: Continuous Security Monitoring (Syft + Grype)
  • NFR-SE-007: Software Bill of Materials (SBOM)
  • NFR-SE-008: Admin Endpoint Authorization
• 4.5 Acceptance Testing Requirements
  • NFR-AT-001: Acceptance Testing
  • NFR-AT-002: Gherkin Syntax
  • NFR-AT-003: CI/CD Integration
  • NFR-AT-004: Test Isolation
• 4.6 Observability Requirements (Sentry)
  • NFR-OB-001: Error Tracking
  • NFR-OB-002: Performance Monitoring
  • NFR-OB-003: Distributed Tracing
  • NFR-OB-004: Structured Logging
  • NFR-OB-005: Sampling Configuration
• 4.6 Data Privacy Requirements
  • NFR-DP-001: GDPR Compliance
  • NFR-DP-002: Data Minimization
  • NFR-DP-003: Data Retention
• 4.6 Reliability Requirements
  • NFR-RE-001: Idempotency
  • NFR-RE-002: Graceful Degradation
  • NFR-RE-003: Error Recovery
• 4.7 Maintainability Requirements
  • NFR-MA-001: Code Quality
  • NFR-MA-002: Test Coverage
  • NFR-MA-003: Documentation
  • NFR-MA-004: Logging
• 4.8 Compatibility Requirements
  • NFR-CO-001: Browser Support
  • NFR-CO-002: API Version Compatibility
• 5. API Specifications
• 5.1 Shopify API Requirements
  • 5.1.1 Required Shopify Scopes
  • 5.1.2 Webhook Topics Required
  • 5.1.3 REST/GraphQL Endpoints Used
• 5.2 SimplyPrint API Requirements
  • 5.2.1 Expected Capabilities
  • 5.2.2 Webhook/Polling Requirements
• 5.3 Sendcloud API Requirements
  • 5.3.1 Required Capabilities
• 6. Data Requirements
• 6.1 Data Entities
  • 6.1.1 Order
  • 6.1.2 LineItem
  • 6.1.3 PrintJob
  • 6.1.4 ProductMapping
  • 6.1.5 EventLog
• 6.2 Data Flow
• 7. Interface Requirements
• 7.1 User Interface Requirements
  • UI-001: Dashboard Layout
  • UI-002: Order List View
  • UI-003: Order Detail View
  • UI-004: Configuration Pages
• 7.2 API Interface Requirements
  • API-001: Internal REST API
  • API-002: Webhook Endpoints
  • API-003: OpenAPI/Swagger Documentation
• 8. Constraints
• 8.1 Technical Constraints
• 8.2 Business Constraints
• 8.3 External Constraints
• 9. Traceability Matrix
• 10. Acceptance Criteria Summary
• 10.1 MVP Acceptance
• 10.2 Production Release Criteria
• 11. Document Approval
• 12. Revision History

1. Introduction¶

1.1 Purpose¶

This document defines the functional and non-functional requirements for Forma3D.Connect, the integration services platform that connects Forma 3D's Shopify e-commerce system with SimplyPrint print farm management.

1.2 Scope¶

This requirements specification covers:

• Integration between Shopify and SimplyPrint
• Automated order processing workflows
• Administrative dashboard and monitoring
• Error handling and recovery mechanisms

1.3 Definitions and Acronyms¶

2. System Overview¶

2.1 System Context¶

2.2 User Classes¶

3. Functional Requirements¶

3.1 Shopify Integration¶

FR-SH-001: Webhook Registration¶

FR-SH-002: Order Reception¶

FR-SH-003: Product-to-Print Mapping¶

FR-SH-004: Order Fulfillment¶

FR-SH-005: Order Cancellation Handling¶

3.2 SimplyPrint Integration¶

FR-SP-001: Authentication¶

Implementation Details: - HTTP Basic Authentication with company ID and API key - Credentials stored in environment variables (SIMPLYPRINT_API_KEY, SIMPLYPRINT_COMPANY_ID) - Connection verification on module initialization - Sentry alerts on authentication failures

FR-SP-002: Print Job Creation¶

Implementation Details: - Automatic print job creation via OrchestrationService when orders are created - Supports assembly products (multiple parts per product) - Product mapping lookup for file references - Idempotent job creation (prevents duplicates)

FR-SP-003: Print Job Status Monitoring¶

Implementation Details: - Webhook endpoint at POST /webhooks/simplyprint with X-SP-Token verification - Polling fallback (configurable via SIMPLYPRINT_POLLING_ENABLED) - Status mapping: queued → assigned → printing → completed/failed/cancelled - EventLog entries for all status changes

FR-SP-004: Print Job Completion Handling¶

Implementation Details: - OrchestrationService tracks job completion per order - Emits order.ready-for-fulfillment event when all jobs complete - Supports partial completion (PARTIALLY_COMPLETED status)

FR-SP-005: Print Job Failure Handling¶

Implementation Details: - Error message captured from SimplyPrint API - Sentry alerts for failures (5xx errors) - EventLog entries with requiresAttention: true for operator review - Retry endpoint: POST /api/v1/print-jobs/:id/retry - Cancel endpoint: POST /api/v1/print-jobs/:id/cancel - Maximum retry count configurable (default: 3)

FR-SP-006: Printer Status Visibility¶

3.3 Shipping Integration¶

FR-SC-001: Shipping Label Generation¶

Implementation Notes: Sendcloud API client at apps/api/src/sendcloud/sendcloud-api.client.ts. Shipment model stores parcel ID, tracking info, label URL. Labels generated on order.ready-for-fulfillment event.

FR-SC-002: Tracking Information Sync¶

Implementation Notes: Tracking number and URL from Sendcloud stored in Order model. Fulfillment service uses tracking info when creating Shopify fulfillment. Shipment status (from SendCloud webhooks) is surfaced on every order API response via shipmentStatus field, enabling the dashboard to show real-time shipping progress (Label Created → In Transit → Delivered).

3.4 Administrative Dashboard¶

FR-AD-001: Order Queue View¶

Implementation: apps/web/src/pages/orders/index.tsx — Order list with order status filtering, shipping status filtering (Ready to Ship, In Transit, Delivered, Shipping Issues), shipping status badges, pagination, and real-time updates via Socket.IO. API returns shipmentStatus field on every order response. Backend supports shipmentStatus and readyToShip query parameters.

FR-AD-002: Order Detail View¶

Implementation: apps/web/src/pages/orders/[id].tsx — Order detail page with customer info, line items, print jobs, and action buttons.

FR-AD-003: Product Mapping Management¶

Implementation: apps/web/src/pages/mappings/ — Mapping list and create/edit form with assembly parts editor.

FR-AD-004: System Configuration¶

Implementation: apps/web/src/pages/settings/index.tsx — Settings page with connection status and system info.

FR-AD-005: Activity Logs¶

Implementation: apps/web/src/pages/logs/index.tsx — Activity logs with severity/event type filtering and CSV export.

FR-AD-006: Manual Order Processing¶

Implementation: apps/web/src/pages/orders/[id].tsx — Retry, cancel, and manual action buttons with API key authentication.

3.5 Notifications¶

FR-NO-001: Error Notifications¶

FR-NO-002: Daily Summary¶

4. Non-Functional Requirements¶

4.1 Performance Requirements¶

NFR-PE-001: Order Processing Latency¶

NFR-PE-002: Fulfillment Latency¶

NFR-PE-003: Dashboard Response Time¶

NFR-PE-004: Concurrent Order Processing¶

4.2 Scalability Requirements¶

NFR-SC-001: Daily Order Volume¶

NFR-SC-002: Database Growth¶

4.3 Availability Requirements¶

NFR-AV-001: System Uptime¶

NFR-AV-002: Planned Maintenance Window¶

NFR-AV-003: Recovery Time Objective (RTO)¶

NFR-AV-004: Recovery Point Objective (RPO)¶

4.4 Security Requirements¶

NFR-SE-001: API Authentication¶

Authentication Methods:

NFR-SE-002: Data Encryption in Transit¶

Traceability: .specstory/history/2026-01-10_19-58Z-phase-1c-deployment-prompt-execution.md, 2026-01-16_11-19Z-phase-5-prompt-documentation.md, docs/_internal/prompts/done/prompt-phase6.md

NFR-SE-003: Data Encryption at Rest¶

NFR-SE-004: Access Control¶

Traceability: .specstory/history/2026-01-21_20-12Z-user-accounts-and-permissions-with-keycloak.md, 2026-01-24_16-51Z-rbac-multitenancy-prompt.md, 2026-01-25_16-23Z-rbac-user-management-functionality.md

NFR-SE-005: Audit Logging¶

Traceability: .specstory/history/2026-01-09_20-04Z-phase-1-prompt-execution.md, 2026-01-13_15-49Z-prompt-phase-2-execution.md; code: libs/service-common/src/lib/audit/, libs/domain/src/entities/event-log.ts

NFR-SE-006: Continuous Security Monitoring (Syft + Grype)¶

Security Pipeline:

Note: Aikido was previously used as a SaaS security platform. It was replaced by Syft + Grype (open-source tools by Anchore) to eliminate external SaaS dependency and run scanning directly in the CI/CD pipeline.

NFR-SE-007: Software Bill of Materials (SBOM)¶

NFR-SE-008: Admin Endpoint Authorization¶

Protected Endpoints:

Security Features: - Timing-safe comparison prevents timing attacks - Generic error messages prevent information leakage - Audit logging for access attempts - Development mode allows bypass when key not configured

4.5 Acceptance Testing Requirements¶

The project requires automated acceptance testing to verify deployments:

NFR-AT-001: Acceptance Testing¶

NFR-AT-002: Gherkin Syntax¶

NFR-AT-003: CI/CD Integration¶

NFR-AT-004: Test Isolation¶

4.6 Observability Requirements (Sentry)¶

The project integrates Sentry for comprehensive observability with an OpenTelemetry-first architecture:

NFR-OB-001: Error Tracking¶

NFR-OB-002: Performance Monitoring¶

NFR-OB-003: Distributed Tracing¶

NFR-OB-004: Structured Logging¶

NFR-OB-005: Sampling Configuration¶

4.6 Data Privacy Requirements¶

NFR-DP-001: GDPR Compliance¶

NFR-DP-002: Data Minimization¶

NFR-DP-003: Data Retention¶

4.6 Reliability Requirements¶

NFR-RE-001: Idempotency¶

Traceability: .specstory/history/2026-01-09_20-04Z-phase-1-prompt-execution.md; code: libs/service-common/src/lib/sendcloud/sendcloud-webhook.service.ts (database-backed idempotency), apps/*/src/webhook-idempotency/, order creation with duplicate handling

NFR-RE-002: Graceful Degradation¶

NFR-RE-003: Error Recovery¶

4.7 Maintainability Requirements¶

NFR-MA-001: Code Quality¶

Traceability: .specstory/history/2026-01-09_20-04Z-phase-1-prompt-execution.md, 2026-03-12_17-18Z-sonarcloud-integration-prompt.md, 2026-03-13_*sonarcloud*.md

NFR-MA-002: Test Coverage¶

Traceability: .specstory/history/2026-01-10_16-00Z-pipeline-code-coverage-threshold-not-met.md, 2026-03-12_17-18Z-sonarcloud-integration-prompt.md, 2026-03-13_*coverage*.md

NFR-MA-003: Documentation¶

OpenAPI/Swagger Implementation Details:

• Interactive Swagger UI: /api/docs (non-production only)
• OpenAPI 3.0 JSON: /api/docs-json
• All endpoints documented with @ApiTags, @ApiOperation, @ApiResponse
• All DTOs documented with @ApiProperty decorators
• Request/response schemas auto-generated
• Grouped by feature: Health, Orders, Product Mappings, Shopify Webhooks

NFR-MA-004: Logging¶

Traceability: .specstory/history/2026-01-10_15-01Z-observability-phase-implementation.md (NFR-OB-004 same phase); code: Pino/nestjs-pino

4.8 Compatibility Requirements¶

NFR-CO-001: Browser Support¶

Traceability: .specstory/history/2026-01-14_19-31Z-phase-4-prompt-document.md

NFR-CO-002: API Version Compatibility¶

5. API Specifications¶

5.1 Shopify API Requirements¶

5.1.1 Required Shopify Scopes¶

read_orders
write_orders
read_products
read_fulfillments
write_fulfillments
read_inventory
read_merchant_managed_fulfillment_orders
write_merchant_managed_fulfillment_orders

5.1.2 Webhook Topics Required¶

5.1.3 REST/GraphQL Endpoints Used¶

5.2 SimplyPrint API Requirements¶

5.2.1 Expected Capabilities¶

5.2.2 Webhook/Polling Requirements¶

5.3 Sendcloud API Requirements¶

5.3.1 Required Capabilities¶

6. Data Requirements¶

6.1 Data Entities¶

6.1.1 Order¶

6.1.2 LineItem¶

6.1.3 PrintJob¶

6.1.4 ProductMapping¶

6.1.5 EventLog¶

6.2 Data Flow¶

7. Interface Requirements¶

7.1 User Interface Requirements¶

UI-001: Dashboard Layout¶

• Clean, modern design using Tailwind CSS
• Responsive layout (desktop-first, mobile-compatible)
• Left sidebar navigation
• Main content area with contextual actions

UI-002: Order List View¶

• Table with sortable columns
• Status indicators with color coding
• Quick action buttons per row
• Pagination (50 items per page default)

UI-003: Order Detail View¶

• Two-column layout: order info + timeline
• Line item status indicators
• Action buttons: Retry, Cancel, Force Fulfill
• Print job details expandable

UI-004: Configuration Pages¶

• Form-based input with validation
• Clear success/error feedback
• Connection test buttons for API credentials

7.2 API Interface Requirements¶

API-001: Internal REST API¶

• Versioned endpoints (/api/v1/...)
• JSON request/response format
• Consistent error response structure
• ✅ OpenAPI documentation — Implemented at /api/docs

API-002: Webhook Endpoints¶

• /api/v1/webhooks/shopify - Shopify webhook receiver
• /webhooks/simplyprint - SimplyPrint webhook receiver
• HMAC signature verification
• Idempotent processing

API-003: OpenAPI/Swagger Documentation¶

8. Constraints¶

8.1 Technical Constraints¶

8.2 Business Constraints¶

8.3 External Constraints¶

9. Traceability Matrix¶

10. Acceptance Criteria Summary¶

10.1 MVP Acceptance¶

The MVP is considered complete when:

1. ✓ New Shopify orders automatically create SimplyPrint print jobs
2. ✓ Completed print jobs automatically trigger Shopify fulfillment
3. ✓ Admin dashboard shows order pipeline with status
4. ✓ Manual override capabilities available
5. ✓ Error notifications sent to operators
6. ✓ System achieves 95% automation success rate
7. ✓ System achieves 99% uptime over 2-week test period
8. ✅ API documentation available via Swagger UI — Implemented

10.2 Production Release Criteria¶

1. All MVP criteria met
2. Load testing passes for 500 orders/day
3. Security review completed
4. Documentation complete
5. Runbook validated
6. Backup/recovery tested

11. Document Approval¶

12. Revision History¶