🛠️ Installation (Development)
This guide covers setting up a local development environment. For production deployment, see the User Manual Installation.
✅ Prerequisites
- 🐍 Python 3.11+
- 📦 Node.js 18+
- 📋 Pipenv (Python package manager)
- 🐳 Docker (Optional, for production deployment)
📋 Setup Instructions
The project includes a main orchestration script, dev.py, to automate all tasks.
📦 1. Install Dependencies
This command installs all Python and Node.js dependencies for both the backend and frontend.
This will:
- Install backend packages via
pipenv. - Install frontend packages via
npm. - Install Playwright browsers for E2E testing.
🗃️ 2. Initialize the Database
Before starting the server for the first time, create the database:
This command creates a fresh SQLite database with the initial schema.
⚙️ 3. Configure Environment
Copy the example environment file:
The default settings work out of the box. Edit .env if you need to change port or data directory.
🚀 4. Start the Server
To start the FastAPI server with auto-reload:
The server will be available at http://localhost:8000.
For frontend development with Hot Module Replacement, start a second terminal:
The dev server runs at http://localhost:5173 and proxies API calls to the backend.
👤 5. Create a User
To log in, you need to create a user account. The first user automatically becomes the superuser.
Replace <username>, <email>, and <password> with your desired credentials.
🔄 Development Workflow
Once installed, dev.py is your single entry point for every development task.
Run ./dev.py --help for the full command tree.
🖥️ Frontend
| Command | Description | Details |
|---|---|---|
./dev.py front dev |
Start Vite dev server with HMR | Frontend Development |
./dev.py front build |
Production build (or --debug for source maps) |
Frontend Development |
./dev.py front check |
Run svelte-check type checker |
Frontend Development |
./dev.py front preview |
Preview production build locally |
🔗 API Client
| Command | Description | Details |
|---|---|---|
./dev.py api schema |
Export OpenAPI JSON from backend | API Overview |
./dev.py api client |
Generate TypeScript client from schema | API Overview |
./dev.py api sync |
Schema export + client generation in one step | API Overview |
🌍 Internationalization
| Command | Description | Details |
|---|---|---|
./dev.py i18n audit |
Audit missing/extra keys across all languages | i18n |
./dev.py i18n audit --duplicates |
Also report duplicate values | i18n |
./dev.py i18n add KEY --en … --it … |
Add a new key to all language files | i18n |
./dev.py i18n remove KEY |
Remove a key from all files | i18n |
./dev.py i18n search QUERY |
Search keys/values | i18n |
./dev.py i18n tree [PREFIX] |
Show key tree structure | i18n |
🗃️ Database
| Command | Description | Details |
|---|---|---|
./dev.py db create-clean |
Delete DB and recreate with latest migration | Alembic |
./dev.py db upgrade |
Apply pending Alembic migrations | Alembic |
./dev.py db migrate MESSAGE |
Create new auto-generated migration | Alembic |
./dev.py db downgrade |
Rollback one migration step | Alembic |
./dev.py db check |
Verify CHECK constraints | |
./dev.py db current |
Show current migration revision |
🧪 Testing
| Command | Description | Details |
|---|---|---|
./dev.py test all |
Run all test categories in optimal order | Test Walkthrough |
./dev.py test <category> all |
Run a single category (e.g., api, e2e, front-fx) |
Test Walkthrough |
./dev.py test <category> --list |
List available tests without running them | Test Walkthrough |
🧰 Other Tools
| Command | Description |
|---|---|
./dev.py format |
Format Python code with black |
./dev.py lint |
Lint Python code with ruff |
./dev.py mkdocs serve |
Start MkDocs dev server |
./dev.py mkdocs build |
Build MkDocs static site |
./dev.py info api |
Show API info (routes, models) |
./dev.py cache js |
Clear frontend build cache |
./dev.py shell |
Open pipenv shell |