Architecture

Finances App keeps the core finance model independent from the web UI and optional connectors.

Runtime stack

• FastAPI backend
• SQLite database
• React and TypeScript web UI
• Docker Compose for self-hosted deployment
• VitePress documentation site

The Docker image serves the built React UI and the API from one process.

Source of truth

SQLite and generated files are the source of truth.

Notion is optional. Use it for reviewed imports or snapshot exports, not as a background sync database.

Data ownership model

The auth model has three layers:

• Users are global login identities.
• Workspaces own finance data.
• Workspace memberships connect users to workspaces with owner, admin, or member roles.

Finance records, settings, history, trash, generated files, Notion settings, and managed backups are scoped by workspace.

Generated-file records contain an opaque relative storage_key, never an arbitrary host path. The key resolves beneath INVOICER_FILE_STORAGE and is namespaced by workspace and immutable file ID. Only invoice rendering and reviewed backup restore create these records; the generic CRUD API is read-only for generated-file metadata.

Code layout

Path	Purpose
src/invoicer/core	Finance models and domain logic.
src/invoicer/storage	SQLite persistence.
src/invoicer/api	FastAPI app, auth, and web API routes.
src/invoicer/renderers	PDF rendering.
src/invoicer/connectors/notion	Optional Notion import/export connector.
web	React web app.
docs	VitePress documentation site.
tests	Backend, model, storage, API, and integration tests.

Deployment shape

The default deployment is a single Docker Compose service with a persistent volume:

browser -> FastAPI container -> SQLite database in /data
                         |-> generated files in /data/files
                         |-> managed backups in /data/backups

For public deployments, put the container behind a reverse proxy with HTTPS and set INVOICER_COOKIE_SECURE=1.