# weedpump/nia-todo architecture

> Architecture diagram of the GitHub repository weedpump/nia-todo, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/weedpump/nia-todo
- Repository: https://github.com/weedpump/nia-todo

## Overview

#### Purpose and entry points
nia-todo is a self-hosted, multi-client todo system: FastAPI backend, SQLite persistence, offline-capable web/PWA, and Tauri native shells for desktop/Android. Server startup is centered on `api/main.py` and `api/run_server.py`; deployment wraps this through `Dockerfile`, `docker-compose.yml`, and `packaging/systemd/nia-todo.service`.

#### Backend HTTP and realtime boundary
FastAPI routers expose the application contract for setup, authentication, todos, projects, sections, workspaces, sharing, admin, reminders, push, and WebSocket updates. The composition boundary is `api/main.py`; endpoint domains live under `api/routers/todos.py`, `api/routers/projects.py`, and `api/routers/websocket.py`. Security/CORS are request middleware concerns in `api/middleware/security.py` and `api/middleware/dynamic_cors.py`.

#### Persistence and lifecycle
SQLite is the authoritative transactional store, accessed through `api/db.py`. Schema evolution is ordered SQL migrations beginning at `api/migrations/001_initial_schema.sql` and extending through `api/migrations/050_add_todo_attachments.sql`, executed by `api/migrate.py`. Runtime data also contains generated keys, avatars, attachments, and backups; persistence must be mounted in container deployments.

#### Domain services and access control
Routers delegate cross-cutting workflows to services rather than embedding all policy in endpoints. Authentication/session/API-key behavior is concentrated in `api/services/auth.py`; MFA, WebAuthn/passkeys, and OIDC are separated into `api/services/two_factor.py`, `api/services/webauthn.py`, and `api/services/oidc.py`. Sharing and attachment handling have dedicated boundaries in `api/services/sharing.py` and `api/services/attachments.py`, enforcing per-user/shared-project access around stored data.

#### Web/PWA client and offline synchronization
The browser client is a static JavaScript application rooted at `web/index.html`, bootstrapped by `web/static/js/main.js`. Client state and rendering coordinate API modules and feature modules; offline mutations are persisted and replayed through `web/static/js/sync/queue.js` and `web/static/js/features/sync-controller.js`. The service worker at `web/sw.js` provides app-shell/offline coverage, while `web/static/js/features/websocket-client.js` receives server-side changes for realtime convergence.

#### Native clients and platform bridge
Tauri packages the same web UI as Windows, Debian, and Android clients. Rust application entrypoints are `src-tauri/src/main.rs` and `src-tauri/src/lib.rs`; native capabilities and allowed bridge operations are declared in `src-tauri/capabilities/default.json` and `src-tauri/permissions/autogenerated/`. The web layer invokes native-only concerns—notifications, reminders, downloads, OIDC handoffs, passkeys—through `web/static/js/features/native-bridge.js`. Android-specific receivers and OIDC callback handling reside under `src-tauri/gen/android/app/src/main/java/de/tobiaskneidl/nia_todo/`.

#### External integrations and operations
SMTP email, web push, OIDC providers, BrainDump STT/LLM endpoints, and update checks are service-level integrations in `api/services/email.py`, `api/services/push.py`, `api/services/oidc_config.py`, and `api/services/braindump_v2.py`. Debian operations include backup/restore and controlled update scripts under `scripts/backup.sh`, `scripts/nia-todo-restore.sh`, and `scripts/nia-todo-server-update.sh`; scheduled backups are provisioned by `packaging/systemd/nia-todo-backup.timer`.

