QuantEngineByItz/spec/65_adr_001_monolithic_spa_architecture.md

ADR-001: Monolithic SPA Architecture for OMS·WMS·ERP Platform

Status: ACCEPTED (2026-07-26)
Date: 2026-07-26
Deciders: Product Manager, Technical Lead, Architecture Team
Related Decisions: Strategic Execution Framework (Spec 61), OpenAPI (Spec 63), Database Schema (Spec 64)

---

Context

OMS·WMS·ERP commercialization requires unified platform architecture decision to balance:

1. Time-to-Market: 18-week Phase 0-11 roadmap (4.5 months)
2. Team Capacity: 13 FTE (4 frontend devs, 2 backend, 1 UX, 2 QA, infrastructure)
3. Maintenance Burden: Long-term operational cost
4. Scalability: Peak load (100 concurrent users during peak hours, future 1000+)
5. Team Skill Set: Experienced Vue 2 team, transitioning to Vue 3 + TypeScript
6. Feature Complexity: 11 CRUD templates, 5 user roles, audit/compliance requirements

Problem Statement

"Should we build a single monolithic SPA or adopt micro-frontend architecture?"

Tradeoff Matrix:

Factor	Monolithic	Micro-Frontend
Time-to-Market	✅ Fast (single build, shared state)	❌ Slower (coordination, build complexity)
Team Efficiency	✅ Shared code/patterns	❌ Potential duplication
Deployment Risk	⚠️ Full redeploy	✅ Independent deploys (but coordination complexity)
Complexity (Initial)	✅ Simple (one codebase)	❌ Complex (module federation, routing)
State Management	✅ Centralized (Pinia)	⚠️ Distributed (synchronization overhead)
Learning Curve	✅ Single pattern	❌ Multiple architectural patterns
Future Modularity	⚠️ Refactoring cost	✅ Already isolated

---

Decision

ADOPT: Monolithic SPA Architecture

Rationale

1. Time-to-Market (P0 Priority)

   • Single Vite build pipeline → faster CI/CD turnaround
   • Shared Pinia store eliminates cross-module synchronization
   • No module federation complexity (can add in Phase 12+ if needed)
   • Team can move fast on core 11 CRUD templates without coordination overhead

2. Team Efficiency (13 FTE Constraint)

   • 4 frontend devs work on unified codebase (not split into silos)
   • Shared component library reduces duplication
   • PR reviews simpler (single review standard)
   • Onboarding new devs easier (one architectural pattern)

3. Scalability Headroom

   • 100 concurrent users = 50-100 backend requests/sec (well within SPA capacity)
   • PostgreSQL backend can handle 10K+ concurrent connections
   • Browser memory: Pinia store + Vue tree ~5-10MB even at 1000 concurrent
   • Future scale-out: Independent microservices backend (no frontend change needed)

4. Data Consistency (Principle 3)

   • Centralized Pinia store = single source of truth for all entities
   • No client-side replication or sync logic
   • Audit trail via PostgreSQL audit_logs (all mutations captured)
   • JWT tokens + RBAC enforced server-side (client trusted for UX only)

5. Cost Efficiency

   • Single deployment pipeline = lower ops cost
   • Monolithic codebase = faster debugging and troubleshooting
   • No microservices orchestration overhead (Kubernetes, service mesh)

Architectural Layers (7-Layer Model)

