Craft Engine Documentation
A batteries-included Python web framework built on Starlette.
Looking for the big picture first — what the engine contains, the build loop,
scaling from a blog to multi-tenant, and what is not implemented yet? That is
CRAFT_ENGINE.md.
Getting started
| Guide | What it covers |
|---|---|
| Introduction | What Craft Engine is and how the pieces fit together |
| Architecture | Engine vs application; module, plugin, theme and connector responsibilities; CMS composition |
| Installation | Requirements, setup, Docker, first run |
| Configuration | config/, .env, and the env() helper |
| The dev CLI | Every command, and the generators |
| DX Acceleration | ORM mixins (Sluggable, Publishable), fast domain development for AI & Senior Devs |
| Market Evaluation | Technical assessment & positioning for AI Agents and Senior Developers |
The essentials
| Guide | What it covers |
|---|---|
| Service container | Binding, resolution, autowiring, service providers |
| Routing | Routes, groups, resources, route middleware |
| Authentication | Login routes, session flow, and route protection |
| Controllers | Controllers, requests, responses |
| Views | The Forge engine, Forge directives, layouts |
| Validation | Rules, FormRequest, error handling |
Database
| Guide | What it covers |
|---|---|
| Migrations | Schema builder, batches, rollback |
| Database safety | Absolute data persistence, banned destructive commands, soft-delete patterns |
| ORM | Models, relationships, eager loading, soft deletes |
| Query builder | Filtering, joins, aggregates, pagination |
| PostgreSQL | Tenant isolation with RLS, SKIP LOCKED queues, advisory locks, JSONB/range/full-text/vector macros, partitioning |
| CRUD builder | Generating a migration, model, request, resource, API and admin UI for an entity |
Application features
| Guide | What it covers |
|---|---|
| Security | Authentication, authorization, WAF/firewall, honeypot, audit logs, sessions, CSRF |
| Authorization (RBAC) | Roles, permissions, the Gate fallback, role:/permission: middleware |
| Sessions | Drivers, flash data, CSRF tokens |
| Cache | Stores, TTL, remember, prefix flush, idempotent writes |
| Queues and events | Jobs, workers, listeners |
| Extensions | Modules, plugins, themes and connectors: manifest, lifecycle, forward updates, fault isolation, scaffolding |
| Plugins | Plugin extensions, the official plugins (QR code, PIX BR Code, document seal, mutual TLS, privacy kit, SEO, Brazil validator), and moving a legacy plugins/ plugin |
| Engine lifecycle | craft-engine.lock: pin, drift, patches, hotfix, update and upgrade |
| Internal proxy | Module-to-module calls in memory, never through the HTTP kernel |
| API resources | Shaping JSON output |
| Localization | BCP 47 locales, fallback chain, translations |
Working on your app
| Guide | What it covers |
|---|---|
| Testing | Running the suite, fixtures, testing against PostgreSQL |
| Deployment | Production checklist, Docker, health probes, rolling deploys, the connection budget |
| Behind a reverse proxy | Apache and nginx in front of the ASGI process, forwarded headers, host requirements |
| Release synchronization | release:sync / release:status, the VERSION file, the release_syncs trail |
| Observability | Request correlation, structured logging, metrics, error reporting |