curo1305
3248607790
Backend polls each registered service's /health endpoint every 30 s via a background asyncio task. GET /api/services exposes the live status snapshot. The Apps page now renders from this endpoint — showing "Unavailable" (dimmed, non-clickable) when a service is registered but its container is unreachable. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
130 lines
5.3 KiB
Markdown
130 lines
5.3 KiB
Markdown
# 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 |
|
|
|
|
### 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) |
|
|
|
|
### 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 — API keys redacted) |
|
|
| `PATCH` | `/api/settings/ai` | Update AI provider / credentials |
|
|
| `POST` | `/api/settings/ai/test` | Test AI connection (proxies a minimal /chat call) |
|
|
| `GET` | `/api/settings/documents/limits` | Doc service upload limits |
|
|
| `PATCH` | `/api/settings/documents/limits` | Update max PDF size |
|
|
|
|
Settings are persisted to JSON files on the `app_config` Docker named volume and read by the respective feature services.
|
|
|
|
### 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
|
|
|
|
### Database models
|
|
|
|
| Model | Table | Notes |
|
|
|-------|-------|-------|
|
|
| `User` | `users` | email, hashed_password, role (`user`\|`admin`), is_active |
|
|
| `Profile` | `profiles` | one-to-one with User; full_name, phone, etc. |
|
|
|
|
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 volume) └── proxy → health-check loop
|
|
/profile doc-service:8001 (30s poll)
|
|
```
|
|
|
|
---
|
|
|
|
## 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** — no group model yet; blocks document sharing in doc-service
|
|
- **Email verification** — accounts are active immediately after registration
|
|
- **Password reset** — no flow implemented
|
|
|
|
---
|
|
|
|
## Future work
|
|
|
|
- [ ] Groups + permissions system: `groups`, `group_memberships`, `group_app_permissions` tables; admin CRUD; 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
|