FarmaFinder/STATE.md

Pharmacy Integration Platform (PIP) — State Log

Goal

Build a Python/FastAPI backend that abstracts pharmacy ERPs behind a unified REST API. Currently implementing Phase 3 (Inventory & Medication APIs).

Constraints & Preferences

• Backend only, no UI/mobile. Python 3.13, FastAPI, SQLAlchemy async, Alembic, PostgreSQL, Redis, RabbitMQ.
• Clean Architecture, SOLID, Repository Pattern, DI, DDD where valuable, Event Driven, CQRS where needed.
• Versioned API at /api/v1/. JWT+OAuth2 auth. RBAC with role hierarchy and scopes. API Keys for third parties.
• No code secrets. Structured JSON logs. OpenTelemetry, Prometheus, Grafana.
• Docker Compose with health checks; Kubernetes-migratable.
• Monitoring (Prometheus, Grafana, OTEL Collector) omitted from Docker stack; remote monitoring stack exists. PLAN.md provided for external integration.
• Incremental phases — wait for validation before advancing.

Progress

Done

• Phase 1 complete: full project structure, domain entities, ORM models, repositories, auth, security, API endpoints, middleware, Docker, CLI, Alembic, tests scaffolding
• Phase 2 complete: Connector Framework + SDK + Concrete Connectors + API Endpoints + Event Publishers + Tests
• Phase 3 (medication/inventory): Medication & Inventory API endpoints — all E2E validated:
  • Medications: CRUD, search by name/ingredient/nregistro/atc, nregistro lookup, duplicate 409
  • Catalog: per-pharmacy upsert, list, get
  • Inventory: per-pharmacy upsert with history tracking, list, get, history endpoint
  • Reservations: create, idempotency key, list, get, confirm, cancel, insufficient stock 422

In Progress

• Phase 3 remaining items: Sync Job management, Audit logging integration, API Key auth flow, Rate limiting

Blocked

• (none)

Key Decisions

• Monitoring removed from Docker stack; PLAN.md provides instructions for external Prometheus/Grafana integration
• docker-compose.runtime.yml is the lean compose file for local dev
• Connector Registry uses singleton pattern with lazy loading via importlib for builtin connector types
• SDK architecture: SDKConnector base class composes auth handler + retry policy + circuit breaker + httpx client; concrete connectors extend it
• _BUILTIN_CONNECTORS registry maps ERPType values to module.Class strings for dynamic import
• Circuit breaker: 5 failures → open → 30s recovery → half_open (1 probe call) → close on success / reopen on failure
• OAuth2 handler fetches client_credentials tokens with 30s expiry buffer
• Replaced passlib with direct bcrypt library due to Python 3.13 incompatibility
• Connector events published to RabbitMQ with connector.{event} routing keys via ConnectorService._publish_event()
• test_connection sets connector status to ACTIVE on success, ERROR on failure; deploy refuses if already active
• Catalog entries are per-pharmacy, keyed by (pharmacy_id, medication_id) — upsert pattern
• Inventory records use same composite key pattern as catalog — upsert with history tracking
• Reservations support idempotency via idempotency_key, auto-expire, stock reservation/release on confirm/cancel
• Event publishing uses event_type.replace(".", "_") to map dotted event types to RabbitMQ routing keys
• Auth token endpoint expects JSON body (LoginRequest), not OAuth2 form data
• InventoryHistoryEntity has inventory_record_id field — must be set from service when creating history records
• Reservation expires_at uses timedelta (not timestamp arithmetic — float type error with Python 3.13 datetime)

Critical Bugs Fixed (this session)

1. inventory_repository.py:add_history() was using entity.id (None) instead of entity.inventory_record_id for the FK
2. inventory_service.py:upsert_inventory_record() wasn't passing inventory_record_id=upserted.id to InventoryHistoryEntity
3. inventory_service.py:_release_reserved_stock() wasn't passing inventory_record_id either
4. inventory_service.py:create_reservation() used now.__class__(now.timestamp() + ttl_minutes * 60, tz=timezone.utc) which fails with TypeError on float — replaced with now + timedelta(minutes=ttl_minutes)

Next Steps

• Implement Sync Job management (create, list, get, trigger, cancel sync jobs)
• Add Audit logging integration
• Implement API Key auth flow
• Add Rate limiting
• Replace Base.metadata.create_all with Alembic migrations
• Add more connector implementations (NixFara, Unycop, CSV, FTP, SQL)
• Enhance test coverage
• Set up CI/CD pipeline

Critical Context

• bcrypt library used directly (not via passlib) — must keep bcrypt>=4.2.0 in dependencies

• OTel collector reference in docker-compose points to otel-collector:4317 which doesn't exist in runtime stack — harmless warning logs

• System router has /system prefix; health at /api/v1/system/health

• Auth: register at /api/v1/auth/register, token at /api/v1/auth/token (JSON body, not form data)

• Generic exception handler in main.py swallows all errors as {"error": {"code": "INTERNAL_ERROR", "message": "Internal server error"}} — no traceback in response; check container logs or test repo/service directly for debugging

• Inventory endpoint uses PUT /pharmacies/{pharmacy_id}/inventory for upsert

• Reservation endpoints: POST .../reservations (create), POST .../reservations/{id}/confirm, POST .../reservations/{id}/cancel## Recent changes (OTel migration in progress)

• Observability now lives on srv84-macos. The in-stack otel-collector / prometheus / grafana services have been stripped from pip-platform/docker-compose.yml, the orphaned pip-platform/monitoring/otel-collector-config.yaml has been deleted, and pip-platform/docker-compose.runtime.yml was previously pointing at a non-existent otel-collector:4317 — fixed to host.docker.localhost:4317 to route through Grafana Alloy. See PLAN.md for the external-integration rationale.

• pip-platform/monitoring/prometheus/prometheus.yml is now documentation-only — kept as a reference; the active scraper is the Prometheus on srv84-macos.

• Monitoring stack (~/Projects/Monitoring/): Telegram bot token was externalized from alertmanager/config.yml (was plaintext literal) to ${TG_BOT_TOKEN} resolved by an envsubst entrypoint on the remote. OTel→Alloy swap is local-canonical; srv84-macos merge still pending (see PLAN.md).

Relevant Files

Domain

• pip-platform/src/domain/entities/entities.py — All domain entities (including inventory_record_id on InventoryHistoryEntity)
• pip-platform/src/domain/entities/enums.py — All enums

Repositories

• pip-platform/src/infrastructure/database/repositories/medication_repository.py — Medication CRUD + search
• pip-platform/src/infrastructure/database/repositories/medication_catalog_repository.py — Per-pharmacy catalog upsert
• pip-platform/src/infrastructure/database/repositories/inventory_repository.py — Inventory upsert + history
• pip-platform/src/infrastructure/database/repositories/reservation_repository.py — Reservation CRUD + idempotency
• pip-platform/src/infrastructure/database/repositories/__init__.py — All repo exports

Services

• pip-platform/src/services/medication/medication_service.py — Medication + catalog business logic + events
• pip-platform/src/services/inventory/inventory_service.py — Inventory + reservation business logic (stock reservation/release, confirm, cancel, idempotency) + events
• pip-platform/src/services/connector_service.py — Connector lifecycle + event publishing

API Endpoints

• pip-platform/src/api/v1/endpoints/medications.py — Medication CRUD + search
• pip-platform/src/api/v1/endpoints/catalog.py — Per-pharmacy catalog list/get/upsert
• pip-platform/src/api/v1/endpoints/inventory.py — Per-pharmacy inventory list/get/upsert + history
• pip-platform/src/api/v1/endpoints/reservations.py — Per-pharmacy reservation create/confirm/cancel/list/get
• pip-platform/src/api/v1/endpoints/connectors.py — Connector CRUD + test/deploy/deactivate/configs
• pip-platform/src/api/v1/endpoints/erp_systems.py — ERP System CRUD
• pip-platform/src/api/v1/router.py — All routers wired

Infrastructure

• pip-platform/src/infrastructure/messaging/rabbitmq.py — RabbitMQ client with routing keys
• pip-platform/src/connectors/registry.py — ConnectorRegistry singleton
• pip-platform/src/connectors/sdk/base_sdk.py — SDKConnector base class
• pip-platform/src/services/auth/security.py — Fixed bcrypt usage (no passlib)

Docker

• pip-platform/docker-compose.runtime.yml — Lean runtime stack