How weedpump/nia-todo works
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: main.js Web application · todos.py Todo and project routers · db.py SQLite data store · main.py FastAPI application
Components 21
Backend API
- FastAPI application · Composes API routers and realtime endpoints.
api/main.py - Todo and project routers
api/routers/todos.py - WebSocket updates
api/routers/websocket.py - Security and CORS
api/middleware/security.py - Auth and identity · Sessions, API keys, MFA, passkeys, and OIDC flows.
api/services/auth.py - Sharing access control
api/services/sharing.py - Attachment service
api/services/attachments.py - External integrations · Email, push, OIDC configuration, and BrainDump endpoints.
api/services/email.py
Web / PWA
- Web application · Browser UI, state, rendering, and API feature modules.
web/static/js/main.js - Offline mutation queue · Persists and replays browser mutations.
web/static/js/sync/queue.js - Sync controller
web/static/js/features/sync-controller.js - PWA service worker
web/sw.js - Realtime client
web/static/js/features/websocket-client.js
Native Clients
- Native bridge · Invokes notifications, reminders, downloads, and identity handoffs.
web/static/js/features/native-bridge.js - Tauri desktop and Android shell · Packages the shared web UI for Windows, Debian, and Android.
src-tauri/src/main.rs - Native capabilities · Declares allowed Tauri operations.
src-tauri/capabilities/default.json - Android receivers and callbacks · Handles Android platform events and OIDC callbacks.
Persistence & Operations
- SQLite data store · Authoritative store for application data and runtime files.
api/db.py - SQL migrations · Ordered schema migrations applied at startup or administration.
api/migrate.py - Container and systemd deployment · Runs the API with mounted persistent runtime data.
Dockerfile - Backup and restore · Scheduled backup plus restore and controlled update workflows.
scripts/backup.sh
Connections 25
- 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