Engineering Roadmap & Testing Blueprint

This reference document defines the complete Engineering Roadmap and Quality Assurance Testing Blueprint for the Business M platform. It details our progressive service-oriented architecture (SOA) transition and defines the testing gates required to promote components from a monolithic process to high-scale macroservices.

---

1. The 10-Week Progressive SOA Roadmap

Our development path transitions components through four progressive stages:

gantt
    title Business M Development & Scaling Path
    dateFormat  YYYY-MM-DD
    section Phase 1: Core
    Standardizing Schema Masters :active, des1, 2026-06-01, 2d
    TAMAGUI Desk UI Shell Setup : active, des2, 2026-06-03, 3d
    section Phase 2: WMS
    WMS Domain Core (00-14) : des3, 2026-06-08, 14d
    section Phase 3: Finance
    Finance Ledger Engine (00-10) : des4, 2026-06-22, 10d
    section Phase 4: People
    HR & Pension Suite (00-09) : des5, 2026-07-02, 12d
    section Phase 5: Scale
    Macroservice Decomposition (NATS) : des6, 2026-07-14, 15d

1.1 Weekly Milestones

• Week 1-2: Core Platform Foundation: Set up global entities (Item, Party, Supplier) on PostgreSQL, configure localized tenant translation schemas, and establish the base Tamagui Desk UI shell.
• Week 3-4: WMS Feature Completeness: Ship stock ledgers, automated purchase requisitions, supplier onboarding, and outlet loan compliance controls in the same process.
• Week 5-6: Finance Suite Integration: Build hierarchical charts of accounts, cost centers, double-entry journal vouchers, Imprest auto-recoupment, and travel and expense (T&E) claims.
• Week 7-8: People & HR Operations: Onboard employee rosters, leave credit processors, medical claim nominee limits, and pension nominal disbursements.
• Week 9-10: Enterprise Macroservice Scale: Decompose bounded contexts into separate processes communicating over NATS RPC, implement CQRS read projections, and route requests via a high-performance Traefik API gateway.

---

2. Progressive Decomposition Checklist (TDD)

When moving a module from monolith (Indie Mode) to microservice (Enterprise Mode), engineers must satisfy the following strict TDD lifecycle:

Part A: Establishing Bounded Interfaces

1. Identify Cross-Module Invocations: Detect where one library makes a direct import call to another (e.g. WMS inventory asking Finance to clear an outlet loan).
2. Define a Shared Protocol: Extract the interface into libs/m_protocols as a stateless Python Protocol. Use only built-in types or lightweight DTOs.
3. Enforce Zero Direct Imports: Consumer modules must never import domain code or controllers directly from the provider. They must rely solely on the Protocol.

Part B: Implementing the Adapters

• The In-Process Adapter: Write a local class implementing the Protocol that calls the provider’s local controllers in-memory.
• The Out-of-Process Adapter: Write a NATS class that serializes the DTO, publishes to a secure NATS subject, and handles network timeouts.
• Horizontal Queue Groups: Out-of-process background subscribers must specify a NATS queue group identifier (e.g., queue='wms-service') to ensure automatic load-balancing when scaled across multiple replicated containers.

Part C: Wiring with Dependency Injection

Use Dependency Injection (DI) containers at boot to dynamically bind the correct adapter based on the environment:

if os.environ.get("M_MODE") == "enterprise":
    container.wms.ledger.override(NatsLedgerAdapter(bus=container.event_bus()))
else:
    container.wms.ledger.override(LocalLedgerAdapter())

---

3. Data Sovereignty & Distributed Reads

In an Enterprise macroservice mesh, database-level Foreign Keys are prohibited across domains. We maintain database autonomy through two distinct patterns:

graph TD
    classDef pattern fill:#f9f,stroke:#333,stroke-width:2px;

    Sub1[StockEntry.supplier_id] -->|Plain String ID| Query{Resolution Pattern}

    Query -->|Pattern A: RPC| RPC[NATS RPC Request]:::pattern
    RPC -->|Consistent State| Core[Core Supplier Service]

    Query -->|Pattern B: CQRS| CQRS[Local CQRS Projection]:::pattern
    CQRS -->|High Throughput| Local[Local ProjectionSupplier Table]

    Core -->|Supplier.updated Event| Event[NATS Event Bus]
    Event -->|Sync Outbox| Local

3.1 Pattern A: Real-Time Request/Response (RPC)

• Use Case: Transactions requiring absolute, highly consistent, real-time validations (e.g., Finance validating supplier payment terms).
• Mechanism: The active adapter dispatches a NATS request: bus.request("rpc.Supplier.get", {"id": supplier_id}).

3.2 Pattern B: CQRS Projections (Local Read-Models)

• Use Case: High-speed, high-throughput operations that require local survivability (e.g., WMS reading Item names during stock receipts).
• Mechanism: The service maintains a lightweight projection_items table locally. A background worker subscribes to item.updated NATS events and updates the local cache, enabling WMS to perform stock validations even if other services are offline.

3.3 Transactional Outbox Pattern

To prevent data loss during transient network disconnects:

1. All out-of-process event broadcasts are first saved to a local Outbox table within the active database transaction.
2. A lightweight background “Relay” worker reads the outbox and attempts to publish to NATS, retrying automatically with exponential backoff until the broker acknowledges.

---

4. Multi-Tier QA Testing Blueprint

Business M ensures absolute stability through four nested testing gates:

graph TD
    Unit[1. pytest Unit Tests] --> Integration[2. Contract Event Tests]
    Integration --> E2E[3. Playwright E2E UI Tests]
    E2E --> Load[4. k6 Load Testing]

4.1 Unit Testing (pytest)

• Every controller and database repository must maintain a minimum of 90% code coverage.
• Mock adapter classes are used to verify business logic in total isolation from networks or databases.

4.2 Integration Contract Tests

• Validate serialization compliance by testing NATS message DTOs.
• Verify that event payload structures conform strictly to shared protocols.

4.3 End-to-End User Flow Validation (Playwright)

• Automated browser runners execute critical user workflows (e.g., creating a Supplier, submitting a Purchase Order, generating a GRN, posting payment entries, and verifying ledger balances).
• Validates that the Tamagui UI transitions cleanly without console or network errors.

4.4 Load & Failover Testing (k6)

• Concurrency Load: Simulation of high-concurrency peak orders (up to 10,000 requests per minute).
• Failover Sanity: Simulates transient NATS connection cuts and restarts to verify that:
  • Critical synchronous operations abort gracefully (rolling back database state).
  • Non-critical asynchronous tasks buffer in the Transactional Outbox and resume processing once connectivity is restored.