Framework M Architecture

A guide to understanding Framework M's architecture and project structure.

Overview

Framework M uses Hexagonal Architecture (Ports & Adapters) to maintain clean separation between business logic and infrastructure.

┌─────────────────────────────────────────────────────────────┐
│                    Primary Adapters                         │
│              (HTTP, CLI, Background Jobs)                   │
└─────────────────────────────┬───────────────────────────────┘
                              │
                    ┌─────────▼──────────┐
                    │    Core Domain     │
                    │  (DocTypes, Logic) │
                    └─────────┬──────────┘
                              │
┌─────────────────────────────▼───────────────────────────────┐
│                   Secondary Adapters                        │
│        (Database, Cache, Storage, Events, etc.)             │
└─────────────────────────────────────────────────────────────┘

Project Structure (Monorepo)

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.
   • Recommended for most developers and "Indie" deployments.

Developer Tools (apps/)

• framework-m-studio: Visual DocType builder and CLI scaffolding.
  • Contains m new:app, m new:doctype.
  • Documentation generators.
  • Studio UI (React + Refine).

---

Detailed Directory Map

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

Key Modules

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

Protocol-Based Design

Framework M defines Protocols (interfaces) for all infrastructure concerns:

• See Protocol Reference

This allows you to:

1. Swap implementations without changing business logic
2. Test in isolation with mock adapters
3. Deploy differently (e.g., Redis vs memory cache)

Controller Hooks

Business logic lives in Controllers, not DocTypes. See Defining DocTypes for hook examples.

CLI Commands

Framework M provides CLI tools for development. Run m --help for available commands.

Apps Structure

User applications live in apps/:

apps/
├── your_app/
│   ├── src/
│   │   └── doctypes/
│   │       └── your_doctype/
│   │           ├── __init__.py
│   │           ├── doctype.py      # Schema
│   │           └── controller.py   # Business logic
│   └── pyproject.toml

Next Steps

• Creating Apps - Build your first app
• Defining DocTypes - Advanced patterns