Forma3D.Connect — Development Roadmap¶

Last updated: 2026-03-14
Status: Active — tracks upcoming development work
Prompt files: Each item links to a detailed AI development prompt in this folder

Priority Overview¶

Items are ordered by implementation priority (highest first). Each item has an estimated effort and dependency chain that determines sequencing.

Completed effort: ~36–54 hours (items 1–6)
Remaining estimated effort: 68–102 hours (excluding Kimi mockups which are an external design task)

Dependency Graph¶

Timeline View¶

Detailed Items¶

1. ClickHouse + Grafana Centralized Logging ✅¶

Summary: Migrate structured logging from Sentry Logs to a self-hosted ClickHouse + Grafana stack collected via OpenTelemetry. Sentry continues to handle error tracking, performance monitoring, and profiling — only the logging concern moves.

Key deliverables: - OpenTelemetry Collector receiving logs via OTLP gRPC - ClickHouse for high-performance columnar log storage with tiered TTL retention - Grafana dashboards for log visualization and alerting - Pino logger bridged to OTel replacing SentryLoggerService - Automated backups to DigitalOcean Spaces

Phases: 1. Deploy infrastructure (ClickHouse, OTel Collector, Grafana) — 1 day 2. Application integration with dual-write — 1 week 3. Build Grafana dashboards — 3–5 days 4. Cut over from Sentry Logs — 1 day 5. Cleanup and backups — 1 day

2. pgAdmin On-Demand Container ✅¶

Summary: Move pgAdmin from an always-on container (~300 MB idle memory) to an on-demand container that administrators can start/stop from a UI toggle. Reduces memory pressure and attack surface.

Key deliverables: - Separate docker-compose.pgadmin.yml for independent lifecycle management - Backend API on Gateway for container start/stop/status - Frontend "Developer Tools" settings page with one-click toggle - Data persistence across stop/start cycles

3. Inventory & Stock Management ✅¶

Summary: Transition from pure print-to-order to a hybrid fulfillment model. Track inventory at the ProductMapping level (one stock unit = one complete set of all AssemblyParts). Setting minimumStock > 0 on a product enables automatic replenishment. Orders consume complete units from stock first, then print the remainder. Standard GridFlock grids (e.g., standard IKEA drawer sizes) can have stock management enabled.

Key deliverables: - Inventory fields on ProductMapping (currentStock, minimumStock, etc.) - StockBatch model to group pre-production PrintJobs into complete units - InventoryTransaction model for full audit trail - Stock-aware order fulfillment in OrchestrationService (consume units, print remainder) - Pre-production scheduler (cron-based, creates StockBatches) - Frontend inventory dashboard with stock levels, configuration, and transaction history

4. Stubs & Retry Handlers ✅¶

Summary: Replace all stub and placeholder implementations across microservices with working code. Audit services in shipping-service, gridflock-service, and print-service were no-op stubs; retry queue handlers for print job creation and cancellation were placeholders.

Key deliverables: - Real AuditService implementations in shipping-service, gridflock-service, and print-service (modeled on order-service reference) - Working FulfillmentService in shipping-service - PRINT_JOB_CREATION retry handler in order-service and shipping-service - CANCELLATION retry handler in order-service and shipping-service - Unit tests for all new implementations

5. SonarCloud Code Quality Integration ✅¶

Summary: Integrate SonarCloud Team into the Azure DevOps CI/CD pipeline for continuous code quality analysis. Every push to main and every PR is analyzed for bugs, vulnerabilities, code smells, duplication, cognitive complexity, and test coverage. Results appear as inline PR comments with quality gate enforcement.

Key deliverables: - sonar-project.properties configuration at repo root - CodeQuality job in the ValidateAndTest pipeline stage - PR decoration with quality gate status on Azure DevOps - Coverage integration (Vitest/Jest lcov → SonarCloud) - Rule suppression management via sonar.issue.ignore.multicriteria - Issue triage reports: 2026-03-12, 2026-03-13

Results (first 2 days):

6. CodeCharta City Visualization ✅¶

Summary: Integrate CodeCharta into the CI/CD pipeline to generate a 3D city map from SonarCloud metrics + git history. The .cc.json file is baked into the existing docs Docker image and served with CORS headers so the publicly hosted CodeCharta Web Studio can visualize the codebase as a navigable 3D city.

