index.md

layout	home
hero	name text tagline actions simple_module_python A modular monolith for Python FastAPI + SQLModel + Inertia.js + React. Plugin modules that compose at boot. No microservice tax, no API-client glue. theme text link brand Get started /guide/quickstart theme text link alt Why a modular monolith? /guide/introduction theme text link alt View on GitHub https://github.com/antosubash/simple_module_python
features	title details link linkText Build with it Five-minute quickstart, then scaffold your first module. You'll learn the loop — add a model, generate a migration, write a service, mount a page. /guide/quickstart Quickstart title details link linkText Author a module Read the framework conventions, then walk through a real module end-to-end. Models, contracts, service, endpoints, pages, tests, locales. /guide/first-module Build a module title details link linkText Use a bundled module Twelve first-party modules ship with the framework — auth, users, keycloak, permissions, settings, file_storage, branding, background_tasks, feature_flags, audit_log, dashboard, site_lock. /modules/ Browse modules title details link linkText Operate it in production Deployment, environment variables, diagnostics, release pipeline, performance + load testing. /reference/deployment Deploy

How the docs are organised

<style> .sm-grid { display: grid; grid-template-columns: repeat(auto-fit, minmax(260px, 1fr)); gap: 1rem; margin: 1rem 0 2rem; } .sm-grid a.sm-card { display: block; padding: 1rem 1.25rem; border: 1px solid var(--vp-c-divider); border-radius: 12px; background: var(--vp-c-bg-soft); text-decoration: none !important; } .sm-grid a.sm-card:hover { border-color: var(--vp-c-brand-1); } .sm-grid a.sm-card h3 { margin: 0 0 .25rem; font-size: 1rem; color: var(--vp-c-brand-1); } .sm-grid a.sm-card p { margin: 0; color: var(--vp-c-text-2); font-size: .9rem; line-height: 1.4; } @media (prefers-reduced-motion: no-preference) { .sm-grid a.sm-card { transition: border-color .15s ease, transform .15s ease; } .sm-grid a.sm-card:hover { transform: translateY(-1px); } } </style>

Guide

Install, bootstrap, and build your first module.

Framework

Discovery, lifecycle hooks, middleware, permissions, events, i18n.

Database

SQLModel conventions, per-module Base, mixins, sessions, Alembic.

Frontend

Inertia page keys, shared props, page discovery, React layout.

Testing

The simple_module_test plugin fixtures, unit tests, end-to-end tests.

Modules

Reference for each bundled module: routes, contracts, settings.

Reference

CLI commands, env vars, diagnostic codes, deployment.

Try it in 60 seconds

uv tool install simple_module_cli   # already installed? uv tool upgrade simple_module_cli
smpy new myapp --yes
cd myapp
make dev          # API on :8000, Vite on :5050

Then in another terminal, inside myapp:

smpy create-module orders --dest modules/orders
smpy add ../modules/orders --path host
make migration msg="add orders tables"   # review the generated revision
make migrate

That generates modules/orders/ with a ModuleMeta, a SQLModel table, contracts, a service, REST + Inertia endpoints, three React pages, locales, and a smoke test, wires it into the host and creates its table; the dev server picks it up when it reloads. The full walkthrough is in Your first module.

Where to start

• New here? Read Introduction for the why, then Quickstart for the how.
• Already convinced? Jump straight to Your first module.
• Need an off-the-shelf piece? See the bundled modules.
• Operating an existing deployment? Start with Commands and Environment variables.

When conventions are ambiguous, the authoritative single-page docs (Framework conventions, Module authoring, E2E testing, Release playbook) are the source of truth.