# 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