Skip to content

Architecture & Progressive Scaling

Business M is built on the core principle of Progressive Scaling. By utilizing the orchestrator architecture of Framework M, the system can deploy as a highly efficient unified monolith in Indie Mode, or seamlessly decompose into a distributed, out-of-process macroservice mesh in Enterprise Mode—all without rewriting a single line of business logic.

Key Library: libs/ledger-core (lib-ledger-core) is the foundational shared library implementing Ports and Adapters for double-entry financial ledgers and stock inventory ledgers. Both the book-keeper (Finance macroservice) and stock-keeper (WMS macroservice) are thin Litestar REST applications that consume ledger-core adapters, providing an out-of-process ledger API to the rest of the system.


1. Core Architecture Model: The Three-Tier Flow

Section titled “1. Core Architecture Model: The Three-Tier Flow”

At its heart, the system separates high-performance infrastructure engines from domain logic using a decoupled three-tier architecture:

graph TD
    User[👤 User / Frontend Client] -->|Interacts With| Business[💼 Business Logic Layer<br>business-m / libs/*]
    Business -->|Delegates to Interfaces| Adapters[🔌 Core Engines<br>ledger-core]
    Adapters -->|Manages States & Records| Engine[⚡ Engine Layer<br>TigerBeetle / PostgreSQL / Redis / NATS / Temporal / S3 / Gotenberg]
  1. The Engine Layer: Specialized infrastructure and database engines optimized for distinct tasks (e.g., TigerBeetle for financial ledger entries, PostgreSQL for relational metadata, Redis for state caching, NATS for event messaging, Temporal for durable workflows, and Gotenberg for high-fidelity document generation).
  2. The Core Engines: Foundational libraries (ledger-core) that translate domain intents into specialized database/engine queries (e.g., direct interactions with the WMS stock ledger or Finance TigerBeetle ledger).
  3. The Business Logic Layer: The actual customer-facing business-m application and modular domain business libraries (libs/* for finance, wms, people).

Under this model, the boundaries remain absolute:

  • The User interacts exclusively with the Business Logic Layer.
  • The Business Logic Layer interacts only with the Core Engines (like ledger-core).
  • The Core Engines translate domain intents and manage interactions directly with the raw Engine Layer.

2. Architectural Blueprint & Component Layers

Section titled “2. Architectural Blueprint & Component Layers”

Our monorepo organizes domain layers into distinct, decoupled segments:

graph TD
    Gate[Desk UI Shell / Host Gateway] -->|Composition| DC_Finance[Finance Remote MFE]
    Gate -->|Composition| DC_WMS[WMS Remote MFE]
    Gate -->|Composition| DC_POS[POS Remote MFE]

    DC_Finance -->|REST / API| Gateway[API Proxy Gateway]
    DC_WMS -->|REST / API| Gateway
    DC_POS -->|REST / API| Gateway

    Gateway -->|Local Call / RPC| Core[Core Engines]
    Core -->|In-Process IPC| Local[Local ledger-core integration]
    Core -->|Out-of-Process NATS| Remote[Remote NATS proxy]

    Local --> FinanceLib[Finance Core Domain Lib]
    Remote --> FinanceService[Finance Macroservice / Postgres]

1.1 The Base Host Gateway (apps/business-m)

Section titled “1.1 The Base Host Gateway (apps/business-m)”

The central coordinator and UI orchestrator.

  • Global Masters: Manages fundamental, cross-domain identities (such as Party, Item, Customer, Supplier, Address) in a single shared database context.
  • Host Shell: Renders the React/Tamagui sidebar navigation, notifications, and micro-frontend wrappers.

Core enterprise modules (WMS, Finance, People, POS) are developed as decoupled Python libraries.

  • Bounded Contexts: Each domain maintains its own database models and controllers, inheriting from BaseDocType and referencing global identities securely.
  • Process Isolation: Every domain library is fully self-contained and testable in isolation.

To enforce strict decoupling and prevent circular dependencies, domain interactions rely on Core Engines (like ledger-core) rather than cross-domain imports:

  • Domains depend exclusively on ledger-core for ledger state, never on other domain implementations.
  • Example: The WMS module relies on ledger-core to post inventory valuation adjustments. WMS remains completely unaware of whether the ledger posts via a same-process Finance library or a remote out-of-process service.

Provides robust concrete implementations for interacting with the infrastructure layers across environments:

  • Local Processing: Handles direct method calls for single-process deployments (Indie Mode) using ledger-core.
  • NATS Proxies: Can proxy calls over a secure NATS event bus using out-of-process RPC requests when scaled into Enterprise Mode.

Metric Indie Mode (Monolith) Enterprise Mode (Macroservices)
Process Topology All domains loaded in a single Python process. Each domain deployed in a dedicated Docker/Kubernetes container.
Communication Direct in-memory IPC via Local Adapters. High-throughput NATS PubSub / RPC event bus.
Database Structure Single, unified production PostgreSQL instance. Decentralized, dedicated PostgreSQL databases per macroservice.
UI Delivery Vite Module Federation from python entrypoints. Vite Module Federation with independent remote shells.

The monorepo switches between monolithic and macroservice configurations at bootstrap by overriding dependency-injection containers:

import os
from framework_m.container import container
# Read deployment mode
mode = os.environ.get("M_MODE", "indie")
if mode == "enterprise":
# In Enterprise Mode: WMS calls the out-of-process book-keeper/stock-keeper
# macroservices via a lightweight NATS proxy adapter (no Finance domain dependency)
from m_adapters.finance.ledger import NatsLedgerAdapter
container.wms.ledger.override(NatsLedgerAdapter(bus=container.event_bus()))
else:
# In Indie Mode: WMS calls Finance directly in-process.
# Finance internally uses ledger-core adapters (TigerBeetleLedger / SqlAlchemyLedger)
# to talk to the actual TigerBeetle / Postgres engine.
from finance.adapters.local_ledger import LocalLedgerAdapter
container.wms.ledger.override(LocalLedgerAdapter())

5. Regional Augmentation & Metadata Aggregation

Section titled “5. Regional Augmentation & Metadata Aggregation”

Business M coordinates localization and regulatory compliance (e.g. m-india, m-regional) through decentralized metadata aggregation:

graph LR
    Regional[m-india Compliance Plugin] -->|"Emit Field Metadata (GST/PAN)"| Finance[Finance Domain Owner]
    Finance -->|"Bakes Schemas"| Baked[Augmented Supplier Schema]
    Baked -->|"Render Form"| Gate[Host Gateway UI]
  1. Compliance Contribution: A regional compliance plugin (e.g. m-india) defines localized schema additions (e.g. adding a GSTIN or PAN column to the global Supplier entity).
  2. Domain Aggregation: The active domain owner (Finance) listens for regional metadata contributions and incorporates these localized fields into its MetadataDecoratorRegistry.
  3. Baking Schemas: The Finance module “bakes” these fields into the database schema. Only the Finance module needs to know how to validate or store these regional compliance columns.
  4. Compose & Render: When the Desk UI requests the Supplier document, the gateway query forwards the request to the Finance service, which returns the fully baked, augmented schema. The Gateway simply renders the fields, keeping its core codebase free of regional complexity.