# dicklesworthstone/coding_agent_session_search architecture

> Architecture diagram of the GitHub repository dicklesworthstone/coding_agent_session_search, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/dicklesworthstone/coding_agent_session_search
- Repository: https://github.com/dicklesworthstone/coding_agent_session_search

## Overview

cass is a local-first TUI and machine interface for aggregating coding-agent histories into a searchable archive. The main workflow is discovering configured sources, parsing provider-specific sessions, persisting canonical conversations, building derived lexical and optional semantic indexes, then searching and viewing results. Supporting branches provide analytics, export/archive operations, and readiness/repair diagnostics. The README documents these capabilities and the SQLite source-of-truth contract; sampled source excerpts are incomplete, so the graph omits uncertain internal call wiring.

Main entry points: [`src/storage/sqlite.rs`](https://github.com/dicklesworthstone/coding_agent_session_search/blob/main/src/storage/sqlite.rs) (Canonical archive), [`src/main.rs`](https://github.com/dicklesworthstone/coding_agent_session_search/blob/main/src/main.rs) (CLI entry point), [`src/indexer/semantic/engine.rs`](https://github.com/dicklesworthstone/coding_agent_session_search/blob/main/src/indexer/semantic/engine.rs) (Semantic indexing), [`src/search/query.rs`](https://github.com/dicklesworthstone/coding_agent_session_search/blob/main/src/search/query.rs) (Query and retrieval)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["History ingestion"]
  node_source_setup["Source discovery<br/>[mod.rs]"]
  node_connectors["Agent connectors<br/>[mod.rs]"]
  node_conversation_model["Conversation model<br/>[mod.rs]"]
end

subgraph group_index["Archive and indexes"]
  node_indexer["Indexer<br/>[mod.rs]"]
  node_semantic_engine["Semantic indexing<br/>[engine.rs]"]
  node_archive_db[("Canonical archive<br/>[sqlite.rs]")]
end

subgraph group_retrieval["Search and interfaces"]
  node_cli["CLI entry point<br/>[main.rs]"]
  node_lexical_search["Lexical search<br/>[tantivy.rs]"]
  node_semantic_search["Semantic search<br/>[model_manager.rs]"]
  node_search_query["Query and retrieval<br/>[query.rs]"]
  node_search_service["Robot search service<br/>[search_service.rs]"]
  node_tui["Interactive TUI<br/>[tui.rs]"]
end

subgraph group_support["Operations and outputs"]
  node_analytics["Usage analytics<br/>[query.rs]"]
  node_export["Export and rendering<br/>[export.rs]"]
  node_logical_archive["Logical archives<br/>[mod.rs]"]
  node_doctor["Readiness diagnostics<br/>[doctor.rs]"]
end

node_user(("User or agent"))
node_history["Local histories"]
node_models["Local model files"]

node_user -->|"issues commands"| node_cli
node_history -->|"provides sources"| node_source_setup
node_cli -->|"configures sources"| node_source_setup
node_source_setup -->|"selects providers"| node_connectors
node_connectors -->|"parses sessions"| node_conversation_model
node_indexer -->|"writes conversations"| node_archive_db
node_indexer -->|"builds vectors"| node_semantic_engine
node_semantic_engine -->|"reads conversations"| node_archive_db
node_semantic_engine -.->|"loads local model"| node_models
node_archive_db -->|"rebuilds lexical index"| node_lexical_search
node_archive_db -->|"supplies filters"| node_semantic_search
node_user -->|"sends requests"| node_search_service
node_cli -->|"dispatches search"| node_search_query
node_search_query -->|"retrieves candidates"| node_lexical_search
node_search_query -.->|"refines results"| node_semantic_search
node_search_service -->|"searches index"| node_lexical_search
node_search_service -->|"loads follow-up"| node_archive_db
node_cli -->|"launches interface"| node_tui
node_tui -->|"reads archive"| node_archive_db
node_cli -->|"dispatches analytics"| node_analytics
node_analytics -->|"queries usage data"| node_archive_db
node_cli -->|"dispatches export"| node_export
node_export -->|"reads conversations"| node_archive_db
node_cli -->|"dispatches archive tasks"| node_logical_archive
node_cli -->|"dispatches diagnosis"| node_doctor
node_doctor -->|"checks readiness"| node_archive_db

click node_cli "https://github.com/dicklesworthstone/coding_agent_session_search/blob/main/src/main.rs"
click node_source_setup "https://github.com/dicklesworthstone/coding_agent_session_search/blob/main/src/sources/mod.rs"
click node_connectors "https://github.com/dicklesworthstone/coding_agent_session_search/blob/main/src/connectors/mod.rs"
click node_conversation_model "https://github.com/dicklesworthstone/coding_agent_session_search/blob/main/src/model/mod.rs"
click node_indexer "https://github.com/dicklesworthstone/coding_agent_session_search/blob/main/src/indexer/mod.rs"
click node_semantic_engine "https://github.com/dicklesworthstone/coding_agent_session_search/blob/main/src/indexer/semantic/engine.rs"
click node_archive_db "https://github.com/dicklesworthstone/coding_agent_session_search/blob/main/src/storage/sqlite.rs"
click node_lexical_search "https://github.com/dicklesworthstone/coding_agent_session_search/blob/main/src/search/tantivy.rs"
click node_semantic_search "https://github.com/dicklesworthstone/coding_agent_session_search/blob/main/src/search/model_manager.rs"
click node_search_query "https://github.com/dicklesworthstone/coding_agent_session_search/blob/main/src/search/query.rs"
click node_search_service "https://github.com/dicklesworthstone/coding_agent_session_search/blob/main/src/search_service.rs"
click node_tui "https://github.com/dicklesworthstone/coding_agent_session_search/blob/main/src/ui/tui.rs"
click node_analytics "https://github.com/dicklesworthstone/coding_agent_session_search/blob/main/src/analytics/query.rs"
click node_export "https://github.com/dicklesworthstone/coding_agent_session_search/blob/main/src/export.rs"
click node_logical_archive "https://github.com/dicklesworthstone/coding_agent_session_search/blob/main/src/logical_archive/mod.rs"
click node_doctor "https://github.com/dicklesworthstone/coding_agent_session_search/blob/main/src/doctor.rs"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_source_setup,node_connectors,node_conversation_model,node_user toneBlue
class node_indexer,node_semantic_engine,node_archive_db toneAmber
class node_cli,node_lexical_search,node_semantic_search,node_search_query,node_search_service,node_tui toneMint
class node_analytics,node_export,node_logical_archive,node_doctor toneRose
class node_history,node_models toneIndigo
```

## Components

### History ingestion

- [Source discovery](https://github.com/dicklesworthstone/coding_agent_session_search/blob/main/src/sources/mod.rs): `src/sources/mod.rs`
- [Agent connectors](https://github.com/dicklesworthstone/coding_agent_session_search/blob/main/src/connectors/mod.rs): `src/connectors/mod.rs`
- [Conversation model](https://github.com/dicklesworthstone/coding_agent_session_search/blob/main/src/model/mod.rs): `src/model/mod.rs`

### Archive and indexes

- [Indexer](https://github.com/dicklesworthstone/coding_agent_session_search/blob/main/src/indexer/mod.rs): `src/indexer/mod.rs`
- [Semantic indexing](https://github.com/dicklesworthstone/coding_agent_session_search/blob/main/src/indexer/semantic/engine.rs): `src/indexer/semantic/engine.rs`
- [Canonical archive](https://github.com/dicklesworthstone/coding_agent_session_search/blob/main/src/storage/sqlite.rs): `src/storage/sqlite.rs`

### Search and interfaces

- [CLI entry point](https://github.com/dicklesworthstone/coding_agent_session_search/blob/main/src/main.rs): `src/main.rs`
- [Lexical search](https://github.com/dicklesworthstone/coding_agent_session_search/blob/main/src/search/tantivy.rs): `src/search/tantivy.rs`
- [Semantic search](https://github.com/dicklesworthstone/coding_agent_session_search/blob/main/src/search/model_manager.rs): `src/search/model_manager.rs`
- [Query and retrieval](https://github.com/dicklesworthstone/coding_agent_session_search/blob/main/src/search/query.rs): `src/search/query.rs`
- [Robot search service](https://github.com/dicklesworthstone/coding_agent_session_search/blob/main/src/search_service.rs): `src/search_service.rs`
- [Interactive TUI](https://github.com/dicklesworthstone/coding_agent_session_search/blob/main/src/ui/tui.rs): `src/ui/tui.rs`

### Operations and outputs

- [Usage analytics](https://github.com/dicklesworthstone/coding_agent_session_search/blob/main/src/analytics/query.rs): `src/analytics/query.rs`
- [Export and rendering](https://github.com/dicklesworthstone/coding_agent_session_search/blob/main/src/export.rs): `src/export.rs`
- [Logical archives](https://github.com/dicklesworthstone/coding_agent_session_search/blob/main/src/logical_archive/mod.rs): `src/logical_archive/mod.rs`
- [Readiness diagnostics](https://github.com/dicklesworthstone/coding_agent_session_search/blob/main/src/doctor.rs): `src/doctor.rs`

### Other components

- **User or agent**
- **Local histories**
- **Local model files**

## Connections

- User or agent → CLI entry point: issues commands
- Local histories → Source discovery: provides sources
- CLI entry point → Source discovery: configures sources
- Source discovery → Agent connectors: selects providers
- Agent connectors → Conversation model: parses sessions
- Indexer → Canonical archive: writes conversations
- Indexer → Semantic indexing: builds vectors
- Semantic indexing → Canonical archive: reads conversations
- Semantic indexing → Local model files: loads local model
- Canonical archive → Lexical search: rebuilds lexical index
- Canonical archive → Semantic search: supplies filters
- User or agent → Robot search service: sends requests
- CLI entry point → Query and retrieval: dispatches search
- Query and retrieval → Lexical search: retrieves candidates
- Query and retrieval → Semantic search: refines results
- Robot search service → Lexical search: searches index
- Robot search service → Canonical archive: loads follow-up
- CLI entry point → Interactive TUI: launches interface
- Interactive TUI → Canonical archive: reads archive
- CLI entry point → Usage analytics: dispatches analytics
- Usage analytics → Canonical archive: queries usage data
- CLI entry point → Export and rendering: dispatches export
- Export and rendering → Canonical archive: reads conversations
- CLI entry point → Logical archives: dispatches archive tasks
- CLI entry point → Readiness diagnostics: dispatches diagnosis
- Readiness diagnostics → Canonical archive: checks readiness