Forma3D.Connect — Vision Document¶

Version: 1.0
Date: January 9, 2026
Status: Draft
Document Type: PRINCE2 Project Vision

1. Executive Summary¶

Forma3D.Connect is an integration platform designed to bridge the gap between Forma 3D's print farm management system (SimplyPrint) and its e-commerce platform (Shopify). The system will automate the entire print-on-demand workflow, from order placement to product fulfillment and shipping initiation.

This document defines the vision, objectives, scope, and success criteria for the Forma3D.Connect integration services, following the PRINCE2 methodology framework.

2. Background¶

2.1 Current Situation¶

Forma 3D operates a 3D print farm ecosystem consisting of:

• SimplyPrint: Cloud-based print farm management software connected to multiple 3D printers via Raspberry Pi controllers
• Shopify: Online sales platform with connections to multiple marketplace integrators (Koongo) and shipping providers (Sendcloud)
• Supporting Infrastructure: UPS systems, filament dryers, air quality monitors, and environmental controls

The current ecosystem (as illustrated in assets/ecosystem.jpg) shows disconnected operational flows between:

• Sales channels (Shopify → Koongo → bol., Kaufland.de, CDiscount, Amazon)
• Production systems (SimplyPrint → 3D Printers)
• Business operations (Slicing Pie equity calculator, Matomo analytics, Statping-ng monitoring)

2.2 Business Services Structure¶

As shown in assets/business-overview.jpg, Forma 3D's business operates across three layers:

All services feed into Customer Success as the ultimate outcome.

2.3 Problem Statement¶

Currently, when an order is placed on Shopify:

1. Manual intervention is required to create print jobs in SimplyPrint
2. Print completion status is not automatically communicated to Shopify
3. Order fulfillment must be manually triggered
4. Shipping labels and tracking information are manually processed

This creates delays, potential errors, and limits scalability.

3. Vision Statement¶

"To create a seamless, automated bridge between e-commerce orders and 3D print production, enabling true print-on-demand operations where every Shopify order automatically triggers production, and every completed print automatically fulfills customer orders."

4. Project Objectives¶

4.1 Primary Objectives¶

4.2 Secondary Objectives¶

5. Scope¶

5.1 In Scope¶

5.1.1 Core Integration Features¶

• ✅ Shopify Webhook Listener: Capture new orders in real-time — Implemented (Phase 1)
• ✅ Order Parser & Mapper: Extract print-relevant information from orders — Implemented (Phase 1)
• SimplyPrint Job Creator: Automatically queue print jobs — Phase 2
• Print Status Monitor: Track job progress via SimplyPrint API/webhooks — Phase 2
• Fulfillment Trigger: Mark orders fulfilled in Shopify upon print completion — Phase 3
• Shipping Integration: Trigger Sendcloud shipping label generation — Phase 5

5.1.2 Supporting Features¶

• Admin Dashboard: Web interface for monitoring and manual overrides — Phase 4
• ✅ Event Logging: Comprehensive logging of all integration events — Implemented (Phase 1)
• Error Handling: Retry mechanisms and failure notifications — Phase 3
• ✅ Configuration Management: Map Shopify products to SimplyPrint print profiles — Implemented (Phase 1)

5.1.3 Technical Infrastructure¶

• NestJS API backend with PostgreSQL database
• React 19 admin dashboard
• Socket.IO for real-time updates
• Webhook endpoints for both Shopify and SimplyPrint
• ✅ OpenAPI/Swagger interactive documentation (/api/docs)
• ✅ Aikido Security Platform for continuous security monitoring and SBOM generation
• Sentry Observability Platform — Error tracking, performance monitoring, and distributed tracing (Phase 1b)

5.2 Out of Scope¶

5.3 Future Considerations (Post-MVP)¶

• Inventory forecasting: Predict filament and material needs
• Production scheduling optimization: Intelligent job assignment
• Quality control workflows: Inspection checkpoints
• Customer notification system: Automated progress updates
• Analytics and reporting: Production efficiency metrics
• Multi-location support: Distributed print farm coordination

6. Stakeholders¶

6.1 Internal Stakeholders¶

6.2 External Stakeholders¶

