A full-stack generic CRUD application template. Define your entities in configuration files and the framework auto-generates backend routers, API client functions, and frontend pages.
- Auto-generated CRUD -- declare resources in config and get full create, read, update, delete endpoints and UI pages
- Hierarchical groups -- dot-notation taxonomy (e.g.
engineering.backend) with parent-child relationships - Nested resources -- items with child details, managed through parent routes
- Search and filter -- real-time text search with group dropdown filter
- Backup and restore -- download the entire database as JSON or upload a JSON file to restore it
- Microsoft Entra ID authentication -- OIDC + OAuth 2.0 with PKCE, RBAC roles, and JWT validation
- Seed data -- ships with example groups and items for quick start
| Layer | Technology |
|---|---|
| Backend | Python 3.11+, FastAPI, SQLAlchemy 2 (async), Pydantic v2 |
| Database | SQLite (local dev / Docker) or PostgreSQL (production) |
| Frontend | React 19, React Router 7, Vite 8 |
| Auth | Microsoft Entra ID (MSAL.js + PyJWT) |
| Testing | pytest, Vitest, Playwright |
| Packaging | uv (Python), npm (Node) |
| Container | Docker (multi-stage, multi-platform) + Docker Compose |
| CI/CD | GitHub Actions |
| Deployment | Kubernetes (k3s) with Traefik + CloudNativePG |
- Python 3.11+ with uv
- Node.js 22+ with npm
uv sync
cp .env.example .env
uv run uvicorn app.main:app --reload --port 8000The database is created automatically on first launch and seeded with example data.
cd frontend
npm install
npm run devOpen http://localhost:5173. The dev server proxies API calls to port 8000.
Configure local .env files and GitHub environments from a single config.cue:
cp config.cue.example config.cue # fill in your values
python scripts/init.py # generates .env files + pushes GitHub secretsSee Setup for full details.
docker compose up --build -dThe app is served at http://localhost:5173 (mapped from container port 8000). The SQLite database is persisted in a Docker named volume.
| Document | Description |
|---|---|
| Architecture | System design, generic CRUD framework, data model |
| Setup | Installation and local development |
| Configuration | Environment variables reference |
| API | REST API endpoints and data model |
| Authentication | Microsoft Entra ID setup and auth flows |
| Development | Coding conventions, adding entities, linting |
| Testing | Backend, frontend unit, and E2E testing |
| Deployment | Docker, Kubernetes, CI/CD pipelines |
Internal project -- see repository access settings.