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 thebook-keeper(Finance macroservice) andstock-keeper(WMS macroservice) are thin Litestar REST applications that consumeledger-coreadapters, 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.1 Layer Responsibilities
Section titled “1.1 Layer Responsibilities”- 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).
- 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). - The Business Logic Layer: The actual customer-facing
business-mapplication and modular domain business libraries (libs/*for finance, wms, people).
1.2 Extension & Decoupling Model
Section titled “1.2 Extension & Decoupling Model”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.
1.2 Isolated Domain Libraries (libs/)
Section titled “1.2 Isolated Domain Libraries (libs/)”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
BaseDocTypeand referencing global identities securely. - Process Isolation: Every domain library is fully self-contained and testable in isolation.
1.3 Shared Interfaces
Section titled “1.3 Shared Interfaces”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-corefor ledger state, never on other domain implementations. - Example: The WMS module relies on
ledger-coreto 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.
1.4 Core Engines (libs/ledger-core)
Section titled “1.4 Core Engines (libs/ledger-core)”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.
3. Progressive Scaling Modes
Section titled “3. Progressive Scaling Modes”| 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. |
4. Dependency Injection Pattern
Section titled “4. Dependency Injection Pattern”The monorepo switches between monolithic and macroservice configurations at bootstrap by overriding dependency-injection containers:
import osfrom framework_m.container import container
# Read deployment modemode = 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]
- Compliance Contribution: A regional compliance plugin (e.g.
m-india) defines localized schema additions (e.g. adding aGSTINorPANcolumn to the globalSupplierentity). - Domain Aggregation: The active domain owner (Finance) listens for regional metadata contributions and incorporates these localized fields into its
MetadataDecoratorRegistry. - 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.
- Compose & Render: When the Desk UI requests the
Supplierdocument, 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.