🛠️ Installation (Development)

This guide covers setting up a local development environment. For production deployment, see the User Manual Installation.

✅ Prerequisites

The project includes a main orchestration script, dev.py, to automate all tasks.

This command installs all Python and Node.js dependencies for both the backend and frontend.

./dev.py install

This will:

Before starting the server for the first time, create the database:

./dev.py db create-clean

This command creates a fresh SQLite database with the initial schema.

Copy the example environment file:

cp .env.example .env

The default settings work out of the box. Edit .env if you need to change port or data directory.

To start the FastAPI server with auto-reload:

./dev.py server

The server will be available at http://localhost:8000.

For frontend development with Hot Module Replacement, start a second terminal:

./dev.py front dev

The dev server runs at http://localhost:5173 and proxies API calls to the backend.

To log in, you need to create a user account. The first user automatically becomes the superuser.

./dev.py user create <username> <email> <password>

Replace <username>, <email>, and <password> with your desired credentials.

Once installed, dev.py is your single entry point for every development task. Run ./dev.py --help for the full command tree.

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

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

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

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

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

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