# 2501pr0ject/rustsensei architecture

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

- Interactive diagram: https://gitdiagram.com/2501pr0ject/rustsensei
- Repository: https://github.com/2501pr0ject/rustsensei

## Overview

RustSensei is a French-language local Rust tutor. Its main workflow takes a question from the web UI or CLI through chat handling, optionally retrieves relevant Rust documentation and citations, then generates an answer with local llama.cpp; the API can reuse cached responses. Separate documented capabilities include the French/English Rust concept graph, streaming UI, and automated evaluation. Edges follow shown calls or README statements; unsampled integrations are omitted rather than inferred.

Main entry points: [`app/api.py`](https://github.com/2501pr0ject/rustsensei/blob/main/app/api.py) (Chat API), [`app/rag.py`](https://github.com/2501pr0ject/rustsensei/blob/main/app/rag.py) (Hybrid retrieval), [`app/chat.py`](https://github.com/2501pr0ject/rustsensei/blob/main/app/chat.py) (Chat workflow), [`app/inference.py`](https://github.com/2501pr0ject/rustsensei/blob/main/app/inference.py) (Inference settings)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User interfaces"]
  node_web["Web chat<br/>[App.tsx]"]
  node_cli["Chat CLI<br/>[cli.py]"]
  node_api["Chat API<br/>[api.py]"]
end

subgraph group_answering["Answer generation"]
  node_chat["Chat workflow<br/>[chat.py]"]
  node_cache["Response cache<br/>[cache.py]"]
  node_inference["Inference settings<br/>[inference.py]"]
  node_server_manager["Server manager<br/>[llama_server.py]"]
  node_llama["llama.cpp runtime"]
  node_model_config["Model settings<br/>[model_config.yaml]"]
end

subgraph group_knowledge["Rust knowledge"]
  node_retriever["Hybrid retrieval<br/>[rag.py]"]
  node_knowledge_graph["Concept graph<br/>[knowledge.py]"]
  node_rag_index[("RAG index")]
  node_rust_docs["Rust documentation"]
  node_rag_config["RAG settings<br/>[rag_config.yaml]"]
end

subgraph group_evaluation["Evaluation"]
  node_eval_runner["Evaluation runner<br/>[evaluate.py]"]
  node_eval_prompts["Evaluation prompts<br/>[prompts_fr.jsonl]"]
  node_compiler_check["Rust compilation check<br/>[compile_check.py]"]
end

node_learner(("Learner"))

node_learner -->|"asks via"| node_web
node_learner -->|"asks via"| node_cli
node_web -->|"calls"| node_api
node_cli -->|"starts"| node_chat
node_api -->|"retrieves with"| node_retriever
node_api -->|"checks"| node_cache
node_api -->|"streams through"| node_server_manager
node_chat -->|"retrieves with"| node_retriever
node_chat -->|"checks"| node_cache
node_chat -->|"uses settings"| node_inference
node_server_manager -->|"starts"| node_llama
node_api -->|"formats sampling"| node_inference
node_retriever -->|"expands queries"| node_knowledge_graph
node_retriever -->|"searches"| node_rag_index
node_rust_docs -->|"indexed into"| node_rag_index
node_model_config -->|"configures"| node_inference
node_rag_config -->|"configures"| node_retriever
node_eval_runner -->|"evaluates"| node_eval_prompts
node_eval_runner -->|"checks code with"| node_compiler_check
node_eval_runner -->|"uses settings"| node_inference

click node_web "https://github.com/2501pr0ject/rustsensei/blob/main/frontend/src/App.tsx"
click node_cli "https://github.com/2501pr0ject/rustsensei/blob/main/app/cli.py"
click node_api "https://github.com/2501pr0ject/rustsensei/blob/main/app/api.py"
click node_chat "https://github.com/2501pr0ject/rustsensei/blob/main/app/chat.py"
click node_cache "https://github.com/2501pr0ject/rustsensei/blob/main/app/cache.py"
click node_inference "https://github.com/2501pr0ject/rustsensei/blob/main/app/inference.py"
click node_server_manager "https://github.com/2501pr0ject/rustsensei/blob/main/app/llama_server.py"
click node_retriever "https://github.com/2501pr0ject/rustsensei/blob/main/app/rag.py"
click node_knowledge_graph "https://github.com/2501pr0ject/rustsensei/blob/main/app/knowledge.py"
click node_rag_index "https://github.com/2501pr0ject/rustsensei/tree/main/rag/index"
click node_rust_docs "https://github.com/2501pr0ject/rustsensei/tree/main/rag/docs"
click node_model_config "https://github.com/2501pr0ject/rustsensei/blob/main/configs/model_config.yaml"
click node_rag_config "https://github.com/2501pr0ject/rustsensei/blob/main/configs/rag_config.yaml"
click node_eval_runner "https://github.com/2501pr0ject/rustsensei/blob/main/scripts/evaluate.py"
click node_eval_prompts "https://github.com/2501pr0ject/rustsensei/blob/main/eval/prompts_fr.jsonl"
click node_compiler_check "https://github.com/2501pr0ject/rustsensei/blob/main/scripts/compile_check.py"

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_web,node_cli,node_api toneBlue
class node_chat,node_cache,node_inference,node_server_manager,node_llama,node_model_config toneAmber
class node_retriever,node_knowledge_graph,node_rag_index,node_rust_docs,node_rag_config toneMint
class node_eval_runner,node_eval_prompts,node_compiler_check toneRose
class node_learner toneIndigo
```

## Components

### User interfaces

- [Web chat](https://github.com/2501pr0ject/rustsensei/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Chat CLI](https://github.com/2501pr0ject/rustsensei/blob/main/app/cli.py): `app/cli.py`
- [Chat API](https://github.com/2501pr0ject/rustsensei/blob/main/app/api.py): `app/api.py`

### Answer generation

- [Chat workflow](https://github.com/2501pr0ject/rustsensei/blob/main/app/chat.py): `app/chat.py`
- [Response cache](https://github.com/2501pr0ject/rustsensei/blob/main/app/cache.py): `app/cache.py`
- [Inference settings](https://github.com/2501pr0ject/rustsensei/blob/main/app/inference.py): `app/inference.py`
- [Server manager](https://github.com/2501pr0ject/rustsensei/blob/main/app/llama_server.py): `app/llama_server.py`
- **llama.cpp runtime**
- [Model settings](https://github.com/2501pr0ject/rustsensei/blob/main/configs/model_config.yaml): `configs/model_config.yaml`

### Rust knowledge

- [Hybrid retrieval](https://github.com/2501pr0ject/rustsensei/blob/main/app/rag.py): `app/rag.py`
- [Concept graph](https://github.com/2501pr0ject/rustsensei/blob/main/app/knowledge.py): `app/knowledge.py`
- [RAG index](https://github.com/2501pr0ject/rustsensei/tree/main/rag/index): `rag/index`
- [Rust documentation](https://github.com/2501pr0ject/rustsensei/tree/main/rag/docs): `rag/docs`
- [RAG settings](https://github.com/2501pr0ject/rustsensei/blob/main/configs/rag_config.yaml): `configs/rag_config.yaml`

### Evaluation

- [Evaluation runner](https://github.com/2501pr0ject/rustsensei/blob/main/scripts/evaluate.py): `scripts/evaluate.py`
- [Evaluation prompts](https://github.com/2501pr0ject/rustsensei/blob/main/eval/prompts_fr.jsonl): `eval/prompts_fr.jsonl`
- [Rust compilation check](https://github.com/2501pr0ject/rustsensei/blob/main/scripts/compile_check.py): `scripts/compile_check.py`

### Other components

- **Learner**

## Connections

- Learner → Web chat: asks via (evidence: `README.md`)
- Learner → Chat CLI: asks via (evidence: `README.md`)
- Web chat → Chat API: calls (evidence: `README.md`)
- Chat CLI → Chat workflow: starts (evidence: `app/cli.py`)
- Chat API → Hybrid retrieval: retrieves with (evidence: `app/api.py`)
- Chat API → Response cache: checks (evidence: `app/api.py`)
- Chat API → Server manager: streams through (evidence: `app/api.py`)
- Chat workflow → Hybrid retrieval: retrieves with (evidence: `app/chat.py`)
- Chat workflow → Response cache: checks (evidence: `app/chat.py`)
- Chat workflow → Inference settings: uses settings (evidence: `app/chat.py`)
- Server manager → llama.cpp runtime: starts (evidence: `app/llama_server.py`)
- Chat API → Inference settings: formats sampling (evidence: `app/inference.py`)
- Hybrid retrieval → Concept graph: expands queries (evidence: `app/rag.py`)
- Hybrid retrieval → RAG index: searches (evidence: `README.md`)
- Rust documentation → RAG index: indexed into (evidence: `README.md`)
- Model settings → Inference settings: configures (evidence: `README.md`)
- RAG settings → Hybrid retrieval: configures (evidence: `README.md`)
- Evaluation runner → Evaluation prompts: evaluates (evidence: `README.md`)
- Evaluation runner → Rust compilation check: checks code with (evidence: `scripts/evaluate.py`)
- Evaluation runner → Inference settings: uses settings (evidence: `scripts/evaluate.py`)