Key deliverables: - GenerateCodeCharta pipeline job using codecharta/codecharta-analysis Docker image - Merged .cc.json combining SonarCloud metrics (complexity, code smells, coverage, tech debt) with git history (authors, commits, churn) - CORS-enabled Nginx location block (/codecharta/) on the docs container - Downloadable .cc.json served from the docs site (shareable ?file= URLs blocked by CodeCharta's CSP — users download and drag-and-drop instead) - CodeCharta link in the Settings page Help & Support section (admin-only)

7. Scaling Preparations¶

Summary: Prepare the current Docker Compose deployment for a seamless future migration to DigitalOcean Managed Kubernetes. No Kubernetes tooling is installed — the system stays on Docker Compose but becomes "K8s-ready."

Key deliverables: - DNS TTLs lowered to 60s for fast future cut-over (<1 min propagation) - Container registry hygiene with semantic image tagging - Standardized HTTP health checks (/health/live + /health/ready) - Graceful shutdown handling (SIGTERM) - Configuration externalization audit - Resource constraints on all services - Statelessness verification

Important: DigitalOcean Reserved IPs can only be assigned to Droplets, not Load Balancers. The migration strategy uses a DNS-based cut-over: update A records from Droplet IP to LB's stable IP. With 60s TTLs pre-configured, propagation takes under a minute.

Migration path:

8. Multi-Tenancy + Super Admin¶

Summary: Extend the existing tenant-ready infrastructure to support multiple active tenants with complete data isolation, super admin role for cross-tenant management, and webhook routing for multi-tenant inbound traffic.

Key deliverables: - isSuperAdmin flag on User model - Super admin tenant switching (session-based) - Tenant management API (list, create, switch) - Repository tenant enforcement (compound WHERE clauses on all mutations) - tenantId added to all domain DTOs - Webhook multi-tenant routing (Shopify shop → tenant) - Frontend tenant switcher component

9. Internationalization & Per-User Locale Preferences¶

Summary: Implement full internationalization with per-user locale preferences. A two-tier resolution chain (user → tenant → system default) allows tenants to set organization-wide defaults while individual users override language, timezone, date/time format, measurement units, and first day of week.

Key deliverables: - Per-user locale fields on User model (nullable, inherits from tenant) - Tenant-level locale defaults on Tenant model - react-i18next with namespace-based lazy loading (English + Dutch placeholders) - Locale-aware formatting hooks (useFormatDate, useFormatNumber, useMeasurement) - Backend locale middleware for email and notification localization - "Language & Region" settings section with live preview - ESLint rule to prevent new hardcoded strings in JSX - CI translation completeness check

Locale dimensions covered:

10. Nx Cloud DTE Pipeline¶

Summary: Integrate Nx Cloud with Distributed Task Execution into the Azure DevOps CI/CD pipeline. Collapse sequential Validate → Test → Build stages into a single distributed stage for feature branches, dramatically reducing CI pipeline duration.

Key deliverables: - Nx Cloud workspace connection with remote caching - Manual DTE with Azure agent jobs (3 agents + 1 orchestrator) - Feature branch: single CI stage (lint + typecheck + test distributed) - Main branch: DTE for validation + unchanged Docker packaging - Graceful fallback when Nx Cloud is unavailable

11. Kimi Shopify Store Mockups¶

Summary: Create high-fidelity mockups for the Forma3D Shopify store (homepage, PDP, grid configurator, collection page) using a Studio Neat-inspired minimal aesthetic. This is an external design task for Kimi AI, independent of all technical development work.

Key deliverables: - Homepage mockup (desktop + mobile) - Product Detail Page for a plate organizer - Custom grid configurator page - Collection page - Design system tokens (colors, typography, spacing, buttons)

12. Traefik Mesh Observability¶

Summary: Integrate Traefik Mesh's Prometheus metrics into the existing OTel Collector → ClickHouse → Grafana pipeline. The existing stack answers "what happened inside a service?" (application logs). Mesh metrics answer "what's happening between services?" — completing full-stack observability.

Key deliverables: - Prometheus receiver in OTel Collector scraping Traefik Mesh proxy pods - ClickHouse otel_metrics table with 90-day TTL retention - Grafana "Service Mesh Traffic" dashboard (request rates, latency percentiles, error rates, mTLS status per service pair) - Alerting rules for inter-service error rate spikes, latency anomalies, and mesh proxy health - Works consistently across local dev (Rancher Desktop + Tilt), staging, and production (DOKS)

Architecture Context¶

For reference, this is how the roadmap items relate to the overall system architecture:

Risk Assessment¶

Decision Log¶

Human Estimate vs AI Actual — Completed Items¶

For completed roadmap items, the following compares the original human team estimates with actual AI implementation time:

Context: Full Project Acceleration History¶

Key insight: AI acceleration is highest for well-defined implementation tasks (microservices split: 11x, core development: 18.5x) and lowest for tasks involving heavy research, real-world testing, and human judgment (RBAC: 1.9x, ops intelligence: 1.6x). Stock Management confirmed this pattern — it required 7 AI sessions, heavy human QA, and produced 15 gaps (67% found by the human). The remaining roadmap items (Multi-Tenancy, Scaling) involve significant domain modeling and real-world integration, suggesting 2-4x acceleration is a realistic expectation.

Estimated remaining effort with AI: 16–28 hours (vs. 68–102 hours human estimate for items 7–10, 12)

This roadmap is a living document. Update priorities and dependencies as work progresses and requirements evolve.