Main entry points: [`web/static/js/main.js`](https://github.com/weedpump/nia-todo/blob/main/web/static/js/main.js) (Web application), [`api/routers/todos.py`](https://github.com/weedpump/nia-todo/blob/main/api/routers/todos.py) (Todo and project routers), [`api/db.py`](https://github.com/weedpump/nia-todo/blob/main/api/db.py) (SQLite data store), [`api/main.py`](https://github.com/weedpump/nia-todo/blob/main/api/main.py) (FastAPI application)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_backend["Backend API"]
  node_api_app["FastAPI application<br/>HTTP composition<br/>[main.py]"]
  node_routers["Todo and project routers<br/>HTTP endpoints<br/>[todos.py]"]
  node_websocket_router["WebSocket updates<br/>realtime endpoint<br/>[websocket.py]"]
  node_security["Security and CORS<br/>request middleware<br/>[security.py]"]
  node_auth["Auth and identity<br/>domain service<br/>[auth.py]"]
  node_sharing["Sharing access control<br/>domain service<br/>[sharing.py]"]
  node_attachments["Attachment service<br/>domain service<br/>[attachments.py]"]
  node_integrations{{"External integrations<br/>service integrations<br/>[email.py]"}}
end

subgraph group_web["Web / PWA"]
  node_web_app["Web application<br/>static JavaScript client<br/>[main.js]"]
  node_offline_queue["Offline mutation queue<br/>sync persistence<br/>[queue.js]"]
  node_sync_controller["Sync controller<br/>client synchronization<br/>[sync-controller.js]"]
  node_service_worker["PWA service worker<br/>offline app shell<br/>[sw.js]"]
  node_websocket_client["Realtime client<br/>WebSocket consumer"]
end

subgraph group_native["Native Clients"]
  node_native_bridge["Native bridge<br/>[native-bridge.js]"]
  node_tauri_shell["Tauri desktop and Android shell<br/>native runtime<br/>[main.rs]"]
  node_native_capabilities["Native capabilities<br/>bridge permissions<br/>[default.json]"]
  node_android_handlers["Android receivers and callbacks<br/>Android integration"]
end

subgraph group_operations["Persistence &amp; Operations"]
  node_sqlite[("SQLite data store<br/>transactional persistence<br/>[db.py]")]
  node_migrations["SQL migrations<br/>schema lifecycle<br/>[migrate.py]"]
  node_deployment["Container and systemd deployment<br/>server operation"]
  node_backup["Backup and restore<br/>operations scripts<br/>[backup.sh]"]
end

node_deployment -->|"runs"| node_api_app
node_backup -->|"backs up and restores"| node_sqlite
node_migrations -->|"evolves schema"| node_sqlite
node_api_app -->|"applies"| node_security
node_api_app -->|"mounts"| node_routers
node_api_app -->|"mounts"| node_websocket_router
node_routers -->|"authenticates through"| node_auth
node_routers -->|"enforces sharing through"| node_sharing
node_routers -->|"handles files through"| node_attachments
node_routers -->|"reads and writes"| node_sqlite
node_auth -->|"stores identity data"| node_sqlite
node_sharing -->|"checks access data"| node_sqlite
node_attachments -->|"stores metadata and files"| node_sqlite
node_integrations -.->|"supports OIDC configuration"| node_auth
node_web_app -->|"calls HTTP API"| node_routers
node_web_app -->|"queues offline changes"| node_offline_queue
node_sync_controller -->|"replays"| node_offline_queue
node_web_app -->|"coordinates sync"| node_sync_controller
node_service_worker -->|"caches app shell"| node_web_app
node_websocket_client -->|"receives changes from"| node_websocket_router
node_web_app -->|"uses"| node_websocket_client
node_web_app -->|"invokes when native"| node_native_bridge
node_native_bridge -->|"calls"| node_tauri_shell
node_tauri_shell -->|"is constrained by"| node_native_capabilities
node_tauri_shell -->|"integrates Android handlers"| node_android_handlers

click node_api_app "https://github.com/weedpump/nia-todo/blob/main/api/main.py"
click node_routers "https://github.com/weedpump/nia-todo/blob/main/api/routers/todos.py"
click node_websocket_router "https://github.com/weedpump/nia-todo/blob/main/api/routers/websocket.py"
click node_security "https://github.com/weedpump/nia-todo/blob/main/api/middleware/security.py"
click node_auth "https://github.com/weedpump/nia-todo/blob/main/api/services/auth.py"
click node_sharing "https://github.com/weedpump/nia-todo/blob/main/api/services/sharing.py"
click node_attachments "https://github.com/weedpump/nia-todo/blob/main/api/services/attachments.py"
click node_integrations "https://github.com/weedpump/nia-todo/blob/main/api/services/email.py"
click node_sqlite "https://github.com/weedpump/nia-todo/blob/main/api/db.py"
click node_migrations "https://github.com/weedpump/nia-todo/blob/main/api/migrate.py"
click node_deployment "https://github.com/weedpump/nia-todo/blob/main/Dockerfile"
click node_backup "https://github.com/weedpump/nia-todo/blob/main/scripts/backup.sh"
click node_web_app "https://github.com/weedpump/nia-todo/blob/main/web/static/js/main.js"
click node_offline_queue "https://github.com/weedpump/nia-todo/blob/main/web/static/js/sync/queue.js"
click node_sync_controller "https://github.com/weedpump/nia-todo/blob/main/web/static/js/features/sync-controller.js"
click node_service_worker "https://github.com/weedpump/nia-todo/blob/main/web/sw.js"
click node_websocket_client "https://github.com/weedpump/nia-todo/blob/main/web/static/js/features/websocket-client.js"
click node_native_bridge "https://github.com/weedpump/nia-todo/blob/main/web/static/js/features/native-bridge.js"
click node_tauri_shell "https://github.com/weedpump/nia-todo/blob/main/src-tauri/src/main.rs"
click node_native_capabilities "https://github.com/weedpump/nia-todo/blob/main/src-tauri/capabilities/default.json"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_api_app,node_routers,node_websocket_router,node_security,node_auth,node_sharing,node_attachments,node_integrations toneBlue
class node_web_app,node_offline_queue,node_sync_controller,node_service_worker,node_websocket_client toneAmber
class node_native_bridge,node_tauri_shell,node_native_capabilities,node_android_handlers toneMint
class node_sqlite,node_migrations,node_deployment,node_backup toneRose
```

## Components

### Backend API

- [FastAPI application](https://github.com/weedpump/nia-todo/blob/main/api/main.py): HTTP composition · Composes API routers and realtime endpoints. · `api/main.py`
- [Todo and project routers](https://github.com/weedpump/nia-todo/blob/main/api/routers/todos.py): HTTP endpoints · `api/routers/todos.py`
- [WebSocket updates](https://github.com/weedpump/nia-todo/blob/main/api/routers/websocket.py): realtime endpoint · `api/routers/websocket.py`
- [Security and CORS](https://github.com/weedpump/nia-todo/blob/main/api/middleware/security.py): request middleware · `api/middleware/security.py`
- [Auth and identity](https://github.com/weedpump/nia-todo/blob/main/api/services/auth.py): domain service · Sessions, API keys, MFA, passkeys, and OIDC flows. · `api/services/auth.py`
- [Sharing access control](https://github.com/weedpump/nia-todo/blob/main/api/services/sharing.py): domain service · `api/services/sharing.py`
- [Attachment service](https://github.com/weedpump/nia-todo/blob/main/api/services/attachments.py): domain service · `api/services/attachments.py`
- [External integrations](https://github.com/weedpump/nia-todo/blob/main/api/services/email.py): service integrations · Email, push, OIDC configuration, and BrainDump endpoints. · `api/services/email.py`

### Web / PWA

- [Web application](https://github.com/weedpump/nia-todo/blob/main/web/static/js/main.js): static JavaScript client · Browser UI, state, rendering, and API feature modules. · `web/static/js/main.js`
- [Offline mutation queue](https://github.com/weedpump/nia-todo/blob/main/web/static/js/sync/queue.js): sync persistence · Persists and replays browser mutations. · `web/static/js/sync/queue.js`
- [Sync controller](https://github.com/weedpump/nia-todo/blob/main/web/static/js/features/sync-controller.js): client synchronization · `web/static/js/features/sync-controller.js`
- [PWA service worker](https://github.com/weedpump/nia-todo/blob/main/web/sw.js): offline app shell · `web/sw.js`
- [Realtime client](https://github.com/weedpump/nia-todo/blob/main/web/static/js/features/websocket-client.js): WebSocket consumer · `web/static/js/features/websocket-client.js`

### Native Clients

- [Native bridge](https://github.com/weedpump/nia-todo/blob/main/web/static/js/features/native-bridge.js): web-to-native bridge · Invokes notifications, reminders, downloads, and identity handoffs. · `web/static/js/features/native-bridge.js`
- [Tauri desktop and Android shell](https://github.com/weedpump/nia-todo/blob/main/src-tauri/src/main.rs): native runtime · Packages the shared web UI for Windows, Debian, and Android. · `src-tauri/src/main.rs`
- [Native capabilities](https://github.com/weedpump/nia-todo/blob/main/src-tauri/capabilities/default.json): bridge permissions · Declares allowed Tauri operations. · `src-tauri/capabilities/default.json`
- **Android receivers and callbacks**: Android integration · Handles Android platform events and OIDC callbacks.

### Persistence & Operations

- [SQLite data store](https://github.com/weedpump/nia-todo/blob/main/api/db.py): transactional persistence · Authoritative store for application data and runtime files. · `api/db.py`
- [SQL migrations](https://github.com/weedpump/nia-todo/blob/main/api/migrate.py): schema lifecycle · Ordered schema migrations applied at startup or administration. · `api/migrate.py`
- [Container and systemd deployment](https://github.com/weedpump/nia-todo/blob/main/Dockerfile): server operation · Runs the API with mounted persistent runtime data. · `Dockerfile`
- [Backup and restore](https://github.com/weedpump/nia-todo/blob/main/scripts/backup.sh): operations scripts · Scheduled backup plus restore and controlled update workflows. · `scripts/backup.sh`

## Connections

- Container and systemd deployment → FastAPI application: runs
- Backup and restore → SQLite data store: backs up and restores
- SQL migrations → SQLite data store: evolves schema
- FastAPI application → Security and CORS: applies
- FastAPI application → Todo and project routers: mounts
- FastAPI application → WebSocket updates: mounts
- Todo and project routers → Auth and identity: authenticates through
- Todo and project routers → Sharing access control: enforces sharing through
- Todo and project routers → Attachment service: handles files through
- Todo and project routers → SQLite data store: reads and writes
- Auth and identity → SQLite data store: stores identity data
- Sharing access control → SQLite data store: checks access data
- Attachment service → SQLite data store: stores metadata and files
- External integrations → Auth and identity: supports OIDC configuration
- Web application → Todo and project routers: calls HTTP API
- Web application → Offline mutation queue: queues offline changes
- Sync controller → Offline mutation queue: replays
- Web application → Sync controller: coordinates sync
- PWA service worker → Web application: caches app shell
- Realtime client → WebSocket updates: receives changes from
- Web application → Realtime client: uses
- Web application → Native bridge: invokes when native
- Native bridge → Tauri desktop and Android shell: calls
- Tauri desktop and Android shell → Native capabilities: is constrained by
- Tauri desktop and Android shell → Android receivers and callbacks: integrates Android handlers