# mivaille777/aitrans architecture

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

- Interactive diagram: https://gitdiagram.com/mivaille777/aitrans
- Repository: https://github.com/mivaille777/aitrans

## Overview

AITrans is a local-first desktop research and knowledge workspace. Users bring in documents or browser selections, read and capture passages, then use chat or Agent workflows to synthesize evidence and reuse results in Research and Knowledge. The desktop UI calls a FastAPI backend; its Agent runtime coordinates bounded specialist tasks, while RAG supplies grounded retrieval and a dedicated debugging surface. The README documents the broader product branches; sampled source confirms selected API, retrieval, and persistence responsibilities, but does not expose every runtime call path.

Main entry points: [`backend/main.py`](https://github.com/mivaille777/aitrans/blob/main/backend/main.py) (FastAPI routes), [`apps/desktop/src/App.tsx`](https://github.com/mivaille777/aitrans/blob/main/apps/desktop/src/App.tsx) (Desktop workspaces), [`apps/desktop/src/features/reading/ReadingWorkspace.tsx`](https://github.com/mivaille777/aitrans/blob/main/apps/desktop/src/features/reading/ReadingWorkspace.tsx) (Reading workspace), [`backend/agent_core/runtime.py`](https://github.com/mivaille777/aitrans/blob/main/backend/agent_core/runtime.py) (Agent runtime)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_desktop["Desktop experience"]
  node_desktop_ui["Desktop workspaces<br/>[App.tsx]"]
  node_companion["Chat companion"]
  node_desktop_bridge["Desktop integration<br/>[main.rs]"]
  node_backend_api["FastAPI routes<br/>[main.py]"]
end

subgraph group_reading["Reading and language"]
  node_browser_selection["Browser selection<br/>[service_worker.js]"]
  node_selection_capture["Selection capture<br/>[manager.py]"]
  node_reading_workspace["Reading workspace"]
  node_translation["Translation<br/>[translation.py]"]
end

subgraph group_agent["Agent and research"]
  node_agent_workspace["Agent workspace<br/>[AgentWorkspace.tsx]"]
  node_agent_runtime["Agent runtime<br/>[runtime.py]"]
  node_research_orchestration["Research orchestration"]
  node_specialist_graphs["Specialist workflows"]
end

subgraph group_knowledge["Knowledge and evidence"]
  node_research_evidence["Research evidence<br/>[evidence_ledger.py]"]
  node_knowledge_workspace["Knowledge workspace<br/>[KnowledgeRoute.tsx]"]
  node_knowledge_service["Knowledge services<br/>[service.py]"]
end

subgraph group_retrieval["RAG and retrieval"]
  node_rag_debug_ui["RAG Debug Studio"]
  node_rag_debug_api["RAG debug API<br/>[rag_debug.py]"]
  node_rag_debug_service["RAG diagnostics"]
  node_retrieval_runtime["Retrieval pipeline"]
  node_vector_store[("Vector store<br/>[base.py]")]
  node_rag_debug_store[("Debug profiles store")]
end

node_user(("User"))
node_local_state[("Local runtime data<br/>[paths.py]")]
node_model_provider{{"Model provider"}}

node_user -->|"opens workspaces"| node_desktop_ui
node_desktop_ui -->|"uses typed APIs"| node_backend_api
node_desktop_ui -->|"presents Agent"| node_agent_workspace
node_desktop_ui -->|"presents reading"| node_reading_workspace
node_desktop_ui -->|"presents knowledge"| node_knowledge_workspace
node_desktop_ui -->|"presents chat"| node_companion
node_user -->|"selects passage"| node_browser_selection
node_browser_selection -.->|"sends context"| node_selection_capture
node_selection_capture -->|"supplies selection"| node_reading_workspace
node_desktop_bridge -->|"supports capture"| node_selection_capture
node_reading_workspace -->|"requests reading"| node_backend_api
node_reading_workspace -->|"requests translation"| node_translation
node_backend_api -->|"routes Agent work"| node_agent_runtime
node_agent_workspace -->|"requests Agent runs"| node_backend_api
node_companion -->|"requests chat"| node_backend_api
node_agent_runtime -.->|"coordinates research"| node_research_orchestration
node_research_orchestration -.->|"dispatches tasks"| node_specialist_graphs
node_agent_runtime -->|"uses language models"| node_model_provider
node_research_orchestration -.->|"organizes evidence"| node_research_evidence
node_research_evidence -->|"supports reuse"| node_knowledge_workspace
node_knowledge_workspace -->|"requests knowledge"| node_backend_api
node_backend_api -.->|"routes knowledge"| node_knowledge_service
node_rag_debug_ui -->|"requests diagnostics"| node_rag_debug_api
node_rag_debug_api -->|"delegates runs"| node_rag_debug_service
node_rag_debug_service -->|"runs retrieval"| node_retrieval_runtime
node_retrieval_runtime -->|"searches vectors"| node_vector_store
node_rag_debug_api -->|"loads profiles"| node_rag_debug_store
node_rag_debug_service -->|"persists debug data"| node_rag_debug_store
node_backend_api -.->|"uses local state"| node_local_state
node_knowledge_service -.->|"persists knowledge"| node_local_state

click node_desktop_ui "https://github.com/mivaille777/aitrans/blob/main/apps/desktop/src/App.tsx"
click node_companion "https://github.com/mivaille777/aitrans/blob/main/apps/desktop/src/features/companion/CompanionWorkspaceV2.tsx"
click node_desktop_bridge "https://github.com/mivaille777/aitrans/blob/main/apps/desktop/src-tauri/src/main.rs"
click node_browser_selection "https://github.com/mivaille777/aitrans/blob/main/browser_extension/aitrans_selection_bridge/service_worker.js"
click node_selection_capture "https://github.com/mivaille777/aitrans/blob/main/app/selection/manager.py"
click node_reading_workspace "https://github.com/mivaille777/aitrans/blob/main/apps/desktop/src/features/reading/ReadingWorkspace.tsx"
click node_translation "https://github.com/mivaille777/aitrans/blob/main/backend/api/translation.py"
click node_backend_api "https://github.com/mivaille777/aitrans/blob/main/backend/main.py"
click node_agent_workspace "https://github.com/mivaille777/aitrans/blob/main/apps/desktop/src/features/agent/AgentWorkspace.tsx"
click node_agent_runtime "https://github.com/mivaille777/aitrans/blob/main/backend/agent_core/runtime.py"
click node_research_orchestration "https://github.com/mivaille777/aitrans/blob/main/backend/services/research_orchestration_service.py"
click node_specialist_graphs "https://github.com/mivaille777/aitrans/tree/main/backend/agent_graph"
click node_research_evidence "https://github.com/mivaille777/aitrans/blob/main/app/research/evidence_ledger.py"
click node_knowledge_workspace "https://github.com/mivaille777/aitrans/blob/main/apps/desktop/src/features/knowledge/KnowledgeRoute.tsx"
click node_knowledge_service "https://github.com/mivaille777/aitrans/blob/main/backend/knowledge/service.py"
click node_rag_debug_ui "https://github.com/mivaille777/aitrans/blob/main/apps/desktop/src/features/settings/RagDebugStudioTrace.tsx"
click node_rag_debug_api "https://github.com/mivaille777/aitrans/blob/main/backend/api/rag_debug.py"
click node_rag_debug_service "https://github.com/mivaille777/aitrans/blob/main/backend/services/rag_debug_service.py"
click node_retrieval_runtime "https://github.com/mivaille777/aitrans/blob/main/backend/rag/retrieval_service.py"
click node_vector_store "https://github.com/mivaille777/aitrans/blob/main/backend/rag/stores/base.py"
click node_rag_debug_store "https://github.com/mivaille777/aitrans/blob/main/backend/services/rag_debug_store_service.py"
click node_local_state "https://github.com/mivaille777/aitrans/blob/main/app/infrastructure/paths.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_desktop_ui,node_companion,node_desktop_bridge,node_backend_api,node_user toneBlue
class node_browser_selection,node_selection_capture,node_reading_workspace,node_translation,node_local_state toneAmber
class node_agent_workspace,node_agent_runtime,node_research_orchestration,node_specialist_graphs toneMint
class node_research_evidence,node_knowledge_workspace,node_knowledge_service toneRose
class node_rag_debug_ui,node_rag_debug_api,node_rag_debug_service,node_retrieval_runtime,node_vector_store,node_rag_debug_store,node_model_provider toneIndigo
```

## Components

### Desktop experience

- [Desktop workspaces](https://github.com/mivaille777/aitrans/blob/main/apps/desktop/src/App.tsx): `apps/desktop/src/App.tsx`
- [Chat companion](https://github.com/mivaille777/aitrans/blob/main/apps/desktop/src/features/companion/CompanionWorkspaceV2.tsx): `apps/desktop/src/features/companion/CompanionWorkspaceV2.tsx`
- [Desktop integration](https://github.com/mivaille777/aitrans/blob/main/apps/desktop/src-tauri/src/main.rs): `apps/desktop/src-tauri/src/main.rs`
- [FastAPI routes](https://github.com/mivaille777/aitrans/blob/main/backend/main.py): `backend/main.py`

### Reading and language

- [Browser selection](https://github.com/mivaille777/aitrans/blob/main/browser_extension/aitrans_selection_bridge/service_worker.js): `browser_extension/aitrans_selection_bridge/service_worker.js`
- [Selection capture](https://github.com/mivaille777/aitrans/blob/main/app/selection/manager.py): `app/selection/manager.py`
- [Reading workspace](https://github.com/mivaille777/aitrans/blob/main/apps/desktop/src/features/reading/ReadingWorkspace.tsx): `apps/desktop/src/features/reading/ReadingWorkspace.tsx`
- [Translation](https://github.com/mivaille777/aitrans/blob/main/backend/api/translation.py): `backend/api/translation.py`

### Agent and research

- [Agent workspace](https://github.com/mivaille777/aitrans/blob/main/apps/desktop/src/features/agent/AgentWorkspace.tsx): `apps/desktop/src/features/agent/AgentWorkspace.tsx`
- [Agent runtime](https://github.com/mivaille777/aitrans/blob/main/backend/agent_core/runtime.py): `backend/agent_core/runtime.py`
- [Research orchestration](https://github.com/mivaille777/aitrans/blob/main/backend/services/research_orchestration_service.py): `backend/services/research_orchestration_service.py`
- [Specialist workflows](https://github.com/mivaille777/aitrans/tree/main/backend/agent_graph): `backend/agent_graph`

### Knowledge and evidence

- [Research evidence](https://github.com/mivaille777/aitrans/blob/main/app/research/evidence_ledger.py): `app/research/evidence_ledger.py`
- [Knowledge workspace](https://github.com/mivaille777/aitrans/blob/main/apps/desktop/src/features/knowledge/KnowledgeRoute.tsx): `apps/desktop/src/features/knowledge/KnowledgeRoute.tsx`
- [Knowledge services](https://github.com/mivaille777/aitrans/blob/main/backend/knowledge/service.py): `backend/knowledge/service.py`

### RAG and retrieval

- [RAG Debug Studio](https://github.com/mivaille777/aitrans/blob/main/apps/desktop/src/features/settings/RagDebugStudioTrace.tsx): `apps/desktop/src/features/settings/RagDebugStudioTrace.tsx`
- [RAG debug API](https://github.com/mivaille777/aitrans/blob/main/backend/api/rag_debug.py): `backend/api/rag_debug.py`
- [RAG diagnostics](https://github.com/mivaille777/aitrans/blob/main/backend/services/rag_debug_service.py): `backend/services/rag_debug_service.py`
- [Retrieval pipeline](https://github.com/mivaille777/aitrans/blob/main/backend/rag/retrieval_service.py): `backend/rag/retrieval_service.py`
- [Vector store](https://github.com/mivaille777/aitrans/blob/main/backend/rag/stores/base.py): `backend/rag/stores/base.py`
- [Debug profiles store](https://github.com/mivaille777/aitrans/blob/main/backend/services/rag_debug_store_service.py): `backend/services/rag_debug_store_service.py`

### Other components

- **User**
- [Local runtime data](https://github.com/mivaille777/aitrans/blob/main/app/infrastructure/paths.py): `app/infrastructure/paths.py`
- **Model provider**

## Connections

- User → Desktop workspaces: opens workspaces
- Desktop workspaces → FastAPI routes: uses typed APIs
- Desktop workspaces → Agent workspace: presents Agent (evidence: `apps/desktop/src/App.tsx`)
- Desktop workspaces → Reading workspace: presents reading (evidence: `apps/desktop/src/App.tsx`)
- Desktop workspaces → Knowledge workspace: presents knowledge (evidence: `apps/desktop/src/App.tsx`)
- Desktop workspaces → Chat companion: presents chat (evidence: `apps/desktop/src/App.tsx`)
- User → Browser selection: selects passage
- Browser selection → Selection capture: sends context
- Selection capture → Reading workspace: supplies selection
- Desktop integration → Selection capture: supports capture
- Reading workspace → FastAPI routes: requests reading
- Reading workspace → Translation: requests translation
- FastAPI routes → Agent runtime: routes Agent work
- Agent workspace → FastAPI routes: requests Agent runs
- Chat companion → FastAPI routes: requests chat
- Agent runtime → Research orchestration: coordinates research
- Research orchestration → Specialist workflows: dispatches tasks
- Agent runtime → Model provider: uses language models
- Research orchestration → Research evidence: organizes evidence
- Research evidence → Knowledge workspace: supports reuse
- Knowledge workspace → FastAPI routes: requests knowledge
- FastAPI routes → Knowledge services: routes knowledge
- RAG Debug Studio → RAG debug API: requests diagnostics
- RAG debug API → RAG diagnostics: delegates runs (evidence: `backend/api/rag_debug.py`)
- RAG diagnostics → Retrieval pipeline: runs retrieval (evidence: `backend/services/rag_debug_service.py`)
- Retrieval pipeline → Vector store: searches vectors (evidence: `backend/rag/retrieval_service.py`)
- RAG debug API → Debug profiles store: loads profiles (evidence: `backend/api/rag_debug.py`)
- RAG diagnostics → Debug profiles store: persists debug data (evidence: `backend/services/rag_debug_service.py`)
- FastAPI routes → Local runtime data: uses local state
- Knowledge services → Local runtime data: persists knowledge