Part of the Architecture Specification. Patterns adopted from Open Mercato (§13) and the high-level execution roadmap that sequences the 7-module build (§14).
13. Patterns Adopted from Open Mercato
Context
The team also develops Open Mercato, an AI-supportive CRM/ERP foundation framework (Next.js, MikroORM, PostgreSQL, Redis, 14 shared packages, 20+ modules). A formal analysis evaluated 15 Open Mercato patterns for applicability to Constellation's enterprise commerce context.
See: Open_Mercato_Pattern_Analysis_v1.md for the full evaluation.
Adopted Patterns (8 of 15)
| Pattern | Adaptation for Constellation |
|---|
| Event-Driven Decoupling | Typed events with as const, domain-verb naming, transactional outbox (PostgreSQL), audit-critical events are synchronous |
| Module Setup Lifecycle | setup.ts per module with onTenantCreated, seedDefaults, defaultRoleFeatures. seedExamples hard-gated from production |
| No Cross-Module ORM Relations | FK IDs only across modules. Typed service contracts in packages/contracts. Prisma schema lint in CI |
| Spec-Driven Development | .kiro/specs/ directory. Tasks with 3+ file changes require a spec before implementation |
| Field-Level Encryption | Tenant-scoped DEKs, Prisma $extends for transparent encrypt/decrypt. HSM in production, local in dev. No deterministic hashing in regulated environments |
| CLAUDE.md Task Routing | Root CLAUDE.md with task routing table. Per-module CLAUDE.md with domain context + import tables + known pitfalls |
| Module-Decoupling Test | CI check: each module builds independently. Import boundary lint. Prisma schema cross-reference check |
| Import Pattern Tables | Each module CLAUDE.md maps "need X → import from Y → NOT from Z" |
Adapted Patterns (2 of 15)
| Pattern | What Changed |
|---|
| CRUD Factory → Tool-Oriented Composition | Enterprise entities are too varied for a single factory. Use explicit services, tools, and workflows with composable policy/audit helpers instead |
| Dual Queue → Postgres-First Runtime | PostgreSQL outbox + jobs are canonical. BullMQ is optional for high-throughput. In-memory adapter for unit tests |
Skipped Patterns (5 of 15)
| Pattern | Why Skipped |
|---|
| Module Auto-Discovery | Next.js App Router already provides conventions. 7 modules can be listed explicitly. |
| Awilix DI Container | Runtime opacity hinders compliance auditing. React cache() + factory functions suffice. |
| Widget Injection | Classification boundaries could be violated. Use explicit imports + parallel routes. |
| Custom Entities / EAV | Regulated schemas are compliance-driven and rigid. Use metadata Json? for narrow cases only. |
| Overlay/Override System | Enterprise deployments need deterministic, auditable builds. Use feature flags instead. |
14. Execution Roadmap
Phase 0: Monorepo Setup (1 week)
| Task | Deliverable |
|---|
| Initialise Turborepo workspace | turbo.json, root package.json |
Move project-tracker into apps/ | Working project-tracker in monorepo |
Create packages/tsconfig and packages/eslint-config | Shared configs |
| Set up Docker Compose for local PostgreSQL | docker/docker-compose.yml |
Create root CLAUDE.md with task routing table + universal rules | AI agent governance (Open Mercato pattern) |
Create .kiro/specs/ directory with template | Spec-driven development (Open Mercato pattern) |
| Set up module-decoupling CI check | Isolation guardrail (Open Mercato pattern) |
| Set up GitHub Actions CI for monorepo | Lint, type-check, test across all apps |
| Task | Deliverable |
|---|
| Design Directory data model (Users, Orgs, Roles, Permissions, Tenants) | Prisma schema for identity + tenancy schemas |
Build @constellation-platform/auth-core and auth-next | Auth packages with permission evaluation engine |
Build @constellation-platform/db with RLS + audit helpers | DB package with tenant-aware Prisma client |
| Build Directory API (CRUD for users, orgs, roles, credentials) | REST API with auth middleware |
Build @constellation-platform/events with pg LISTEN/NOTIFY | Event bus with typed contracts |
Build @constellation-platform/jobs | Postgres-first job abstraction |
| Write Directory CLAUDE.md | AI agent context for the module |
Note: Directory UI is deferred to Phase 3a (UI Layer). Phase 1 delivers the complete backend API and platform packages. packages/ui is built as part of Phase 3a when all core module backends are available.
Phase 2: Extract and Stabilise (2 weeks)
| Task | Deliverable |
|---|
| Extract patterns from Directory into packages | Stabilised shared packages |
Build tools/create-module scaffold generator | CLI tool for new modules |
| Document shared package APIs | Package-level documentation |
| Validate shared packages by building a minimal Catalog skeleton | Proof that packages work for a second module |
Phase 3: Catalog + Procurement (8-12 weeks)
| Task | Deliverable |
|---|
| Build Catalog module (products, taxonomy, search, shortlisting) | Full catalog application |
| Build Procurement module (RFQ, CPQ, scoring, orders) | Full procurement application |
| Integrate Catalog → Procurement flow (shortlists become RFQs) | End-to-end procurement workflow |
| Integrate Procurement → Projects (orders trigger project creation) | Event-driven integration |
Phase 3a: UI Layer (4-6 weeks)
Build the user-facing frontend for the core modules. This phase delivers the first end-to-end user experience and coincides with the Business Plan Phase 2 "Commercial Pilot Release" milestone.
| Task | Deliverable |
|---|
Build packages/ui — shared component library (shadcn, Tailwind, layouts) | Design system package consumed by all module apps |
Build apps/auth/ — login, registration, MFA, password reset, session mgmt | Standalone auth app wrapping Supabase (or Keycloak) |
| Build Directory UI — org profiles, user management, role admin, certs | Frontend in apps/directory/ consuming Directory API |
| Build Catalog UI — catalog entry creation, search, filter, shortlisting | Frontend in apps/catalog/ consuming Catalog API |
| Build Procurement UI — RFQ creation from shortlists, offer submission | Frontend in apps/procurement/ consuming Procurement API |
| Implement shared navigation component across module apps | Cross-module nav via URL links (no micro-frontend) |
Dependencies: Phase 1 (Directory API), Phase 3 (Catalog + Procurement APIs). This phase produces packages/ui/ as a deliverable.
Key decisions:
apps/auth/ is the central entry point for all authentication flows. Other modules redirect to apps/auth/ for login and rely on a shared auth cookie for session continuity.- Each module app owns its own UI routes. Shared components (nav, layouts, form primitives) live in
packages/ui/.
- Supplier self-service (org profile, catalog management, RFQ response) is a frontend route group within the existing module apps, not a separate application.
Phase 4: Project-Tracker Migration (2-3 weeks)
| Task | Deliverable |
|---|
Replace project-tracker auth with @constellation-platform/auth-core and auth-next | Shared auth in project-tracker |
Add tenant_id to project-tracker schema | Tenant isolation |
| Complete project-tracker Phases 3-5 using shared packages | Production-ready project coordination |
Phase 5: Remaining Modules (8-13 weeks, parallel AI agents)
| Module | Estimated Duration | Dependencies |
|---|
| Documents | 4-5 weeks | Directory (auth), Security (classification) |
| Supply Chain | 3-4 weeks | Directory (auth), Catalog (product references) |
| Compliance | 3-4 weeks | Directory (auth), Procurement (screening integration) |
Phase 6: Enterprise Readiness (Ongoing, parallel)
| Task | Trigger |
|---|
| Keycloak auth provider implementation | First customer requiring SAML/OIDC federation |
| MinIO storage provider | First customer requiring on-prem file storage |
| Docker/K8s deployment manifests | First dedicated/on-prem deployment |
| HSM key management integration | First customer requiring FIPS 140-2 |
| Full RLS audit and penetration testing | Before any regulated or classified data enters platform |
Phase Crosswalk: Architecture vs Business Plan
The architecture roadmap and business plan use independent phase numbering. This table maps between them to avoid confusion.
| Architecture Phase | Business Plan Phase | Key Deliverables |
|---|
| Phase 0: Platform Bootstrap | Phase 1 (Foundation) — infrastructure | Monorepo, platform packages, scaffold generator |
| Phase 1: Directory Module | Phase 1 (Foundation) — first module | Identity, orgs, roles, tenancy backend API |
| Phase 2: Extract & Stabilise | Phase 1 (Foundation) — hardening | Contracts package, package docs, Catalog skeleton |
| Phase 3: Catalog + Procurement | Phase 2 (Commercial Pilot) — backends | Full Catalog and Procurement backend APIs |
| Phase 3a: UI Layer | Phase 2 (Commercial Pilot) — frontends | packages/ui, apps/auth/, module UIs, end-to-end UX |
| Phase 4: Project-Tracker Migration | Phase 2 (Commercial Pilot) — migration | Project-tracker on shared platform |
| Phase 5: Remaining Modules | Phase 3 (Operational Delivery) | Documents, Supply Chain, Compliance |
| Phase 6: Enterprise Readiness | Ongoing | Keycloak, MinIO, K8s, HSM, penetration testing |
Rule of thumb: Architecture phases are sequenced by technical dependency. Business plan phases are grouped by commercial milestone. When in doubt, the architecture spec governs build order; the business plan governs release scope.