┌─────────────────────────────────────────────────────┐
│ 1. Presentation Layer (Vue 3 SPA)                   │
│    - 4-layer component hierarchy                    │
│    - Tabler UI + Bootstrap 5 + Storybook            │
│    - Responsive + WCAG 2.1 AA                       │
├─────────────────────────────────────────────────────┤
│ 2. State Management (Pinia)                         │
│    - Entity stores (orders, inventory, products)    │
│    - UI state (modals, notifications, routing)      │
│    - Auth store (user, roles, permissions)          │
├─────────────────────────────────────────────────────┤
│ 3. API Client Layer (Axios + Auto-Generated)        │
│    - Type-safe: OpenAPI → TypeScript SDK            │
│    - Interceptors: JWT refresh, error handling      │
│    - Offline support: Request queue (Phase 12+)     │
├─────────────────────────────────────────────────────┤
│ 4. Domain Layer (Business Logic)                    │
│    - Computed properties (qty_available, totals)    │
│    - Validation rules (duplicate checks, constraints) │
│    - Formatters (currency, date, status labels)     │
├─────────────────────────────────────────────────────┤
│ 5. Repository Layer (Data Access Patterns)          │
│    - Cache strategies (LRU, TTL)                    │
│    - Optimistic updates (e.g., reorder lines)       │
│    - Pagination (lazy load, infinite scroll)        │
├─────────────────────────────────────────────────────┤
│ 6. Infrastructure (Routing, Navigation, Config)     │
│    - Vue Router (lazy-loaded per route)             │
│    - Global error boundaries                        │
│    - Feature flags (Phase 12+)                      │
├─────────────────────────────────────────────────────┤
│ 7. External Services (Backend APIs + 3P)            │
│    - REST APIs (OpenAPI 3.0)                        │
│    - JWT authentication                             │
│    - Real-time updates (WebSocket Phase 12+)        │
└─────────────────────────────────────────────────────┘

4-Layer Component Hierarchy

Layer 1: Primitive Components
  ├─ ButtonBase, InputBase, SelectBase, TextBase
  └─ Reusable, no business logic, full a11y

Layer 2: Typed Field Components
  ├─ TextField, DateField, CurrencyField, StatusField
  └─ Domain-aware validation, formatting, labels

Layer 3: Domain Field Components
  ├─ OrderLineField, InventoryField, VoucherLineField
  └─ Business rules, inline lookups, multi-field composition

Layer 4: Business Composite Components
  ├─ OrderForm, InventoryTransferWizard, VoucherEditor
  └─ Full workflows, state orchestration, audit trail

11 CRUD Templates Standardization

All 11 entity CRUD flows follow uniform pattern (List → Create → Read → Edit → Delete):

Entity	API Endpoints	UI Components	Test Coverage
Order	6 (GET, POST, PUT, DELETE + list, detail)	OrderList, OrderDetail, OrderForm	30 E2E scenarios
OrderLine	Nested CRUD (in order context)	LineEditor (inline in form)	10 E2E
Inventory	6	InventoryList, TransferWizard	15 E2E
StockTransfer	6	TransferForm, ApprovalMatrix	12 E2E
Product	6	ProductList, ProductForm	10 E2E
Supplier	6	SupplierList, SupplierForm	8 E2E
Customer	6	CustomerList, CustomerForm	8 E2E
GLAccount	6	AccountList, AccountForm	8 E2E
Voucher	6	VoucherEditor (line-by-line)	15 E2E
User	6	UserList, UserForm, PermissionMatrix	12 E2E
Warehouse	6	WarehouseList, WarehouseForm	8 E2E

Total E2E Coverage: 116 test scenarios (Phase 4 milestone)

---

Consequences

✅ Positive

1. Faster Delivery

   • Single build pipeline: ~3 min build time
   • CI/CD simpler: No cross-module coordination
   • Feature complete by Phase 4 (week 8) for UAT

2. Maintainability

   • Unified codebase = easier debugging
   • All devs understand full system
   • Refactoring easier (no hidden dependencies)

3. Data Consistency

   • Pinia store = single source of truth
   • No sync issues between independent UIs
   • Audit trail via PostgreSQL (not client-side)

4. User Experience

   • Instant navigation (no full-page reloads)
   • Smooth transitions between modules
   • Consistent look & feel (unified design system)

5. Test Coverage

   • 50/30/20 pyramid: unit (50%) → integration (30%) → E2E (20%)
   • All 116 E2E scenarios in single test suite
   • Deterministic tests (single state source)

⚠️ Negative (Mitigations)

1. Monolith Brittleness

   • Problem: One bad release breaks entire app
   • Mitigation: Strict pre-deployment checklist (Phase 5+), blue-green deployment, 6-point health checks

