Business-Management/backend/STATUS.md

Backend — Status

What it is

Central FastAPI gateway. Handles authentication, user management, admin settings, and proxies feature-service traffic. It is the only container that has host-level port exposure (8000, internal) — all browser traffic arrives via the Vite/nginx frontend proxy.

Port: 8000 (on backend-net, no direct host binding in prod). Database: PostgreSQL 16 (postgres_data named volume).

---

Current functionality

Auth (/api/auth)

Method	Path	Description
POST	/api/auth/register	Create account; password policy enforced (uppercase, special char, no "test")
POST	/api/auth/login	OAuth2 password flow; returns RS256 JWT (8-hour expiry)

JWT signing uses a 4096-bit RSA key pair (RS256). Keys are generated by scripts/generate_jwt_keys.py and stored in backend/.env (gitignored). Token stored in localStorage on the client.

Users (/api/users)

Method	Path	Description
GET	/api/users/me	Current user info
GET	/api/users/me/preferences	User's dashboard preferences (app_ids list)
PATCH	/api/users/me/preferences	Update pinned app IDs (max 50; validated as safe slugs)
GET	/api/users/me/groups	List groups the current user belongs to (for share picker)

Profile (/api/profile)

Method	Path	Description
GET	/api/profile	Fetch profile (separate profiles table)
PUT	/api/profile	Update profile fields

Admin (/api/admin)

Method	Path	Description
GET	/api/admin/users	List all users (admin only)
PATCH	/api/admin/users/{id}	Update user (role, active flag)

Groups (/api/admin/groups)

Method	Path	Description
GET	/api/admin/groups	List all groups with member count
POST	/api/admin/groups	Create a new group
GET	/api/admin/groups/{id}	Get group detail with member list
PATCH	/api/admin/groups/{id}	Update group name / description
DELETE	/api/admin/groups/{id}	Delete group (cascades memberships)
POST	/api/admin/groups/{id}/members/{user_id}	Add user to group
DELETE	/api/admin/groups/{id}/members/{user_id}	Remove user from group

Services (/api/services)

Method	Path	Description
GET	/api/services	Returns health status of all registered feature services

A background task (service_health.py) polls each service's /health endpoint every 30 s and stores the result in memory. The first check runs immediately on startup. Any authenticated user may call GET /api/services; the frontend uses it to drive app card visibility.

Settings (/api/settings)

Method	Path	Description
GET	/api/settings/ai	AI service config (masked) — superuser OR ai-service-admin member
PATCH	/api/settings/ai	Update AI provider / credentials — same access
POST	/api/settings/ai/test	Test AI connection — same access
GET	/api/settings/documents/limits	Doc service upload limits — superuser OR doc-service-admin member
PATCH	/api/settings/documents/limits	Update max PDF size — same access
GET	/api/settings/system-prompts	All editable system prompts — superuser OR ai-service-admin member
PATCH	/api/settings/system-prompts/{id}	Update system prompt — same access

Settings are persisted to the config bucket of storage-service:8020 via core/config_storage.py. All config I/O is async HTTP; no filesystem volumes are used.

Access to service-specific settings endpoints is enforced by get_service_admin(service_id) in deps.py — grants access to superusers OR members of the {service_id}-admin group.

Storage config (/api/admin)

Method	Path	Description
GET	/api/admin/storage-config	Current backend driver + health (proxied from storage-service)
PATCH	/api/admin/storage-config	Reconfigure backend without migration
POST	/api/admin/storage-config/migrate	Start async migration to a new backend
GET	/api/admin/storage-config/migrate/status	Poll migration progress
DELETE	/api/admin/storage-config/migrate	Cancel running migration

Feature proxies

All /api/documents/* and /api/documents/categories/* requests are transparently proxied to doc-service:8001 via httpx.AsyncClient. The proxy:

• Validates the JWT (get_current_user)
• Injects x-user-id header (UUID from users.id)
• Strips hop-by-hop headers + content-length, accept-encoding, content-type
• Returns Response (not StreamingResponse) to avoid content-length/chunked conflicts

Plugin system (/api/plugins)

Generic extension/plugin infrastructure — zero feature-specific code in backend. Feature containers self-describe via GET /plugin/manifest.

Method	Path	Auth	Description
GET	/api/plugins	user	List plugins accessible to current user
GET	/api/plugins/{id}/manifest	user	Cached manifest for a plugin (404 if not accessible)
GET	/api/plugins/{id}/settings	user	Proxy to feature GET /plugin/settings
PATCH	/api/plugins/{id}/settings	user	Proxy to feature PATCH /plugin/settings

Access is controlled by the manifest: allow_superuser for admins; required_groups for group members. check_plugin_access(plugin_id, user, db) in deps.py enforces this.

During each health poll, service_health.py also fetches GET /plugin/manifest from healthy services and caches it. New feature containers that expose /plugin/manifest automatically appear in the plugin list — no backend code changes required.

Service admin group bootstrap: On every startup, group_bootstrap.py creates a {service-id}-admin group for every registered service (idempotent). Admins add users to these groups via the Admin → Groups UI to delegate service-level administration.

Database models

Model	Table	Notes
User	users	email, hashed_password, role (user|admin), is_active, dashboard_app_ids (JSON)
Profile	profiles	one-to-one with User; full_name, phone, etc.
Group	groups	name (unique), description, created_at
GroupMembership	group_memberships	group_id + user_id (unique pair); joined_at

Alembic migrations in backend/alembic/versions/ — version table: alembic_version.

---

Architecture

Browser (port 5173 dev / 80 prod)
    │
    └── Vite dev proxy / nginx
            │
            └── /api/*  →  backend:8000  (FastAPI)
                                │
                    ┌───────────┼────────────┬──────────────┐
                 /auth       /settings    /documents/*   /services
                 /users       (JSON        │              │
                 /admin       /storage-    └── proxy →   health-check loop
                 /profile      config       doc-service:8001  (30s poll)
                             (proxy)
                                  │
                             storage-service:8020

---

Security notes

• JWT stored in localStorage — XSS risk. Migration to httpOnly cookie planned.
• No refresh token — after 8h the user must log in again.
• Admin routes use get_current_admin dependency (checks role == "admin").
• All backend routes require authentication except /api/auth/*.
• backend-net is marked internal: true — containers on it cannot reach the internet directly.

---

Known limitations / not implemented

• No refresh tokens — 8h hard expiry; adding refresh requires httpOnly cookie + rotation
• No httpOnly cookie — JWT in localStorage is XSS-exposed
• App permissions — no per-user, per-app access control. Currently all authenticated users can use all apps. Planned: user_app_permissions table, admin UI to grant/revoke
• Groups / sharing — groups + memberships exist; app permission hooks not yet wired up
• Email verification — accounts are active immediately after registration
• Password reset — no flow implemented

---

Future work

• Groups system: groups, group_memberships tables; admin CRUD; add/remove members
• Generic plugin infrastructure: manifest contract, /api/plugins proxy router, check_plugin_access
• App permissions registry: group_app_permissions table; AppsPage filtered by group grants
• Doc sharing via group membership
• App permissions registry: user_app_permissions (user_id, app_key); AppsPage filtered by grants
• httpOnly cookie migration for JWT
• Refresh token flow (paired with cookie migration)
• Email verification on registration
• Password reset flow
• Rate limiting on auth endpoints