Project Summary & Business Challenge
3DPCC is a specialized B2B SaaS for automating quotes, production management, and inventory in the 3D printing industry. Role: Sole Architect & Lead Full-Stack Developer.
The project was inherited at the moment its existing architecture hit a wall of technical limitations:
Starting state: The application had a Supabase Postgres database, but all logic relied on direct frontend queries and individual Supabase Edge Functions.
Business requirement: Transform the calculator into a central operational system (ERP) for 3D print farms — with organization management, multi-warehouse support, customer deduplication, and strict stock reservation processes.
Architectural problem of Serverless / Edge Functions in ERP: The distributed logic and Edge Function calls made it impossible to implement key reliability mechanisms:
- No unified control over multi-domain transactions.
- No ability to implement safe retry mechanisms (with backoff), queuing, or the Transactional Outbox pattern for events.
- Difficulty enforcing strict idempotency and a consistent API contract for complex business operations.
- Unnecessary overhead and complexity on the frontend from SSR (Next.js) combined with authorization tokens stored in localStorage.
As the sole developer, I designed and implemented a dedicated, canonical Node.js backend API (Modular Monolith) from scratch, taking over all business and transactional logic, and refactored the frontend into a clean, highly performant SPA.
Backend Architecture: Modular Monolith (Node.js 24 LTS)
The choice fell on a Modular Monolith. In a one-person team, microservices would generate enormous DevOps overhead. Instead, business code was divided into isolated modules within a single repository with clear dependency restrictions:
src/modules/<module>/
├── <module>.routes.ts # HTTP transport & Express routing
├── <module>.schemas.ts # Zod validation contracts (input/output)
├── <module>.service.ts # Use cases & pure domain logic
├── <module>.repository.ts # Drizzle ORM (I/O queries to Postgres)
├── <module>.types.ts # Domain and local types
└── tests/ # Dedicated module integration testsArchitectural Principles (Enforced by Design)
1. Canonical business API: The frontend no longer makes direct Supabase queries — all communication goes through the versioned /api/v1 API.
2. No logic in routers: Route handles only HTTP receive, header verification, and Zod input validation.
3. Pure logic in Service: The service layer has zero Express (req/res) dependencies; it is 100% unit testable and manages transaction consistency.
4. DB isolation in Repository: No module may execute direct SQL/Drizzle queries against another module's tables — communication only via public services.
5. No circular dependencies: Explicit module registration in the main /api/v1 router, no magic auto-discovery.
Deep Dive: Domain Modules
1. Warehouses & Stock Reservations
Stock levels and corrections: Multiple warehouses per organization (default per org), bounded stock list, and transactional quantity corrections.
Stock Reservation Lifecycle: Full reservation lifecycle implemented (create, consume, release, expire).
Idempotency and Concurrency: SHA-256 request fingerprinting (based on parameters + requestId). Retrying a request on a dropped connection neither duplicates the reservation nor corrupts stock levels.
2. Orders Core & State Machine
State Machine: Strict order state machine (Draft → Confirmed → Processing → Fulfilled / Canceled). State transitions are coupled to automatic warehouse reservation consume/release in a single transaction.
Financial snapshots: Source order amounts stored as integers in the smallest currency unit (grosz/cents ISO 4217) — eliminates floating-point rounding errors.
3. Customers & Merge Engine
Duplicate queue: Automatic detection of potential customer duplicates based on contact and address data.
Logical Merge: Idempotent, auditable customer record merge process (POST /api/v1/customers/:id/merge), preserving the historical integrity of related orders.
4. Entitlements & Feature Gating
The system dynamically resolves organization entitlements based on Stripe Billing subscription plans and granted capabilities (notes.access, inventory.manage, etc.).
The /api/v1/entitlements endpoint is the single source of truth for the frontend UI (LimitMeters, Upsells, RequireEntitlement gates).
Security, Multi-tenancy & Audit Log
Multi-tenancy & Isolation
Every database record carries an org_id.
All Repository queries automatically append WHERE org_id = tenant.orgId.
Defense in Depth: Supabase Postgres Row Level Security (RLS) policies act as a second line of defense against data leakage between organizations.
Dedicated Audit Log (audit_records)
Designed as an immutable Append-Only table:
Application code has INSERT-only permissions.
Every critical action (invitation acceptance, role change, organization ownership transfer) writes an audit record with before_state and after_state snapshots in the same Postgres transaction as the business operation.
Frontend Architecture: Deliberate SPA (React 19 + Vite 8)
The frontend was migrated from SSR to a pure Single Page Application (SPA), relieving the browser and eliminating authorization problems.
The Two Seams Pattern
To prevent locking the project into specific auxiliary libraries, two isolation seams were introduced:
1. lib/navigation.ts — The only module in the entire application that imports react-router. All components and views navigate through this abstract interface.
2. lib/i18n.ts — The only module importing use-intl.
As a result, swapping the router or i18n engine in the future requires modifying exactly one file in the project.
16-Language Support (i18n) and ICU Typing
English is statically bundled (serves as fallback and type anchor for AppMessages).
The remaining 15 languages load dynamically as lazy chunks (only on 3dpcc-locale cookie detection or change).
Dedicated Vitest tests validate key completeness and ICU parameter structure across all 16 JSON files.
Engineering Process & Quality Assurance
Architectural Decision Records (ADR)
The project is driven by 17 formal ADR documents (ADR-001 Drizzle Schema Strategy, ADR-009 Stock Reservation Lifecycle, ADR-010 Orders State Machine, ADR-013 Platform Operator Authorization, and more).
CI/CD Gates and Testing
Three independent quality gates configured in GitHub Actions, triggered on every Pull Request:
1. Static & Unit Gate: ESLint, TypeScript tsc --noEmit, Vitest (unit tests).
2. Database Gate: Integration tests running on a real, containerized Supabase Postgres instance. Tests generate synthetic data, auto-clean after themselves, verifying idempotency, concurrency, and RLS policies.
3. Production Gate: Build test and Docker production container smoke test (Node 24 LTS).
Results & Business Value
1. Ordered process architecture: Replacing direct database queries from the frontend with a canonical business backend, which enabled implementing advanced consistency mechanisms (idempotency, state machines, transactions).
2. Cost predictability: The modular monolith enables cheap operation on a single instance (Railway/Docker) without paying for or maintaining complex microservices infrastructure or distributed serverless functions.
3. Integration readiness: The generated API with full OpenAPI 3.1 documentation and stable versioning enables rapid external store integration (Etsy, Amazon) and mobile app development.