Internal Documentation
This folder contains internal working documents that are not intended for external consumption.
Workspace Overview
forma3d-connect is a full-stack Nx monorepo powering an automated 3D printing fulfillment pipeline — from Shopify order ingestion through print job management, shipping, and delivery.
| Layer |
Stack |
| Frontend |
React 19, Vite, Tailwind CSS, TanStack Query, Socket.IO |
| Backend |
NestJS 11 microservices, BullMQ, Prisma 5 |
| Database |
PostgreSQL |
| Observability |
Sentry, OpenTelemetry, ClickHouse, Grafana, Pino |
| CI/CD |
Azure DevOps, Docker, Traefik |
| Testing |
Vitest (frontend), Jest (backend), Playwright + Cucumber (E2E), K6 (load) |
Applications
| App |
Port |
Description |
web |
4200 |
React 19 PWA dashboard with real-time updates |
gateway |
3000 |
API gateway — auth, proxying, rate limiting, health aggregation |
order-service |
3001 |
Order management, Shopify webhooks/OAuth, fulfillment, analytics |
print-service |
3002 |
Print job management, SimplyPrint integration, product mappings |
shipping-service |
3003 |
Shipment management, Sendcloud integration, tracking |
gridflock-service |
3004 |
JSCAD baseplate STL generation + BambuStudio slicing |
acceptance-tests |
— |
Playwright + Cucumber/Gherkin BDD tests |
Libraries
| Library |
Package |
Description |
domain |
@forma3d/domain |
Business entities, enums, schemas, errors, events |
api-client |
@forma3d/api-client |
Typed API client for the frontend |
utils |
@forma3d/utils |
Generic utilities |
config |
@forma3d/config |
Shared configuration |
observability |
@forma3d/observability |
Sentry, OpenTelemetry, Pino logging |
domain-contracts |
@forma3d/domain-contracts |
Cross-service interface contracts |
service-common |
@forma3d/service-common |
Shared microservice code (events, BullMQ) |
gridflock-core |
@forma3d/gridflock-core |
JSCAD-based STL generation |
testing |
testing |
Centralized test fixtures |
Contents
Completed Prompts (prompts/done/)
Core Phases
| Prompt |
Description |
prompt-phase0.md |
Initial project setup |
prompt-phase1.md |
Shopify integration (webhooks, orders) |
prompt-phase1b-observability.md |
Sentry observability integration |
prompt-phase1c-deployment.md |
Docker/Traefik deployment |
prompt-phase1d-acceptance.md |
Acceptance testing with Playwright |
prompt-phase2.md |
SimplyPrint integration |
prompt-phase3.md |
Fulfillment and cancellation workflows |
prompt-phase4.md |
Admin dashboard UI |
prompt-phase5.md |
Tech debt audit and planning |
prompt-phase6.md |
Phase 6 features |
prompt-phase7-PWA.md |
Progressive Web App support |
Tech Debt (Phase 5 sub-tasks)
| Prompt |
Description |
prompt-phase5b-domain-boundary-separation.md |
Domain boundary separation |
prompt-phase5c-techdebt-critical.md |
Critical tech debt items |
prompt-phase5d-techdebt-critical.md |
Critical tech debt items (continued) |
prompt-phase5e-techdebt-json-schemas.md |
JSON schema validation |
prompt-phase5f-techdebt-shared-types.md |
Shared type definitions |
prompt-phase5g-techdebt-structured-logging.md |
Structured logging |
prompt-phase5h-techdebt-controller-tests.md |
Controller test coverage |
prompt-phase5i-techdebt-domain-contracts.md |
Domain contracts |
prompt-phase5j-techdebt-error-types.md |
Typed error handling |
prompt-phase5k-techdebt-configuration.md |
Configuration management |
prompt-phase5l-techdebt-eslint-test-setup.md |
ESLint and test setup |
prompt-phase5m-techdebt-unused-components.md |
Unused component cleanup |
prompt-phase5n-techdebt-rate-limiting.md |
Rate limiting |
prompt-phase5o-techdebt-connection-pool.md |
Database connection pooling |
prompt-phase5p-techdebt-api-versioning.md |
API versioning |
prompt-phase5q-techdebt-shipment-tests.md |
Shipment test coverage |
prompt-phase5r-techdebt-metadata-types.md |
Metadata type definitions |
prompt-phase5s-techdebt-prisma-decoupling.md |
Prisma decoupling |
prompt-phase5t-techdebt-dead-code.md |
Dead code removal |
prompt-phase5u-techdebt-file-naming.md |
File naming conventions |
prompt-phase5v-techdebt-openapi-examples.md |
OpenAPI examples |
prompt-phase5w-techdebt-test-fixtures.md |
Test fixture improvements |
Feature Prompts
| Prompt |
Description |
prompt-shopify-oauth.md |
Shopify OAuth flow |
prompt-service-points.md |
Service points feature |
prompt-simplyprint-history-reconciliation.md |
SimplyPrint history reconciliation |
prompt-echarts-dashboard-analytics.md |
ECharts dashboard analytics |
prompt-phase-20260124-RBAC-multitenancy.md |
RBAC and multi-tenancy |
prompt-gridflock-stl-generation-service-part1.md |
GridFlock STL generation (part 1) |
prompt-gridflock-stl-generation-service-part2.md |
GridFlock STL generation (part 2) |
prompt-gridflock-stl-generation-service-part3.md |
GridFlock STL generation (part 3) |
prompt-gridflock-stl-generation-service-part4.md |
GridFlock STL generation (part 4) |
prompt-gridflock-stl-generation-service-part5.md |
GridFlock STL generation (part 5) |
prompt-gridflock-stl-generation-service-part6.md |
GridFlock STL generation (part 6) |
prompt-eventcatalog-architecture-documentation.md |
EventCatalog architecture documentation |
prompt-clickhouse-grafana-logging.md |
ClickHouse + Grafana centralized logging |
prompt-pgadmin-on-demand-container.md |
On-demand pgAdmin container management |
Implementation Feedback
| File |
Description |
techdebt-high-implementation-feedback.md |
Feedback from high-priority tech debt work |
techdebt-medium-low-implementation-feedback.md |
Feedback from medium/low-priority tech debt work |
Mockups
The mockups/ subfolder contains PlantUML Salt wireframes for the dashboard UI (layouts, orders, mappings, logs, login).
Upcoming Prompts (prompts/todo/)
See prompts/todo/ROADMAP.md for the full prioritized roadmap with PlantUML diagrams.
| # |
Prompt |
Description |
| 1 |
prompt-inventory-stock-management.md |
Inventory and stock management |
| 2 |
prompt-scaling-preparations.md |
Docker Compose to Kubernetes preparation (reserved IP, health checks, statelessness) |
| 3 |
prompt-multi-tenancy-super-admin.md |
Multi-tenancy super admin |
| 4 |
prompt-nx-cloud-dte-pipeline.md |
Nx Cloud DTE pipeline |
| 5 |
kimi_prompt_3d_organizers_studio_neat_inspired.md |
3D organizers (Studio Neat inspired) |
| 6 |
prompt-implement-stubs-and-retry-handlers.md |
Implement stubs and retry handlers |
| 7 |
prompt-openscad-server-side-preview.md |
Moved to done/ — partly done, replaced by plate-level cache |
| 8 |
prompt-stl-cache-prepopulation-scripts.md |
Moved to done/ — legacy preview cache scripts removed; replaced by plate-level cache |
Note
These documents are for development reference only. They document the AI-assisted development process but are not part of the official project documentation.