7. Business Case¶

7.1 Benefits¶

Tangible Benefits¶

Intangible Benefits¶

• Improved customer satisfaction through faster, more reliable fulfillment
• Scalability enablement for business growth
• Competitive advantage in print-on-demand market
• Operational insights through data collection

7.2 Costs¶

7.3 Return on Investment¶

With an estimated labor savings of 3.5 hours/day at operational rates, the system pays for development costs within 3-6 months, with ongoing savings thereafter.

8. Technical Vision¶

8.1 Architecture Overview¶

8.2 Tech Stack (per .cursor/rules/derived-cursor-rules.mdc)¶

8.3 Integration Points¶

Shopify API¶

• Authentication: OAuth 2.0 / API Key
• Webhooks: orders/create, orders/updated, orders/cancelled
• REST/GraphQL: Order retrieval, fulfillment creation, inventory updates
• Key Endpoints:
• POST /admin/api/2024-01/fulfillments.json
• GET /admin/api/2024-01/orders.json
• PUT /admin/api/2024-01/orders/{id}.json

SimplyPrint API¶

• Authentication: API Key / Bearer Token
• Webhooks: Print job status updates, completion events
• REST API: Job creation, queue management, printer status
• Key Operations:
• Create print job from file/URL
• Assign job to printer/queue
• Monitor job status
• Retrieve completion events

Sendcloud API¶

• Authentication: API Key
• REST API: Label creation, tracking information
• Key Operations:
• Create shipping label
• Retrieve tracking URL

9. Constraints¶

9.1 Technical Constraints¶

9.2 Business Constraints¶

9.3 Regulatory Constraints¶

10. Assumptions¶

11. Risks¶

12. Success Criteria¶

12.1 MVP Success Criteria¶

12.2 Post-MVP Success Criteria¶

13. Quality Expectations¶

13.1 Code Quality¶

• ✅ 100% TypeScript with strict mode — Implemented
• ✅ No any types or ts-ignore comments — Enforced via ESLint
• ✅ Comprehensive error handling with typed errors — Implemented
• Unit test coverage > 80% — In progress
• ✅ Integration test coverage for all API interactions — E2E tests implemented

13.2 Security Quality (Aikido Platform)¶

The project integrates Aikido Security Platform for continuous security monitoring:

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

13.3 Documentation¶

• ✅ API documentation (OpenAPI/Swagger) — Implemented
• Interactive Swagger UI at /api/docs
• OpenAPI 3.0 JSON specification at /api/docs-json
• All endpoints documented with request/response schemas
• Grouped by feature: Health, Orders, Product Mappings, Shopify Webhooks
• Architecture decision records ✅ Implemented — See docs/03-architecture/adr/ADR.md
• 16 ADRs documenting all architectural decisions
• C4 model diagrams (Context, Container, Component, Deployment, Database)
• Runbook for operations
• Incident response procedures

13.4 Operational Quality (Sentry Observability)¶

The project integrates Sentry for comprehensive observability:

Architecture: - OpenTelemetry-first approach for vendor neutrality - Traces exported to Sentry via OTLP - 100% sampling (adjustable when traffic increases) - Sensitive data scrubbing (PII, tokens, secrets) - Sentry Logs integration for structured log ingestion

14. Approval¶

15. Document Control¶

Appendix A: Glossary¶

Appendix B: References¶

• Shopify Admin API Documentation: https://shopify.dev/docs/api/admin
• SimplyPrint Platform: https://simplyprint.io
• Sendcloud API Documentation: https://api.sendcloud.dev
• Nx Monorepo Documentation: https://nx.dev
• NestJS Documentation: https://docs.nestjs.com
• NestJS Swagger Module: https://docs.nestjs.com/openapi/introduction
• OpenAPI Specification: https://swagger.io/specification/
• Aikido Security Platform: https://www.aikido.dev/
• Sentry Documentation: https://docs.sentry.io/
• Sentry for NestJS: https://docs.sentry.io/platforms/javascript/guides/nestjs/
• Sentry for React: https://docs.sentry.io/platforms/javascript/guides/react/
• OpenTelemetry Documentation: https://opentelemetry.io/docs/