# 10-tux/murphy architecture

> Architecture diagram of the GitHub repository 10-tux/murphy, 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/10-tux/murphy
- Repository: https://github.com/10-tux/murphy

## Overview

MURPHY is a FastAPI codebase assistant: developers provide a repository, which is parsed and indexed for retrieval-augmented natural-language answers. The graph follows the upload-to-query workflow and includes session, API, and model layers. README capabilities such as architecture exploration and documentation generation are product goals, not separately verified workflows here. Unsampled indexing internals are included where the source index identifies them; uncertain links are omitted.

Main entry points: [`main.py`](https://github.com/10-tux/murphy/blob/main/main.py) (FastAPI app), [`app/api/repository.py`](https://github.com/10-tux/murphy/blob/main/app/api/repository.py) (Repository API), [`app/services/repository_indexing_service.py`](https://github.com/10-tux/murphy/blob/main/app/services/repository_indexing_service.py) (Repository indexer), [`app/services/rag_service.py`](https://github.com/10-tux/murphy/blob/main/app/services/rag_service.py) (RAG pipeline)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and sessions"]
  node_fastapi["FastAPI app<br/>[main.py]"]
  node_repository_api["Repository API<br/>[repository.py]"]
  node_query_api["Query API<br/>[query.py]"]
  node_files_api["Files API<br/>[files.py]"]
  node_history_api["History API<br/>[history.py]"]
  node_status_api["Status API<br/>[status.py]"]
  node_sessions["Session registry<br/>[session_service.py]"]
end

subgraph group_repository["Repository intake"]
  node_repository_service["Repository handling"]
  node_workspace["Temporary workspace"]
end

subgraph group_processing["Parsing and indexing"]
  node_repo_indexer["Repository indexer"]
  node_generic_parser["Generic parser<br/>[generic_parser.py]"]
  node_python_parser["Python parser<br/>[python_parser.py]"]
  node_indexing["Document indexing"]
  node_chunking["Code chunking"]
end

subgraph group_answering["Retrieval and answers"]
  node_vector_store[("FAISS vector store")]
  node_embeddings["Embedding provider"]
  node_rag["RAG pipeline<br/>[rag_service.py]"]
  node_prompt["Prompt construction<br/>[prompt_service.py]"]
  node_llm["LLM service<br/>[llm_service.py]"]
end

subgraph group_configuration["Configuration and models"]
  node_parsed_file["Parsed file model<br/>[parsed_file.py]"]
  node_api_models["API schemas<br/>[api_models.py]"]
  node_settings["Application settings<br/>[config.py]"]
end

node_developer(("Developer"))
node_gemini["Google Gemini"]
node_huggingface["Sentence Transformers"]

node_developer -->|"uses API"| node_fastapi
node_fastapi -->|"mounts route"| node_repository_api
node_fastapi -->|"mounts route"| node_query_api
node_fastapi -->|"mounts route"| node_files_api
node_fastapi -->|"mounts route"| node_history_api
node_fastapi -->|"mounts route"| node_status_api
node_repository_api -->|"extracts and discovers"| node_repository_service
node_repository_api -->|"builds index"| node_repo_indexer
node_repository_api -->|"creates session"| node_sessions
node_repository_api -.->|"creates workspace"| node_workspace
node_query_api -->|"gets session"| node_sessions
node_query_api -->|"invokes query"| node_rag
node_files_api -->|"reads session"| node_sessions
node_history_api -->|"reads history"| node_sessions
node_status_api -->|"checks session"| node_sessions
node_repo_indexer -->|"selects parser"| node_generic_parser
node_repo_indexer -->|"selects parser"| node_python_parser
node_repo_indexer -->|"indexes files"| node_indexing
node_repo_indexer -->|"builds service"| node_rag
node_generic_parser -->|"creates model"| node_parsed_file
node_python_parser -->|"creates model"| node_parsed_file
node_indexing -->|"chunks content"| node_chunking
node_indexing -->|"stores chunks"| node_vector_store
node_chunking -->|"reads structure"| node_parsed_file
node_vector_store -->|"creates vectors"| node_embeddings
node_rag -->|"retrieves documents"| node_vector_store
node_rag -->|"builds prompt"| node_prompt
node_rag -->|"generates answer"| node_llm
node_embeddings -->|"creates provider"| node_gemini
node_embeddings -->|"creates provider"| node_huggingface
node_llm -->|"configures model"| node_gemini
node_embeddings -->|"loads settings"| node_settings
node_llm -->|"loads settings"| node_settings
node_vector_store -->|"loads settings"| node_settings
node_query_api -->|"validates response"| node_api_models
node_repository_api -->|"returns upload schema"| node_api_models

click node_fastapi "https://github.com/10-tux/murphy/blob/main/main.py"
click node_repository_api "https://github.com/10-tux/murphy/blob/main/app/api/repository.py"
click node_query_api "https://github.com/10-tux/murphy/blob/main/app/api/query.py"
click node_files_api "https://github.com/10-tux/murphy/blob/main/app/api/files.py"
click node_history_api "https://github.com/10-tux/murphy/blob/main/app/api/history.py"
click node_status_api "https://github.com/10-tux/murphy/blob/main/app/api/status.py"
click node_sessions "https://github.com/10-tux/murphy/blob/main/app/services/session_service.py"
click node_repository_service "https://github.com/10-tux/murphy/blob/main/app/services/repository_service.py"
click node_workspace "https://github.com/10-tux/murphy/blob/main/app/utils/temporary_workspace.py"
click node_repo_indexer "https://github.com/10-tux/murphy/blob/main/app/services/repository_indexing_service.py"
click node_generic_parser "https://github.com/10-tux/murphy/blob/main/app/parsers/generic_parser.py"
click node_python_parser "https://github.com/10-tux/murphy/blob/main/app/parsers/python_parser.py"
click node_parsed_file "https://github.com/10-tux/murphy/blob/main/app/models/parsed_file.py"
click node_indexing "https://github.com/10-tux/murphy/blob/main/app/services/indexing_service.py"
click node_chunking "https://github.com/10-tux/murphy/blob/main/app/services/chunking_service.py"
click node_vector_store "https://github.com/10-tux/murphy/blob/main/app/services/vector_store_service.py"
click node_embeddings "https://github.com/10-tux/murphy/blob/main/app/services/embedding_service.py"
click node_rag "https://github.com/10-tux/murphy/blob/main/app/services/rag_service.py"
click node_prompt "https://github.com/10-tux/murphy/blob/main/app/services/prompt_service.py"
click node_llm "https://github.com/10-tux/murphy/blob/main/app/services/llm_service.py"
click node_api_models "https://github.com/10-tux/murphy/blob/main/app/models/api_models.py"
click node_settings "https://github.com/10-tux/murphy/blob/main/app/core/config.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_fastapi,node_repository_api,node_query_api,node_files_api,node_history_api,node_status_api,node_sessions toneBlue
class node_repository_service,node_workspace toneAmber
class node_repo_indexer,node_generic_parser,node_python_parser,node_indexing,node_chunking toneMint
class node_vector_store,node_embeddings,node_rag,node_prompt,node_llm toneRose
class node_parsed_file,node_api_models,node_settings,node_developer,node_gemini,node_huggingface toneIndigo
```

## Components

### API and sessions

- [FastAPI app](https://github.com/10-tux/murphy/blob/main/main.py): `main.py`
- [Repository API](https://github.com/10-tux/murphy/blob/main/app/api/repository.py): `app/api/repository.py`
- [Query API](https://github.com/10-tux/murphy/blob/main/app/api/query.py): `app/api/query.py`
- [Files API](https://github.com/10-tux/murphy/blob/main/app/api/files.py): `app/api/files.py`
- [History API](https://github.com/10-tux/murphy/blob/main/app/api/history.py): `app/api/history.py`
- [Status API](https://github.com/10-tux/murphy/blob/main/app/api/status.py): `app/api/status.py`
- [Session registry](https://github.com/10-tux/murphy/blob/main/app/services/session_service.py): `app/services/session_service.py`

### Repository intake

- [Repository handling](https://github.com/10-tux/murphy/blob/main/app/services/repository_service.py): `app/services/repository_service.py`
- [Temporary workspace](https://github.com/10-tux/murphy/blob/main/app/utils/temporary_workspace.py): `app/utils/temporary_workspace.py`

### Parsing and indexing

- [Repository indexer](https://github.com/10-tux/murphy/blob/main/app/services/repository_indexing_service.py): `app/services/repository_indexing_service.py`
- [Generic parser](https://github.com/10-tux/murphy/blob/main/app/parsers/generic_parser.py): `app/parsers/generic_parser.py`
- [Python parser](https://github.com/10-tux/murphy/blob/main/app/parsers/python_parser.py): `app/parsers/python_parser.py`
- [Document indexing](https://github.com/10-tux/murphy/blob/main/app/services/indexing_service.py): `app/services/indexing_service.py`
- [Code chunking](https://github.com/10-tux/murphy/blob/main/app/services/chunking_service.py): `app/services/chunking_service.py`

### Retrieval and answers

- [FAISS vector store](https://github.com/10-tux/murphy/blob/main/app/services/vector_store_service.py): `app/services/vector_store_service.py`
- [Embedding provider](https://github.com/10-tux/murphy/blob/main/app/services/embedding_service.py): `app/services/embedding_service.py`
- [RAG pipeline](https://github.com/10-tux/murphy/blob/main/app/services/rag_service.py): `app/services/rag_service.py`
- [Prompt construction](https://github.com/10-tux/murphy/blob/main/app/services/prompt_service.py): `app/services/prompt_service.py`
- [LLM service](https://github.com/10-tux/murphy/blob/main/app/services/llm_service.py): `app/services/llm_service.py`

### Configuration and models

- [Parsed file model](https://github.com/10-tux/murphy/blob/main/app/models/parsed_file.py): `app/models/parsed_file.py`
- [API schemas](https://github.com/10-tux/murphy/blob/main/app/models/api_models.py): `app/models/api_models.py`
- [Application settings](https://github.com/10-tux/murphy/blob/main/app/core/config.py): `app/core/config.py`

### Other components

- **Developer**
- **Google Gemini**
- **Sentence Transformers**

## Connections

- Developer → FastAPI app: uses API (evidence: `README.md`)
- FastAPI app → Repository API: mounts route (evidence: `main.py`)
- FastAPI app → Query API: mounts route (evidence: `main.py`)
- FastAPI app → Files API: mounts route (evidence: `main.py`)
- FastAPI app → History API: mounts route (evidence: `main.py`)
- FastAPI app → Status API: mounts route (evidence: `main.py`)
- Repository API → Repository handling: extracts and discovers (evidence: `app/api/repository.py`)
- Repository API → Repository indexer: builds index (evidence: `app/api/repository.py`)
- Repository API → Session registry: creates session (evidence: `app/api/repository.py`)
- Repository API → Temporary workspace: creates workspace
- Query API → Session registry: gets session (evidence: `app/api/query.py`)
- Query API → RAG pipeline: invokes query (evidence: `app/api/query.py`)
- Files API → Session registry: reads session (evidence: `app/api/files.py`)
- History API → Session registry: reads history (evidence: `app/api/history.py`)
- Status API → Session registry: checks session (evidence: `app/api/status.py`)
- Repository indexer → Generic parser: selects parser (evidence: `app/services/repository_indexing_service.py`)
- Repository indexer → Python parser: selects parser (evidence: `app/services/repository_indexing_service.py`)
- Repository indexer → Document indexing: indexes files (evidence: `app/services/repository_indexing_service.py`)
- Repository indexer → RAG pipeline: builds service (evidence: `app/services/repository_indexing_service.py`)
- Generic parser → Parsed file model: creates model (evidence: `app/parsers/generic_parser.py`)
- Python parser → Parsed file model: creates model (evidence: `app/parsers/python_parser.py`)
- Document indexing → Code chunking: chunks content (evidence: `app/services/indexing_service.py`)
- Document indexing → FAISS vector store: stores chunks (evidence: `app/services/indexing_service.py`)
- Code chunking → Parsed file model: reads structure (evidence: `app/services/chunking_service.py`)
- FAISS vector store → Embedding provider: creates vectors (evidence: `app/services/vector_store_service.py`)
- RAG pipeline → FAISS vector store: retrieves documents (evidence: `app/services/rag_service.py`)
- RAG pipeline → Prompt construction: builds prompt (evidence: `app/services/rag_service.py`)
- RAG pipeline → LLM service: generates answer (evidence: `app/services/rag_service.py`)
- Embedding provider → Google Gemini: creates provider (evidence: `app/services/embedding_service.py`)
- Embedding provider → Sentence Transformers: creates provider (evidence: `app/services/embedding_service.py`)
- LLM service → Google Gemini: configures model (evidence: `app/services/llm_service.py`)
- Embedding provider → Application settings: loads settings (evidence: `app/services/embedding_service.py`)
- LLM service → Application settings: loads settings (evidence: `app/services/llm_service.py`)
- FAISS vector store → Application settings: loads settings (evidence: `app/services/vector_store_service.py`)
- Query API → API schemas: validates response (evidence: `app/api/query.py`)
- Repository API → API schemas: returns upload schema (evidence: `app/api/repository.py`)