2. Large Bundle Size

   • Problem: Initial load time if all code bundled
   • Mitigation: Lazy-load routes per module, code split at route level, target <500KB main chunk (Lighthouse 90+)

3. Shared State Complexity

   • Problem: Pinia store grows as features added
   • Mitigation: Modular stores (orders, inventory, users modules), clear naming, documentation

4. Scaling to 1000+ Users

   • Problem: Browser memory, server load
   • Mitigation: Pagination (not all records in memory), connection pooling (PostgreSQL), infrastructure scale-out (Phase 12+)

5. Future Microfront-End Transition

   • Problem: If modularity needed later, refactoring cost
   • Mitigation: Component library + API contracts locked down early, can extract UI module → separate SPA in Phase 13+

---

Alternatives Considered

1. Micro-Frontend Architecture (Module Federation)

Approach: Each CRUD entity (Order, Inventory, etc.) as independent webpack Module Federation remote

Pros:

• Independent deployments per module
• Teams can work in parallel without merge conflicts
• Better long-term modularity

Cons:

• ❌ Shared state synchronization complexity (events, bus, sync failures)
• ❌ Build time: 9-12 min (multiple builds + federation setup)
• ❌ 18-week timeline NOT feasible (needs 20+ weeks for coordination overhead)
• ❌ Learning curve (few devs experienced in Module Federation)
• ❌ CI/CD complexity (version matrix: Order v1-v3 × Inventory v2-v5)

Decision: REJECTED — Too risky for 18-week timeline with 4 frontend devs

2. Headless Backend + Separate Frontends (Web + Mobile)

Approach: Unified .NET backend + Vue SPA (web) + React Native (mobile)

Pros:

• Native mobile experience
• Backend shared code reuse

Cons:

• ❌ Scope creep (mobile adds 4-6 weeks)
• ❌ Double maintenance (Vue + React Native)
• ❌ Mobile not in Phase 0-11 scope (can add in Phase 13+)

Decision: REJECTED — Out of scope. Mobile deferred to Phase 13+

3. Low-Code Platform (OutSystems, Mendix)

Approach: Rapid CRUD generation, visual development

Pros:

• Fastest CRUD generation
• Less boilerplate code

Cons:

• ❌ Vendor lock-in
• ❌ Limited customization for complex workflows (approval matrix, audit trail)
• ❌ Higher TCO (licensing)
• ❌ Team skill atrophy (no real engineering)

Decision: REJECTED — Does not meet control + compliance requirements

4. Separate Microservices UIs (One SPA per domain: OMS, WMS, ERP)

Approach: 3 independent SPAs (micro-frontends without Module Federation)

Pros:

• Clear domain separation
• Smaller bundles per SPA

Cons:

• ❌ Cross-domain navigation complex (not SPA-like experience)
• ❌ Duplicate components (auth, common UI)
• ❌ Harder to reorder across domains (OMS order → WMS allocation → ERP GL)
• ❌ 3 CI/CD pipelines vs 1

Decision: REJECTED — Poor user experience for cross-domain workflows

---

Implementation Plan (Phases 1-4)

Phase 1: Dev Environment & CI/CD (Week 1-2)

• Vite SPA scaffold + TypeScript strict mode
• Pinia stores structure (orders, inventory, users modules)
• Axios API client + OpenAPI SDK auto-generation
• ESLint + Prettier + pre-commit hooks
• GitHub Actions CI/CD (lint → test → build)
• Storybook setup (6.0+, TypeScript support)

Exit Criteria: All devs can build locally, CI green, Storybook runs

Phase 2: Primitive & Composite Layers (Week 3-4)

• Layer 1: 30 Primitive components (Button, Input, Select, etc.)
• Layer 2: 12 Typed Field components (TextField, DateField, etc.)
• Storybook documentation for all components
• WCAG 2.1 AA accessibility audit (axe-core)
• Unit tests: 70%+ coverage

Exit Criteria: Storybook published, all primitives tested, accessibility passed

Phase 3: Smart Components & State (Week 5-6)

