Forma3D.Connect — Requirements Document¶

Version: 1.0
Date: January 9, 2026
Status: Draft
Related Document: Vision Document

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 ✅ (Phase 1 Complete)¶

FR-SH-001: Webhook Registration ✅ Implemented¶

FR-SH-002: Order Reception ✅ Implemented¶

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

FR-SH-004: Order Fulfillment ✅ Implemented¶

FR-SH-005: Order Cancellation Handling ✅ Implemented¶

3.2 SimplyPrint Integration ✅ (Phase 2 Complete)¶

FR-SP-001: Authentication ✅ Implemented¶

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 ✅ Implemented¶

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 ✅ Implemented¶

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 ✅ Implemented¶

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 ✅ Implemented¶

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 ✅ (Phase 5 Complete)¶

FR-SC-001: Shipping Label Generation ✅ Implemented¶

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 ✅ Implemented¶

Implementation Notes: Tracking number and URL from Sendcloud stored in Order model. Fulfillment service uses tracking info when creating Shopify fulfillment.

3.4 Administrative Dashboard ✅ (Phase 4 Complete)¶

FR-AD-001: Order Queue View ✅ Implemented¶

Implementation: apps/web/src/pages/orders/index.tsx — Order list with status filtering, pagination, and real-time updates via Socket.IO.

FR-AD-002: Order Detail View ✅ Implemented¶

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 ✅ Implemented¶

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

FR-AD-004: System Configuration ✅ Implemented¶

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

FR-AD-005: Activity Logs ✅ Implemented¶

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

FR-AD-006: Manual Order Processing ✅ Implemented¶

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 ✅ Implemented¶

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¶

NFR-SE-003: Data Encryption at Rest¶

NFR-SE-004: Access Control¶

NFR-SE-005: Audit Logging¶

NFR-SE-006: Continuous Security Monitoring (Aikido) ✅¶

Aikido Security Checks:

Future: Code quality analysis will be enabled in a subsequent phase.

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¶

NFR-RE-002: Graceful Degradation ✅ Implemented¶

NFR-RE-003: Error Recovery ✅ Implemented¶

4.7 Maintainability Requirements¶

NFR-MA-001: Code Quality¶

NFR-MA-002: Test Coverage¶

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¶

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¶

read_orders
write_orders
read_products
read_fulfillments
write_fulfillments
read_inventory

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¶

• /webhooks/shopify - Shopify webhook receiver
• /webhooks/simplyprint - SimplyPrint webhook receiver (if available)
• 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¶