# a7ex-turcan/rtfm architecture

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

- Interactive diagram: https://gitdiagram.com/a7ex-turcan/rtfm
- Repository: https://github.com/a7ex-turcan/rtfm

## Overview

RTFM is a local documentation retrieval system. A developer indexes files or connected Jira/Confluence sources; documents are converted, chunked, and stored in OpenSearch. An MCP server exposes search and related tools to an LLM client, with hybrid retrieval and optional local embeddings/reranking. The repository also supports notes, contradiction detection, live database queries, status/catalog tools, and watching folders. Some subsystem links are based on README descriptions because their implementations were not sampled.

Main entry points: [`src/Rtfm.Core/Indexing/DocumentIngestor.cs`](https://github.com/a7ex-turcan/rtfm/blob/main/src/Rtfm.Core/Indexing/DocumentIngestor.cs) (Ingestion coordinator), [`src/Rtfm.Core/Search/DocumentSearch.cs`](https://github.com/a7ex-turcan/rtfm/blob/main/src/Rtfm.Core/Search/DocumentSearch.cs) (Document search), [`src/Rtfm.Cli/Commands/WatchCommand.cs`](https://github.com/a7ex-turcan/rtfm/blob/main/src/Rtfm.Cli/Commands/WatchCommand.cs) (Folder watch), [`src/Rtfm.Cli/Commands/ConfluenceCommand.cs`](https://github.com/a7ex-turcan/rtfm/blob/main/src/Rtfm.Cli/Commands/ConfluenceCommand.cs) (Confluence commands)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI workflows"]
  node_cli["RTFM CLI<br/>[Program.cs]"]
  node_fileindex["File indexing<br/>[IndexCommand.cs]"]
  node_watch["Folder watch<br/>[WatchCommand.cs]"]
  node_confluencecmd["Confluence commands"]
  node_jiracmd["Jira commands<br/>[JiraCommand.cs]"]
end

subgraph group_ingest["Ingestion and sources"]
  node_convert["Document conversion"]
  node_chunk["Markdown chunking<br/>[MarkdownChunker.cs]"]
  node_ingestor["Ingestion coordinator"]
  node_confluence["Confluence crawler"]
  node_jira["Jira crawler<br/>[JiraCrawler.cs]"]
  node_watcher["Filesystem watcher<br/>[FolderWatcher.cs]"]
end

subgraph group_retrieval["Search and analysis"]
  node_search["Document search<br/>[DocumentSearch.cs]"]
  node_embed["Local embeddings<br/>[LocalEmbedder.cs]"]
  node_contradictions["Contradiction detection"]
  node_notes["Notes<br/>[NotesStore.cs]"]
  node_databasequery["Database queries"]
end

subgraph group_storage["Index and state"]
  node_opensearch[("OpenSearch")]
  node_indexer["Document indexer<br/>[DocumentIndexer.cs]"]
end

subgraph group_mcp["MCP interface"]
  node_mcp["MCP server<br/>[Program.cs]"]
  node_searchtool["Search tool<br/>[SearchDocsTool.cs]"]
  node_dbtools["Database tools<br/>[DatabaseTools.cs]"]
end

node_developer(("Developer"))
node_llm(("LLM client"))

node_developer -->|"runs commands"| node_cli
node_cli -->|"dispatches"| node_fileindex
node_developer -->|"indexes documents"| node_fileindex
node_fileindex -.->|"ingests files"| node_ingestor
node_ingestor -->|"converts"| node_convert
node_ingestor -->|"chunks markdown"| node_chunk
node_ingestor -->|"embeds chunks"| node_embed
node_ingestor -->|"indexes chunks"| node_indexer
node_indexer -->|"writes documents"| node_opensearch
node_developer -->|"imports content"| node_confluencecmd
node_confluencecmd -->|"crawls pages"| node_confluence
node_confluencecmd -->|"ingests pages"| node_ingestor
node_developer -.->|"imports content"| node_jiracmd
node_jiracmd -->|"crawls issues"| node_jira
node_jiracmd -->|"ingests issues"| node_ingestor
node_developer -->|"monitors folder"| node_watch
node_watch -->|"watches changes"| node_watcher
node_watch -->|"reindexes changes"| node_ingestor
node_llm -->|"sends MCP requests"| node_mcp
node_mcp -.->|"registers tools"| node_searchtool
node_searchtool -->|"runs search"| node_search
node_search -->|"queries index"| node_opensearch
node_search -->|"embeds query"| node_embed
node_search -->|"annotates results"| node_notes
node_mcp -.->|"registers tools"| node_dbtools
node_dbtools -->|"executes queries"| node_databasequery
node_databasequery -.->|"queries live database"| node_developer
node_ingestor -->|"checks new chunks"| node_contradictions
node_contradictions -->|"stores pairs"| node_opensearch

click node_cli "https://github.com/a7ex-turcan/rtfm/blob/main/src/Rtfm.Cli/Program.cs"
click node_fileindex "https://github.com/a7ex-turcan/rtfm/blob/main/src/Rtfm.Cli/Commands/IndexCommand.cs"
click node_watch "https://github.com/a7ex-turcan/rtfm/blob/main/src/Rtfm.Cli/Commands/WatchCommand.cs"
click node_confluencecmd "https://github.com/a7ex-turcan/rtfm/blob/main/src/Rtfm.Cli/Commands/ConfluenceCommand.cs"
click node_jiracmd "https://github.com/a7ex-turcan/rtfm/blob/main/src/Rtfm.Cli/Commands/JiraCommand.cs"
click node_convert "https://github.com/a7ex-turcan/rtfm/blob/main/src/Rtfm.Core/Conversion/DocumentConverter.cs"
click node_chunk "https://github.com/a7ex-turcan/rtfm/blob/main/src/Rtfm.Core/Chunking/MarkdownChunker.cs"
click node_ingestor "https://github.com/a7ex-turcan/rtfm/blob/main/src/Rtfm.Core/Indexing/DocumentIngestor.cs"
click node_confluence "https://github.com/a7ex-turcan/rtfm/blob/main/src/Rtfm.Core/Confluence/ConfluenceCrawler.cs"
click node_jira "https://github.com/a7ex-turcan/rtfm/blob/main/src/Rtfm.Core/Jira/JiraCrawler.cs"
click node_watcher "https://github.com/a7ex-turcan/rtfm/blob/main/src/Rtfm.Core/Watch/FolderWatcher.cs"
click node_search "https://github.com/a7ex-turcan/rtfm/blob/main/src/Rtfm.Core/Search/DocumentSearch.cs"
click node_embed "https://github.com/a7ex-turcan/rtfm/blob/main/src/Rtfm.Core/Embeddings/LocalEmbedder.cs"
click node_contradictions "https://github.com/a7ex-turcan/rtfm/blob/main/src/Rtfm.Core/Contradictions/ContradictionDetector.cs"
click node_notes "https://github.com/a7ex-turcan/rtfm/blob/main/src/Rtfm.Core/Notes/NotesStore.cs"
click node_databasequery "https://github.com/a7ex-turcan/rtfm/blob/main/src/Rtfm.Core/Database/DatabaseQueryService.cs"
click node_indexer "https://github.com/a7ex-turcan/rtfm/blob/main/src/Rtfm.Core/Indexing/DocumentIndexer.cs"
click node_mcp "https://github.com/a7ex-turcan/rtfm/blob/main/src/Rtfm.Mcp/Program.cs"
click node_searchtool "https://github.com/a7ex-turcan/rtfm/blob/main/src/Rtfm.Mcp/SearchDocsTool.cs"
click node_dbtools "https://github.com/a7ex-turcan/rtfm/blob/main/src/Rtfm.Mcp/DatabaseTools.cs"

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_cli,node_fileindex,node_watch,node_confluencecmd,node_jiracmd,node_llm toneBlue
class node_convert,node_chunk,node_ingestor,node_confluence,node_jira,node_watcher toneAmber
class node_search,node_embed,node_contradictions,node_notes,node_databasequery toneMint
class node_opensearch,node_indexer toneRose
class node_mcp,node_searchtool,node_dbtools,node_developer toneIndigo
```

## Components

### CLI workflows

- [RTFM CLI](https://github.com/a7ex-turcan/rtfm/blob/main/src/Rtfm.Cli/Program.cs): `src/Rtfm.Cli/Program.cs`
- [File indexing](https://github.com/a7ex-turcan/rtfm/blob/main/src/Rtfm.Cli/Commands/IndexCommand.cs): `src/Rtfm.Cli/Commands/IndexCommand.cs`
- [Folder watch](https://github.com/a7ex-turcan/rtfm/blob/main/src/Rtfm.Cli/Commands/WatchCommand.cs): `src/Rtfm.Cli/Commands/WatchCommand.cs`
- [Confluence commands](https://github.com/a7ex-turcan/rtfm/blob/main/src/Rtfm.Cli/Commands/ConfluenceCommand.cs): `src/Rtfm.Cli/Commands/ConfluenceCommand.cs`
- [Jira commands](https://github.com/a7ex-turcan/rtfm/blob/main/src/Rtfm.Cli/Commands/JiraCommand.cs): `src/Rtfm.Cli/Commands/JiraCommand.cs`

### Ingestion and sources

- [Document conversion](https://github.com/a7ex-turcan/rtfm/blob/main/src/Rtfm.Core/Conversion/DocumentConverter.cs): `src/Rtfm.Core/Conversion/DocumentConverter.cs`
- [Markdown chunking](https://github.com/a7ex-turcan/rtfm/blob/main/src/Rtfm.Core/Chunking/MarkdownChunker.cs): `src/Rtfm.Core/Chunking/MarkdownChunker.cs`
- [Ingestion coordinator](https://github.com/a7ex-turcan/rtfm/blob/main/src/Rtfm.Core/Indexing/DocumentIngestor.cs): `src/Rtfm.Core/Indexing/DocumentIngestor.cs`
- [Confluence crawler](https://github.com/a7ex-turcan/rtfm/blob/main/src/Rtfm.Core/Confluence/ConfluenceCrawler.cs): `src/Rtfm.Core/Confluence/ConfluenceCrawler.cs`
- [Jira crawler](https://github.com/a7ex-turcan/rtfm/blob/main/src/Rtfm.Core/Jira/JiraCrawler.cs): `src/Rtfm.Core/Jira/JiraCrawler.cs`
- [Filesystem watcher](https://github.com/a7ex-turcan/rtfm/blob/main/src/Rtfm.Core/Watch/FolderWatcher.cs): `src/Rtfm.Core/Watch/FolderWatcher.cs`

### Search and analysis

- [Document search](https://github.com/a7ex-turcan/rtfm/blob/main/src/Rtfm.Core/Search/DocumentSearch.cs): `src/Rtfm.Core/Search/DocumentSearch.cs`
- [Local embeddings](https://github.com/a7ex-turcan/rtfm/blob/main/src/Rtfm.Core/Embeddings/LocalEmbedder.cs): `src/Rtfm.Core/Embeddings/LocalEmbedder.cs`
- [Contradiction detection](https://github.com/a7ex-turcan/rtfm/blob/main/src/Rtfm.Core/Contradictions/ContradictionDetector.cs): `src/Rtfm.Core/Contradictions/ContradictionDetector.cs`
- [Notes](https://github.com/a7ex-turcan/rtfm/blob/main/src/Rtfm.Core/Notes/NotesStore.cs): `src/Rtfm.Core/Notes/NotesStore.cs`
- [Database queries](https://github.com/a7ex-turcan/rtfm/blob/main/src/Rtfm.Core/Database/DatabaseQueryService.cs): `src/Rtfm.Core/Database/DatabaseQueryService.cs`

### Index and state

- **OpenSearch**
- [Document indexer](https://github.com/a7ex-turcan/rtfm/blob/main/src/Rtfm.Core/Indexing/DocumentIndexer.cs): `src/Rtfm.Core/Indexing/DocumentIndexer.cs`

### MCP interface

- [MCP server](https://github.com/a7ex-turcan/rtfm/blob/main/src/Rtfm.Mcp/Program.cs): `src/Rtfm.Mcp/Program.cs`
- [Search tool](https://github.com/a7ex-turcan/rtfm/blob/main/src/Rtfm.Mcp/SearchDocsTool.cs): `src/Rtfm.Mcp/SearchDocsTool.cs`
- [Database tools](https://github.com/a7ex-turcan/rtfm/blob/main/src/Rtfm.Mcp/DatabaseTools.cs): `src/Rtfm.Mcp/DatabaseTools.cs`

### Other components

- **Developer**
- **LLM client**

## Connections

- Developer → RTFM CLI: runs commands
- RTFM CLI → File indexing: dispatches (evidence: `src/Rtfm.Cli/Program.cs`)
- Developer → File indexing: indexes documents
- File indexing → Ingestion coordinator: ingests files
- Ingestion coordinator → Document conversion: converts (evidence: `src/Rtfm.Core/Indexing/DocumentIngestor.cs`)
- Ingestion coordinator → Markdown chunking: chunks markdown (evidence: `src/Rtfm.Core/Indexing/DocumentIngestor.cs`)
- Ingestion coordinator → Local embeddings: embeds chunks (evidence: `src/Rtfm.Core/Indexing/DocumentIngestor.cs`)
- Ingestion coordinator → Document indexer: indexes chunks (evidence: `src/Rtfm.Core/Indexing/DocumentIngestor.cs`)
- Document indexer → OpenSearch: writes documents (evidence: `src/Rtfm.Core/Indexing/DocumentIndexer.cs`)
- Developer → Confluence commands: imports content
- Confluence commands → Confluence crawler: crawls pages (evidence: `src/Rtfm.Cli/Commands/ConfluenceCommand.cs`)
- Confluence commands → Ingestion coordinator: ingests pages (evidence: `src/Rtfm.Cli/Commands/ConfluenceCommand.cs`)
- Developer → Jira commands: imports content
- Jira commands → Jira crawler: crawls issues (evidence: `src/Rtfm.Cli/Commands/JiraCommand.cs`)
- Jira commands → Ingestion coordinator: ingests issues (evidence: `src/Rtfm.Cli/Commands/JiraCommand.cs`)
- Developer → Folder watch: monitors folder
- Folder watch → Filesystem watcher: watches changes (evidence: `src/Rtfm.Cli/Commands/WatchCommand.cs`)
- Folder watch → Ingestion coordinator: reindexes changes (evidence: `src/Rtfm.Cli/Commands/WatchCommand.cs`)
- LLM client → MCP server: sends MCP requests
- MCP server → Search tool: registers tools
- Search tool → Document search: runs search (evidence: `src/Rtfm.Mcp/SearchDocsTool.cs`)
- Document search → OpenSearch: queries index (evidence: `src/Rtfm.Core/Search/DocumentSearch.cs`)
- Document search → Local embeddings: embeds query (evidence: `src/Rtfm.Core/Search/DocumentSearch.cs`)
- Document search → Notes: annotates results (evidence: `src/Rtfm.Core/Search/DocumentSearch.cs`)
- MCP server → Database tools: registers tools
- Database tools → Database queries: executes queries (evidence: `src/Rtfm.Mcp/DatabaseTools.cs`)
- Database queries → Developer: queries live database
- Ingestion coordinator → Contradiction detection: checks new chunks (evidence: `src/Rtfm.Core/Indexing/DocumentIngestor.cs`)
- Contradiction detection → OpenSearch: stores pairs (evidence: `src/Rtfm.Core/Contradictions/ContradictionDetector.cs`)
