Skip to main content

​
Storage Overview

StorePathPurpose
SQLite app DBdata/samaritan.dbconversations, messages, feedback, projects, usage
SQLite FTSdata/samaritan_fts.dblexical search index
Chromadata/chroma/vectors + chunk metadata
Connections cachedata/samaritan_connections.dbrelated-source cache
Eval filesdata/eval/results/*.jsoneval run outputs

​
Core SQL Tables (samaritan.db)

  • conversations
  • messages
  • feedback
  • conversation_state
  • projects
  • project_sources
  • llm_usage
Key constraints include:
  • role checks (user/assistant)
  • feedback rating checks (-1/1)
  • foreign-key cascades for conversation-scoped cleanup
  • indexed paths for recent conversation and feedback analytics reads

​
FTS Table (samaritan_fts.db)

chunks_fts virtual table contains:
  • content (indexed full text)
  • chunk_id (unindexed reference)
  • video_id (unindexed filter)
  • source_id (unindexed filter)
  • namespace (unindexed filter)

​
Chroma Metadata Families

  • YouTube chunk metadata
  • Article chunk metadata
  • File chunk metadata
Typed metadata contracts are enforced before write.

​
Endpoint Domain Map

  • /api/chat*, /api/conversations*, /api/feedback*
  • /api/library*, /api/ingest*
  • /api/career*, /api/projects*, /api/user-skills*
  • /api/evals*, /api/stats*
Use http://localhost:8000/docs for full request/response schema details.