Skip to main content

Getting Started with Framework M

A quick guide to create your first Framework M application.

Prerequisites​

  • Python 3.12+ - Check with python --version
  • uv - Python package manager (install)

Installation​

Framework M is installed as a Python package:

# Create a new project directory
mkdir my-project && cd my-project

# Initialize with uv
uv init

# Add framework-m dependency
uv add framework-m

Create Your First App​

Framework M organizes code into apps. Each app contains DocTypes (data models).

# Create a new app called "crm"
uv run m new:app crm

This creates:

crm/
├── src/
│   └── crm/              # Namespaced package
│       ├── __init__.py
│       └── doctypes/
│           └── __init__.py
├── tests/
│   └── __init__.py
├── pyproject.toml
└── README.md

Create Your First DocType​

A DocType defines a data model (like a database table). Let's create a Contact DocType:

cd crm
uv run m new:doctype Contact

This creates:

src/crm/doctypes/contact/
├── __init__.py
├── doctype.py      # Schema definition
└── controller.py   # Business logic

tests/doctypes/contact/
└── test_contact.py # Tests

Edit the DocType​

Open src/crm/doctypes/contact/doctype.py and add fields:

"""Contact DocType."""

from __future__ import annotations

from typing import ClassVar

from pydantic import Field

from framework_m import DocType, Field


class Contact(DocType):
    """Contact - stores customer information."""

    __doctype_name__: ClassVar[str] = "Contact"

    # Fields
    first_name: str = Field(description="First name")
    last_name: str = Field(description="Last name")
    email: str = Field(default="", description="Email address")
    phone: str = Field(default="", description="Phone number")

    class Meta:
        """DocType metadata."""

        naming_rule: ClassVar[str] = "autoincrement"
        is_submittable: ClassVar[bool] = False

Run Database Migration​

Before using the DocType, create its database table:

# Initialize Alembic (first time only)
uv run m migrate init

# Create migration file
uv run m migrate create "Add Contact doctype" --autogenerate

# Run the migration
uv run m migrate

Start Development Server​

Framework M provides development commands with hot reload:

# Start with hot reload (recommended for development)
uv run m dev

# Or for production mode
uv run m start

Open http://localhost:8000 in your browser.

Verify via API​

The Studio exposes a REST API. Test it with curl:

# List all contacts
curl http://localhost:8000/api/v1/resource/Contact

# Create a contact
curl -X POST http://localhost:8000/api/v1/resource/Contact \
  -H "Content-Type: application/json" \
  -d '{"first_name": "John", "last_name": "Doe", "email": "john@example.com"}'

Next Steps​