framework-m 0.12.0

A modular, metadata-driven business application framework

Framework M

The complete metadata-driven business application framework for Python 3.12+.

Official Website: frameworkm.dev

📦 Metapackage: This is the primary Framework M package. Installing it gives you everything required to build applications. For individual components, see the Related Packages section.

Overview

Framework M is inspired by Frappe Framework but built with modern Python practices:

• Hexagonal Architecture: Clean separation via Ports & Adapters
• Async-First: Native asyncio with Litestar and SQLAlchemy
• Type-Safe: 100% type hints, mypy strict compatible
• Stateless: JWT/Token auth, no server-side sessions
• Metadata-Driven: Define DocTypes as Pydantic models

Installation

pip install framework-m

Or with uv:

uv add framework-m

Quick Start

1. Define a DocType

from framework_m import DocType, Field

class Todo(DocType):
    """A simple task document."""

    title: str = Field(description="Task title")
    description: str | None = Field(default=None, description="Task details")
    is_completed: bool = Field(default=False, description="Completion status")
    priority: int = Field(default=1, ge=1, le=5, description="Priority (1-5)")

2. Use the CLI

# Show version
m --version

# Show framework info
m info

# Start production server
m prod

# Start development server
m dev

Architecture & Features

Framework M follows a strict Ports & Adapters (Hexagonal) architecture. The core domain logic is isolated from infrastructure concerns.

• Primary Adapters: HTTP API (Litestar), CLI, WebSockets, Job Workers.
• Core Domain: DocTypes, Controllers, and Business Logic.
• Ports (Interfaces): Defined protocols for Repositories, Events, Storage, etc.
• Secondary Adapters: Implementations for PostgreSQL, Redis, S3, etc.

Key Capabilities:

• Automatic CRUD operations (RepositoryProtocol)
• Event-driven architecture (EventBusProtocol)
• Row-level security & permissions (PermissionProtocol)
• Background jobs (JobQueueProtocol)
• File storage abstraction (StorageProtocol)

Technology Stack

• Web Framework: Litestar 2.0+
• ORM: SQLAlchemy 2.0 (Async)
• Validation: Pydantic V2
• Task Queue: Taskiq + NATS JetStream
• DI Container: dependency-injector
• Database: PostgreSQL (default), SQLite (testing)
• Cache: Redis
• Events: NATS JetStream

Development

# Clone and setup
git clone https://gitlab.com/castlecraft/framework-m.git
cd framework-m

# Install dependencies
uv sync --all-packages --all-extras --all-groups

# Run tests
uv run pytest

# Type checking
uv run mypy src/framework_m --strict

# Linting
uv run ruff check .
uv run ruff format .

Documentation

• Architecture Overview
• Contributing Guide
• Phase Checklists

Related Packages

Framework M is split into modular packages:

Package	Description
framework-m	This package - Metapackage with CLI, kernel, and re-exports
framework-m-core	Core protocols and dependency injection
framework-m-standard	Default adapters (SQLAlchemy, Redis, Litestar)
framework-m-studio	Visual DocType builder UI

License

Apache 2.0 License - see LICENSE for details.

Acknowledgments

Inspired by Frappe Framework, reimagined with:

• Modern Python (3.12+, async/await, type hints)
• Clean architecture (Hexagonal/Ports & Adapters)
• No global state (Dependency Injection)
• Code-first schemas (Pydantic, not database JSON)