• Layer 3: 12 Domain Field components
• Layer 4: 4 Business Composite components (Order, Inventory, Voucher, User)
• Pinia stores + API integration
• Integration tests (Vitest + MSW mocks)
• Real-time data binding

Exit Criteria: State management tested, API mocks working, 50 integration tests pass

Phase 4: CRUD Templates & E2E (Week 7-8)

• 11 full CRUD forms (List, Create, Read, Edit, Delete)
• Approval workflows (supervisor sign-off for high-value orders)
• Pagination + lazy loading
• 116 E2E test scenarios (Playwright)
• Responsive design (mobile, tablet, desktop)

Exit Criteria: All 11 CRUD screens tested, 116 E2E scenarios pass, Lighthouse 90+

---

Related Decisions

• ADR-002 (TBD): Authentication & Authorization (JWT + RBAC)
• ADR-003 (TBD): State Management Strategy (Pinia module organization)
• ADR-004 (TBD): Component Library Versioning (npm @quantengine/ui)
• Strategic Execution Framework (Spec 61): 30 principles applied
• OpenAPI Specification (Spec 63): 30 REST endpoints defined
• Database Schema (Spec 64): PostgreSQL 3NF design

---

Validation Checklist (Phase 0 → Phase 1)

Before proceeding to Phase 1 development:

• All stakeholders agree on monolithic SPA approach
• Component taxonomy approved (4-layer hierarchy)
• 11 CRUD templates mapped to API endpoints
• OpenAPI spec validated by backend team
• Database schema approved by DBA
• Vite scaffold created with TypeScript strict mode
• CI/CD pipeline (GitHub Actions) functional
• Team training: Vue 3 Composition API + Pinia + TypeScript
• Design system finalized (Tabler + custom components)

---

Appendix A: Bundle Size Strategy

Target: Main chunk <500KB (gzip), total <1MB

Strategy:

1. Route-level code splitting: Lazy-load each CRUD module (orders, inventory, etc.)
2. Dynamic imports: import('./orders/OrderForm.vue')
3. Library externalization: Vue, Pinia, Axios in separate chunks
4. Tree-shaking: Remove unused Tabler components at build time
5. Compression: Gzip (server) + Brotli (CDN)

Monitoring: Bundle analyzer in CI (Phase 5+)

---

Appendix B: Performance Targets

Metric	Target	Rationale
First Contentful Paint (FCP)	<2s	Initial render speed
Time to Interactive (TTI)	<3s	User can interact
Largest Contentful Paint (LCP)	<2.5s	Main content visible
Cumulative Layout Shift (CLS)	<0.1	Visual stability
API response time (P95)	<250ms	Backend performance
Database query (P95)	<100ms	Query optimization
Concurrent users (initial)	100	Phase 0-8 capacity
Concurrent users (future)	1000+	Phase 12+ infrastructure scale

---

Appendix C: Team Structure (13 FTE)

Product Manager (1)
├─ Requirements gathering, stakeholder communication
│
Technical Lead / Architect (1)
├─ Architecture decisions, code review
│
Frontend Development Team (4)
├─ Lead FE Dev (1): Component library, design system
├─ Senior FE Dev (1): State management, API integration
├─ Mid-Level FE Dev (2): CRUD templates, E2E tests
│
Backend Development Team (2)
├─ API development (.NET)
├─ Database optimization
│
UX/UI Designer (1)
├─ Figma designs, accessibility audit
│
QA Team (2)
├─ Automation (Playwright)
├─ Manual testing + UAT coordination
│
DevOps/SRE (1)
├─ CI/CD pipeline, monitoring, deployment
│
Security Specialist (0.5 contractor)
├─ Security audit, OWASP validation
│
Technical Writer (0.5)
├─ API docs, user guides, wiki

---

Sign-Off

• Product Manager: _________________ Date: _______
• Technical Lead: _________________ Date: _______
• Backend Lead: _________________ Date: _______
• Frontend Lead: _________________ Date: _______
• QA Lead: _________________ Date: _______

---

Document Version: 1.0
Last Updated: 2026-07-26
Next Review: Phase 1 completion (2026-08-09)