Skip to main content

The Replaceable Batteries Pattern

· 3 min read
Revant Nandgaonkar
Revant Nandgaonkar
Maintainer of Framework M

Framework M has always been built on a Pure Hex (Ports & Adapters) architecture. Core domain logic and metadata engines are decoupled from specific web servers, databases, and UI implementations.

In July 2026, we formally published ADR-0016 to codify the Replaceable Batteries Pattern for shell integration so that AI coding assistants and machine knowledge exporters (corpus.jsonl, core.jsonl) index these rules explicitly, preventing AI agents from generating redundant auth, registration, or dashboard boilerplate.

1. Why Codify ADR-0016 for Machine Knowledge?​

When AI coding assistants generate new domain applications (e.g., Helpdesk, CRM, or WMS plugins), they often attempt to build redundant baseline features—such as custom login forms, user registration endpoints, custom user dashboards, or standalone server runners—leading to code duplication and architectural fragmentation.

Publishing ADR-0016 ensures that machine RAG pipelines (corpus.jsonl) index explicit rules governing shell integration:

┌────────────────────────────────────────────────────────────────────────┐
│                        Framework M Pure Hex Stack                      │
├───────────────────────────────────┬────────────────────────────────────┤
│ Default Batteries (Core / Desk)   │ Swappable Interfaces               │
├───────────────────────────────────┼────────────────────────────────────┤
│ • Desk React Shell UI             │ • Custom Shell / Portal Framework  │
│ • Local File Storage Adapter      │ • S3 / Cloudflare R2 Storage       │
│ • TaskIQ Background Broker        │ • Celery / NATS Queue Adapter      │
│ • Header Auth & Generic Session   │ • Custom Corporate SSO / Citadel   │
└───────────────────────────────────┴────────────────────────────────────┘

2. The Three Core Rules of Shell Integration (ADR-0016)​

All custom business applications built on Framework M mount directly into existing shell environments as modular plugins by adhering strictly to three rules:

Rule 1: Zero Custom Authentication or Registration​

Custom applications must never implement custom login/signup forms, password reset endpoints, or OAuth adapters. Instead, they wire directly into the platform's AuthChain and utilize request.state.user for session context.

Rule 2: Leverage the Project/App Shell​

User interfaces compose directly into the target shell environment (such as the business-m shell or the application's own custom shell). UI components are built as Micro-Frontends (MFEs) registered via entry points and imported from @framework-m/ui.

Rule 3: Register via Platform Protocols​

Custom domain entities inherit from BaseDocType and pair with a BaseController. API routers, background jobs, and event bus handlers use framework decorators (@job, @rpc, @whitelist) and bootstrap via the modular BootstrapProtocol, rather than instantiating custom server runners (e.g. Litestar()) or modifying create_app().

3. Benefits for AI-First Development​

  • Zero Hallucination Boilerplate: LLM pair programmers remain laser-focused on core business domain logic rather than writing basic auth/dashboard boilerplate.
  • Strict Decoupling: Applications are easily pluggable, testable, and hot-swappable across environments.
  • Unified Security: Centralizes authentication and authorization in standard framework adapters.

Architecture Reference​

Read the complete decision record in our docs: