Instruction file imported from DarshanPatel24/enterprise-knowledge-hub (.github/instructions/backend.instructions.md). Copyright stays with the author.

Backend Engineering Instructions (FastAPI + Python)

Layering and Boundaries

1. Respect Clean Architecture layers:
   • domain: pure entities and value objects, no framework imports.
   • data: SQL and vector access primitives (connection, models, clients).
   • repositories: persistence operations using the data layer only.
   • services: business orchestration; depend on repositories and other services.
   • api: thin HTTP layer; validate input, call services, return schemas.
   • jobs: scheduled/background orchestration; reuse services.
2. API route handlers must not contain business logic.
3. Services must not run raw SQL or talk to Qdrant directly except via data/repository abstractions.

Dependency Injection

1. Compose dependencies through FastAPI Depends and a central provider module.
2. Inject repositories and services; do not instantiate them inline in routes.
3. Make external clients (SQL, Qdrant, Ollama, embeddings) swappable behind interfaces.

Typing and Models

1. All public functions/methods require complete type hints.
2. Use Pydantic models for:
   • request and response payloads
   • configuration/settings
   • cross-service data contracts
3. Keep domain entities separate from API schemas.

Error Handling

1. Define explicit exception types for domain, security, and infrastructure errors.
2. Map exceptions to consistent HTTP responses in middleware.
3. Never swallow exceptions silently; log with context and correlation ID.

Logging and Observability

1. Use structured logging (key/value), not f-string log spam.
2. Attach correlation IDs to each request and propagate through services.
3. Emit timing/metrics for ingestion, retrieval, and generation paths.
4. Never log secrets or full document/chunk contents.

Data Access Rules

1. SQL Server is the source of truth; Qdrant stores vectors and retrieval metadata.
2. Use parameterized queries exclusively.
3. Keep stable document_id and chunk_id identifiers across SQL and Qdrant.
4. All writes that affect both stores must be idempotent and reconcilable.

Retrieval and Security Rules

1. Chat path is anonymous; do not require a principal for query execution.
2. Classification is ingestion-time metadata in the current model, not a per-user query-time gate.
3. Hybrid pipeline order: dense + BM25, RRF fusion, rerank (optional), context build.
4. Generation must be grounded and include citations; return the exact fallback sentence when no evidence exists.

Performance and Reliability

1. Use async I/O for network/database operations where supported.
2. Apply retry with backoff for transient failures.
3. Guard external runtimes (Ollama) with timeouts and graceful degradation.

Testing

1. Provide unit tests for services and repositories (mock external systems).
2. Provide integration tests for ingestion, retrieval, and generation flows.
3. Provide security tests for authorization boundaries.