Skip to main content

​
Lifecycle Layers

Every request flows through:
  1. ASGI server receives request
  2. middleware (rate limiting, timing, CORS)
  3. FastAPI route validation + dispatch
  4. service orchestration
  5. persistence side effects
  6. response return (JSON, SSE, or WS)

​
Startup Lifecycle

On app boot:
  • config load
  • DB/index initialization
  • optional FTS backfill from Chroma when needed
  • optional observability integration bootstrap

​
Ingestion Lifecycle

​
Job-backed paths

  • POST /api/ingest
  • POST /api/ingest/upload
Flow:
  1. create queued job record
  2. run background processing
  3. update progress/state (queued -> processing -> completed|failed)
  4. expose status via GET /api/ingest/{job_id} and WS /api/ingest/ws/{job_id}

​
Direct path

  • POST /api/ingest/url
Directly executes ingest logic and returns payload status (ok / error) without job polling semantics.

​
Chat Lifecycle (/api/chat and /api/chat/stream)

Key contracts:
  • conversation creation is implicit in chat flow
  • provenance fields are returned in response payloads
  • streaming path ends with one terminal event (done or error)

​
Persistence Touchpoints

Chat path writes:
  • conversations/messages
  • feedback-linked metadata fields
Ingestion path writes:
  • Chroma vectors + metadata
  • FTS index rows
  • learnings artifacts
  • cache invalidation side effects