Craft Framework · Open Source MIT

CraftEngine ^v4.3.0

The Python Framework for Expressive Web Applications

Build elegant, production-grade applications in Python with familiar MVC conventions. Craft ORM with dual-key UUIDs, Forge templates, Active Defense WAF, and visual CRUD builder — batteries included.

Read Documentation Quick start Support the project

1,800+ Tests Passing

3 DB Engines

MIT License

Py 3.14+ ASGI Runtime

routes/web.py & app/Models/Post.py

from craft.facades import Route, Auth, DB
from craft.orm.model import Model

class Post(Model):
    __table__ = "posts"
    fillable = ["title", "body", "user_id"]

    def author(self):
        return self.belongs_to(User)

# Expressive REST & Admin Routing
Route.resource("posts", PostController, write_middleware="auth")
Route.get("/admin", [AdminController, "index"])
    .middleware("auth", "role:admin", "firewall")

Rapid Setup

Up and Running in Seconds

From zero to a running application with migrations, seed data, and administrative UI — in four simple steps.

Clone & Configure

$ git clone https://github.com/msrjson/craftengine.git

$ cd craftengine/data && cp .env.example .env

$ python dev.py key:generate

Migrate & Seed

$ python dev.py migrate --seed

Serve Local App

$ python dev.py serve

Run with Docker

$ docker compose up -d --build

App ready on localhost:9000

Core Architecture

Everything You Need, Nothing You Don't

A full-featured framework that respects your time. Familiar MVC conventions tailored for Python developers who demand speed, clarity, and security.

Active Record & Dual-Key UUID

High-performance ORM with eager loading, relationships, soft deletes, query builder, and automatic UUID public resolution — on SQLite, PostgreSQL and MySQL.

Async ASGI Performance

A high-throughput ASGI core: synchronous controllers run in parallel on a thread pool, each borrowing a pooled database connection, with asynchronous controller support.

Active Defense & WAF Firewall

Built-in Web Application Firewall (SQLi, XSS, SSRF protection), honeypot attacker trapping, brute-force cooldown, and audit logging.

Visual & Terminal CRUD Builder

Generate full vertical slices in one command or via the visual web builder: DDL migrations, Models, FormRequests, Resources, and Admin UI.

Forge Template Engine

Expressive, autoescaped templates with directives such as @csrf, @auth, @guest, @can, @honeypot and component layouts.

Developer Console & CLI

Comprehensive CLI tooling: generators, interactive tinker console, database migrator, queue workers, task scheduler, and firewall management.

Verified on every change

Tested as if production depended on it

The whole suite runs against PostgreSQL and SQLite. These numbers are copied from the test report of a real run, not typed in, and the badge below shows the live status of every push.

1,846 tests passing on PostgreSQL PostgreSQL 18.6

1,784 tests passing on SQLite Python 3.14.7

0 failures 111 test files

Nothing is ever deleted

No test deletes, truncates or drops a record. A check fails the build on any such statement, and each PostgreSQL run gets a fresh database of its own.

End-to-end journeys

A project is generated from scratch, then sign-in, registration, the admin panel and generated CRUD screens are used the way a person would - in every language, refusals included.

Documented commands, executed

Every command the documentation and the CLI tell you to run is executed by the suite, so a guide cannot teach one that does not exist.

doctor

Mistakes fail loudly

Unknown template directives, missing controller methods, misconfigured roles and untranslated keys are errors that name the fix, not silent empty pages. craft doctor checks a project before its first request.

Last verified run: 2026-10-04 · commit 4b9d3a6 ·

Secure by Default

Security Is Part of the Engine

The dangerous defaults are closed before you write your first route — not left as a checklist for later.

Argon2id Password Hashing

Memory-hard hashing for new passwords; older bcrypt and PBKDF2 hashes stay verifiable and are upgraded on the next login.

AES-256-GCM Credential Vault

Third-party API keys and OAuth secrets are encrypted at rest with a key derived from the application key — never stored in plaintext.

Context-Bound Signed Tokens

Password-reset and verification tokens are bound to their purpose and context, with optional expiry, so a leaked token cannot be replayed elsewhere.

CSRF, Honeypot & Anti-Spam

Every state-changing form carries @csrf; public forms add honeypot and anti-spam checks compared in constant time, with every trigger recorded as a security event.

Authorization, Not Just Authentication

Gates, policies and role: middleware; the build fails if an admin route is ever declared without an authorizing guard.

Absolute Data Persistence

Forward-only migrations and soft deletes. Destructive commands such as migrate:fresh and db:wipe are banned in every environment.

The Workspace

A Skeleton You Copy, Not a Library You Fight

The repository is the base skeleton for a new application. Clone it, rename it, and the same codebase carries you from a blog to multi-tenant scale.

craftengine/

data/the application, mounted as /app
data/engine/the core, imported as craft.*
data/app/controllers, models, policies, plugins
data/routes/web and API routes
data/resources/views/Forge templates
data/database/forward-only migrations and seeders
data/documentation/35+ guides and llms.txt
data/tests/1,500+ pytest cases
data/dev.pythe developer CLI
.claude/rules/governance and quality gates
.agents/skills for AI coding agents

Modules, Plugins, Container

Core engine, business modules and removable capability plugins, wired through a dependency-injection container and static facades — every service can be mocked in pytest.

Database-Backed i18n

Translations live in the database, not in flat files. Every project is born trilingual — English source, Brazilian Portuguese default, Spanish alternative — with ICU plurals.

Governed Releases

Version, release counter and changelog move together; tests, lint and the language gate must pass before a release is cut. English code, zero hardcoded user-facing copy.

AI-Native

Built for Humans and Coding Agents

Conventions a model already understands, documentation written for machines as well as people, and first-class agent tooling inside the framework.

Model Context Protocol

Declare RBAC-guarded AgentTool classes and expose them over MCP, so assistants and IDEs discover and call your application's tools securely.

Provider-Agnostic AI SDK

One AI facade for text generation and an agent orchestrator, with swappable drivers instead of vendor lock-in.

Machine-Readable Docs

llms.txt, llms-full.txt, CRAFT_ENGINE.md and agent skills give a coding agent the build loop, the limits and what is not built yet.

Measured, Not Claimed

Parallel Requests on One Worker

Measured on the sample application with the bundled load tester, after moving the controller chain onto a thread pool with pooled connections.

~115 req/s from 10 concurrent clients, up from ~27 req/s

0.57 s p95 latency, down from 1.9 s

JSON queued jobs, never pickle — safe across processes

Internal proxy

Modules talk in memory, not over HTTP

External requests go through the HTTP kernel. A call from one module to another goes through the internal proxy: the service is resolved from the container and called on the same thread, inside the same connection and transaction. Before, the same call was a loopback HTTP request through the kernel.

One call between modules

Before: HTTP 817 µs

After: proxy 16 µs

51× cheaper per call, database read included.

Requests per second with 32 clients

Before: HTTP 740 req/s

After: proxy 1,513 req/s

An external request that needs another module, end to end. Higher is better.

p95 latency with 32 clients

Before: HTTP 56 ms

After: proxy 29 ms

The slowest 5% of requests. Lower is better.

Requests per second with 64 clients

Before: HTTP 8 req/s

After: proxy 1,426 req/s

A loopback request holds two of the 40 worker threads, so the pool deadlocks: 89 requests failed. The proxy holds one and failed none.

Measured with the real kernel under uvicorn, one process, on 2026-10-04 · benchmark at commit 480dd2b · Internal proxy guide

CraftEngine v4.3.0