Skip to main content

Concepts

This section provides a deep dive into the fundamental concepts and recurring patterns used across Framework M.

8.1 The DocType Pattern​

At the core of Framework M is the DocType (Document Type), a metadata-driven approach to defining business entities.

  • Pydantic Metadata: Schemas are defined as Pydantic models, providing runtime validation and IDE type-safety.
  • Metadata Endpoints: Global metadata registries allow generic UI components (like the Desk) to automatically render forms and lists without manual frontend coding.

8.2 Dependency Injection (DI) as Universal Composer​

Framework M uses the dependency-injector library as its primary orchestration mechanism. This provides a unified composition layer across all execution contexts, ensuring that the same services and adapters are available regardless of how the system is invoked:

  • API Layer: Services are wired into request handlers via the DI container.
  • CLI Framework (Typer): Services are provided to terminal commands.
  • Background Jobs (Taskiq): Workers bootstrap the same DI container to process jobs.
  • Interactive REPL: Developers can access the full service layer in a shell.
  • Testing (Pytest): Providers are overridden via fixtures for mocking.

8.3 Hexagonal Adapters & Repository Pattern​

Business logic is decoupled from infrastructure through formal Protocols (Interfaces).

  • Repositories: Standardized CRUD interfaces for data access.
  • Controllers: Where DocType-specific business logic and lifecycle hooks (validate, before_save, after_save) live.
  • Adapters: Concrete implementations for specific databases (SQLAlchemy), message brokers (NATS), or caches (Redis).

8.4 Plugin Discovery via Python Entrypoints​

Framework M discovers adapters and plugins dynamically through Python entrypoints in pyproject.toml. This allows for a "Zero-Cliff" future where any part of the system can be extended or replaced by a third-party package without modifying the core framework code.

8.5 Unit of Work (UoW)​

The Unit of Work (UoW) is a behavioral pattern used to maintain a list of objects affected by a business transaction and coordinate the writing out of changes and the resolution of concurrency problems.

In Framework M, the UoW acts as the transactional orchestrator:

  • Atomic Operations: It ensures that changes across multiple repositories (e.g., updating an Order and decreasing Stock) are committed atomically within a single database transaction.
  • Adapter Coordination: It manages the lifecycle of database sessions and message broker connections, ensuring that events are only emitted to NATS JetStream after the database transaction has successfully committed.
  • Rollback Safety: If any part of the unit fails, the UoW guarantees a clean rollback across all participating adapters to prevent data corruption.

8.6 Frontend Modular Architecture (MFE)​

The frontend is a modular, high-performance architecture centered around the Desktop Workspace Shell and external Plugins. Depending on the deployment needs, it supports two distinct orchestration modes:

  • Distributed MFE Mode: Utilizing a Micro-Frontend approach, the framework-m-desk acts as a host that dynamically loads "Plugin MFEs" via Vite-powered module federation. This is ideal for large, independently-deployable macroservices.
  • Monolith Single Bundle Mode: For smaller projects or unified deployments, the framework-m-vite-plugin can automatically collapse all discovered plugins into a single, optimized production bundle. This simplifies deployment by serving everything from a single static directory.
  • Tamagui Styling Engine: The framework uses Tamagui as its primary styling and layout engine, providing performance-optimized CSS-in-JS that remains compatible with React Native.
  • MComponents Abstraction: To avoid vendor lock-in, all UI primitives (Tabs, Modals, Tables) are wrapped and exposed via MComponents. This ensures that the underlying engine can be swapped or upgraded without modifying plugin code.
  • Token-Driven Tokens: Architecture is strictly token-based (Themes, Spacing, Typography), enabling unified customization ("White Labeling") across the entire system by simply updating the framework-m-ui theme configuration.
  • Host-Plugin Bridge: Communication between the shell and plugins is handled through the Plugin SDK, which provides formal JS protocols for sidebar registration, menu items, and global state access.