Restructure with Turborepo

2026-07-06 15:51:53 +02:00
parent f66cafbbc3
commit 190b3d163d
277 changed files with 53253 additions and 0 deletions
@@ -0,0 +1,65 @@
+# PIP Platform — State Tracker
+
+## Current Phase: 3 (Complete)
+
+### Phase 1 — Foundation ✅
+- FastAPI app skeleton, Settings, Docker Compose (Postgres, Redis, RabbitMQ)
+- SQLAlchemy async models + Alembic migration `001_initial`
+- Auth: JWT (access/refresh), RBAC (admin/operator/viewer), user CRUD
+- Entities: Pharmacy, Connector, Medication, Inventory, Reservation, ERP System
+- Repositories + Services for all entities
+- API v1 endpoints for all entities
+- Middleware: CORS, request logging, metrics
+- Observability: OpenTelemetry traces, Prometheus metrics
+
+### Phase 2 — Connector SDK ✅
+- Abstract connector interface + Mock connector implementation
+- Connector registry, version management, config CRUD
+- Medicationcatalog + inventory sync plumbing
+
+### Phase 3 — Sync, Audit, API Keys, Rate Limiting ✅
+- **Sync Jobs**: Repository, service, API endpoints (create, list, get, trigger, complete, fail, cancel, logs, status filter)
+- **Audit Logging**: AuditService (`log_action`, `list_logs`), AuditMiddleware (auto-logs POST/PUT/PATCH/DELETE), audit endpoint
+- **API Key Auth**: Dual auth via `get_authenticated_user` — supports both Bearer JWT and X-API-Key header; `require_role` and `require_scope` use it; API Key CRUD endpoints
+- **Rate Limiting**: Custom `RateLimitMiddleware` (sliding window, X-RateLimit-* headers, 429 with Retry-After); exempt paths (docs, metrics, health)
+- **RabbitMQ**: Routing keys for `sync_created`, `sync_triggered`, `sync_completed`, `sync_failed`, `sync_cancelled`
+
+## Architecture Decisions
+- Clean Architecture: domain entities → services → API endpoints → infrastructure
+- Repository pattern with SQLAlchemy async
+- Dual auth: JWT Bearer + X-API-Key in single `get_current_user` dependency
+- Audit middleware uses separate DB session (via `async_session_factory`) to decouple from request session
+- Rate limiting: custom middleware replacing slowapi (incompatible with FastAPI 0.138+ `_IncludedRouter`)
+- DB migrations: Alembic `upgrade head` runs in app lifespan (not `create_all`)
+- `APIKeyEntity.key_hash` is `bytes` (sha256 digest), ORM model uses `LargeBinary(64)`
+
+## Key Files
+| File | Purpose |
+|------|---------|
+| `src/main.py` | App factory, lifespan (alembic upgrade), middleware chain |
+| `src/api/v1/dependencies/auth.py` | Dual auth: JWT + API Key, require_role, require_scope |
+| `src/api/middleware/audit.py` | Auto-audit for write endpoints |
+| `src/api/middleware/rate_limit.py` | Custom sliding window rate limiter |
+| `src/api/v1/endpoints/sync_jobs.py` | Sync job CRUD + lifecycle |
+| `src/api/v1/endpoints/api_clients.py` | API client + key management |
+| `src/api/v1/endpoints/audit.py` | Audit log query endpoint |
+| `src/services/synchronization/sync_service.py` | Sync job business logic |
+| `src/services/audit/audit_service.py` | Audit service |
+| `src/infrastructure/messaging/rabbitmq.py` | Event publishing routing keys |
+| `alembic/versions/001_initial.py` | Full schema (all tables including sync_jobs, sync_logs, audit_logs) |
+
+## Configuration (env)
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `RATE_LIMIT_PER_MINUTE` | 60 | Max requests per client per minute |
+| `RATE_LIMIT_AUTH_PER_MINUTE` | 10 | (reserved) Auth endpoint limit |
+| `JWT_SECRET_KEY` | change-me-in-production | Must be set in production |
+| `API_KEY_PREFIX` | pip | (reserved) Key namespace prefix |
+
+## Next Phase Ideas
+- Redis-backed rate limiter (for multi-instance)
+- Per-client rate limits (use `api_clients.rate_limit` column)
+- API Key scope enforcement on specific endpoints (currently role-only)
+- Sync job execution worker (consume RabbitMQ events, run connector)
+- IP allowlist enforcement for API clients
+- Alembic migration 002 for any schema changes