docs/explanation/decisions.md

Architecture Decisions (ADR-style)

ADR-001: Use modular FastAPI layout for classifier backend

• Status: Accepted
• Type: Explicit
• Evidence:
  • app/main.py
  • app/api/router.py
  • app/routers/
  • app/services/
  • app/pipelines/
• Rationale:
  • Clear separation between transport, orchestration, and integrations.

ADR-002: Preserve endpoint contracts from prior service behavior

• Status: Accepted
• Type: Explicit
• Evidence:
  • app/routers/classification.py
  • tests/test_routes.py
• Rationale:
  • Keep clients functional while refactoring internals.

ADR-003: Use local Hugging Face zero-shot NLI model for classification

• Status: Accepted
• Type: Explicit
• Evidence:
  • app/core/config.py
  • app/services/classifier_service.py
• Rationale:
  • Perform true runtime-label zero-shot classification with local inference control.

ADR-004: Use local langdetect library for language detection

• Status: Accepted
• Type: Explicit
• Evidence:
  • app/services/language_service.py
• Rationale:
  • Remove external dependency and keep language inference local.

ADR-005: Keep labels in in-memory mutable config

• Status: Accepted (current), Needs review
• Type: Explicit
• Evidence:
  • app/models/label_config.py
  • app/services/label_service.py
  • app/routers/classification.py (/configlabel, /labels)
• Rationale:
  • Simple runtime tuning without DB migration.
• Tradeoff:
  • No persistence across restarts, no cross-instance consistency.

ADR-006: Store uploaded files on local filesystem under static mount

• Status: Accepted
• Type: Explicit
• Evidence:
  • app/services/file_storage_service.py
  • app/main.py
  • docker-compose.yml
• Rationale:
  • Enables document/image extraction workflow with minimal infrastructure.

ADR-007: Map errors into contract-friendly HTTP statuses

• Status: Accepted
• Type: Explicit
• Evidence:
  • app/routers/classification.py
  • app/core/exceptions.py
• Rationale:
  • Differentiate local validation issues (400) from inference failures (502).

ADR-008: No built-in auth layer for this API

• Status: Accepted (current), Needs review
• Type: Inferred
• Evidence:
  • app/routers/classification.py
  • absence of auth dependencies/middleware in app/main.py
• Rationale:
  • likely positioned as internal or early-stage service.