Building Block View

The Building Block View provides a static decomposition of the system into its constituent parts, from broad packages down to individual modules.

5.1 Level 1: Core Framework Decomposition

Framework M is split into focused packages to enable flexibility and lean production deployments.

Core Packages (libs/)

1. framework-m-core: The absolute minimum kernel.

   • All Protocols (Interfaces) for Repository, EventBus, Cache, etc.
   • Pydantic-based DocType metadata engine.
   • Dependency Injection container.
   • Zero adapters (infrastructure-free).

2. framework-m-standard: The standard battery of adapters.

   • SQLAlchemy adapters (PostgreSQL/SQLite).
   • NATS adapters for Event Bus and WebSockets.
   • Redis adapters for Caching.
   • Litestar web integration.
   • RBAC Permission system.

3. framework-m: The meta-package.

   • Bundles core + standard.

5.2 Level 2: Repository Structure

libs/
├── framework-m-core/
│   └── src/framework_m_core/
│       ├── domain/              # Base protocols
│       ├── interfaces/          # Protocol definitions (Ports)
│       └── registry.py          # MetaRegistry
│
├── framework-m-standard/
│   └── src/framework_m_standard/
│       ├── adapters/            # Concrete implementations
│       │   ├── db/              # SQLAlchemy
│       │   ├── eventbus/        # NATS
│       │   └── web/             # Litestar
│       └── cli/                 # Standard commands (migrate, start)
│
apps/
└── studio/                      # Studio UI & Scaffolding
    └── src/framework_m_studio/
        ├── cli/                 # Dev commands (new, codegen, docs)
        └── docs_generator.py    # Documentation engine

5.3 Level 3: Internal Module Map

Module	Purpose	Location
framework_m_core.domain	Base classes for DocTypes/Controllers	framework-m-core
framework_m_core.interfaces	System-wide Protocols (contracts)	framework-m-core
framework_m_standard.adapters.db	SQLAlchemy & GenericRepository	framework-m-standard
framework_m_standard.adapters.web	Litestar app factory & Auto-CRUD	framework-m-standard
framework_m_studio.cli.new	Code generation and app templates	framework-m-studio

5.4 Level 4: Frontend Architecture Decomposition

The frontend is a modular multi-tier architecture designed for extensibility and performance via Micro-Frontends (MFE).

Core Frontend Packages (libs/)

1. framework-m-ui: The Design System and Component Library.

   • Tamagui Engine: Built on top of the Tamagui engine, providing high-performance styling and layout.
   • MComponents Abstraction: This allows the internal engine (Tamagui) to be swapped or upgraded in the future without breaking plugin consumption.
   • Mobile/RN Ready: Inherits React Native compatibility from Tamagui, enabling a future path for cross-platform mobile apps.
   • Token-Based Customization: Heavily utilizes a token system (Themes/Sizing/Spacing) for easy white-labeling and theming.
   • Headless Core: Combines framework-agnostic Vanilla CSS with React-based headless logic for accessibility and state management.
   • Shared Library: Provides the core UI primitives (Tables, Inputs, Modals) used by both the Desk Host and individual MFE Plugins.

2. framework-m-desk: The Unified Workspace Shell (Host).

   • Standard Bundled Shell: The framework provides a preconfigured development and production desk ("The Desk") that is ready-to-use out of the box with standard framework-m library integrations. (This is packed as wheels within the framework-m-standard package).
   • Scaffolded Custom Shell: Developers can use the core m libraries (desk, ui, sdk) to scaffold their own completely bespoke shell apps while maintaining native support for "Framework M Plugins".
   • Plugin Orchestrator: Manages the lifecycle of loaded MFEs, providing shared state, authentication, and layout slots (sidebar, headers, content).

3. framework-m-vite-plugin: The Build-Time Orchestrator.

   • Auto-Discovery: Scans the workspace/filesystem for compatible plugin packages and generates a virtual module (virtual:framework-m-plugins) for registration.
   • Monolith Mode: Bundles all discovered internal packages into a single cohesive deployment—ideal for initial development or smaller deployments.
   • Distributed MFE Mode: Leverages Module Federation to build independent, versioned plugin bundles that the shell loads at runtime. This enables decentralized development and independent deployments across teams.

4. framework-m-plugin-sdk: The Plugin Contract.

   • JS-side protocols for communicating with the framework-m-desk shell.
   • Exposes UI hooks and API callers for plugin developers.

Frontend Module Map

Package	Key Responsibility	Location
framework-m-ui	Consistent design tokens and components	libs/framework-m-ui
framework-m-desk	Unified workspace shell and auth host	libs/framework-m-desk
framework-m-vite-plugin	Seamless MFE bundling and HMR	libs/framework-m-vite-plugin
framework-m-plugin-sdk	Plugin runtime API and bridge	libs/framework-m-plugin-sdk
frontend (Host App)	Deployment glue for the shell	frontend/

graph TD
    subgraph "Workspace Shell (Host)"
      Desk[framework-m-desk]
    end

    subgraph "Shared Foundation"
      UI[framework-m-ui]
      SDK[framework-m-plugin-sdk]
    end

    subgraph "Micro-Frontends (MFE)"
      Plugin1[Order Management]
      Plugin2[Warehouse App]
    end

    Desk --> UI
    Desk --> SDK
    Plugin1 --> SDK
    Plugin2 --> SDK
    Plugin1 -.-> Desk
    Plugin2 -.-> Desk