# yousif-gh/guidely architecture

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

- Interactive diagram: https://gitdiagram.com/yousif-gh/guidely
- Repository: https://github.com/yousif-gh/guidely

## Overview

Guidely lets employees ask questions about company documents and receive grounded answers with cited sources. The main workflow runs from the search page through the FastAPI ask route, vector retrieval and score filtering, then Groq answer generation; the UI displays the answer and sources. A separate admin workflow uploads or reindexes text documents, which are parsed, chunked, embedded and indexed. Health and in-memory metrics provide operational visibility. The README documents frontend/backend operation; the specific frontend-to-API wiring is not shown in the excerpts, so that link is marked unverified.

Main entry points: [`backend/services/vector_store.py`](https://github.com/yousif-gh/guidely/blob/main/backend/services/vector_store.py) (Vector indexing and retrieval), [`backend/routes/search.py`](https://github.com/yousif-gh/guidely/blob/main/backend/routes/search.py) (Search and ask routes), [`backend/main.py`](https://github.com/yousif-gh/guidely/blob/main/backend/main.py) (FastAPI app), [`backend/routes/documents.py`](https://github.com/yousif-gh/guidely/blob/main/backend/routes/documents.py) (Document routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["User interface"]
  node_app["Page navigation<br/>[App.jsx]"]
  node_search_ui["Ask and sources<br/>[SearchPage.jsx]"]
  node_source_list["Source display<br/>[SourceList.jsx]"]
  node_admin_ui["Document admin<br/>[AdminPage.jsx]"]
end

subgraph group_api["API and workflows"]
  node_server["FastAPI app<br/>[main.py]"]
  node_request_model["Search request<br/>[record.py]"]
  node_document_routes["Document routes<br/>[documents.py]"]
  node_search_routes["Search and ask routes<br/>[search.py]"]
end

subgraph group_indexing["Document indexing"]
  node_document_files[("Text documents")]
  node_parsing["Text parsing and chunks<br/>[parsing.py]"]
  node_embeddings["Local embeddings<br/>[embeddings.py]"]
end

subgraph group_answering["Retrieval and answers"]
  node_vector_store["Vector indexing and retrieval<br/>[vector_store.py]"]
  node_llm["Answer generation<br/>[llm.py]"]
end

subgraph group_operations["State and metrics"]
  node_index_files[("FAISS index and chunks")]
  node_embedding_cache[("Embedding cache")]
  node_metrics["Request and cache metrics<br/>[metrics.py]"]
end

node_employee(("Employee"))
node_groq["Groq API"]

node_employee -->|"uses"| node_app
node_app -->|"renders"| node_search_ui
node_app -->|"renders"| node_admin_ui
node_search_ui -.->|"submits question"| node_search_routes
node_search_ui -->|"renders sources"| node_source_list
node_admin_ui -.->|"manages documents"| node_document_routes
node_server -->|"registers"| node_document_routes
node_server -->|"registers"| node_search_routes
node_server -->|"records requests"| node_metrics
node_server -->|"reads snapshot"| node_metrics
node_server -->|"reads index state"| node_vector_store
node_search_routes -->|"validates requests"| node_request_model
node_document_routes -->|"writes and lists"| node_document_files
node_document_routes -->|"validates upload"| node_parsing
node_document_routes -->|"builds index"| node_vector_store
node_vector_store -->|"reads documents"| node_document_files
node_vector_store -->|"chunks text"| node_parsing
node_vector_store -->|"embeds chunks"| node_embeddings
node_vector_store -->|"writes and searches"| node_index_files
node_embeddings -->|"reads and writes"| node_embedding_cache
node_embeddings -->|"records cache"| node_metrics
node_search_routes -->|"retrieves chunks"| node_vector_store
node_search_routes -->|"generates answer"| node_llm
node_llm -->|"requests completion"| node_groq
node_search_routes -->|"logs model errors"| node_metrics

click node_app "https://github.com/yousif-gh/guidely/blob/main/frontend/src/App.jsx"
click node_search_ui "https://github.com/yousif-gh/guidely/blob/main/frontend/src/pages/SearchPage.jsx"
click node_source_list "https://github.com/yousif-gh/guidely/blob/main/frontend/src/components/SourceList.jsx"
click node_admin_ui "https://github.com/yousif-gh/guidely/blob/main/frontend/src/pages/AdminPage.jsx"
click node_server "https://github.com/yousif-gh/guidely/blob/main/backend/main.py"
click node_request_model "https://github.com/yousif-gh/guidely/blob/main/backend/models/record.py"
click node_document_routes "https://github.com/yousif-gh/guidely/blob/main/backend/routes/documents.py"
click node_search_routes "https://github.com/yousif-gh/guidely/blob/main/backend/routes/search.py"
click node_document_files "https://github.com/yousif-gh/guidely/tree/main/backend/data/sample-docs"
click node_parsing "https://github.com/yousif-gh/guidely/blob/main/backend/services/parsing.py"
click node_embeddings "https://github.com/yousif-gh/guidely/blob/main/backend/services/embeddings.py"
click node_vector_store "https://github.com/yousif-gh/guidely/blob/main/backend/services/vector_store.py"
click node_llm "https://github.com/yousif-gh/guidely/blob/main/backend/services/llm.py"
click node_metrics "https://github.com/yousif-gh/guidely/blob/main/backend/services/metrics.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_app,node_search_ui,node_source_list,node_admin_ui toneBlue
class node_server,node_request_model,node_document_routes,node_search_routes toneAmber
class node_document_files,node_parsing,node_embeddings,node_groq toneMint
class node_vector_store,node_llm toneRose
class node_index_files,node_embedding_cache,node_metrics,node_employee toneIndigo
```

## Components

### User interface

- [Page navigation](https://github.com/yousif-gh/guidely/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Ask and sources](https://github.com/yousif-gh/guidely/blob/main/frontend/src/pages/SearchPage.jsx): `frontend/src/pages/SearchPage.jsx`
- [Source display](https://github.com/yousif-gh/guidely/blob/main/frontend/src/components/SourceList.jsx): `frontend/src/components/SourceList.jsx`
- [Document admin](https://github.com/yousif-gh/guidely/blob/main/frontend/src/pages/AdminPage.jsx): `frontend/src/pages/AdminPage.jsx`

### API and workflows

- [FastAPI app](https://github.com/yousif-gh/guidely/blob/main/backend/main.py): `backend/main.py`
- [Search request](https://github.com/yousif-gh/guidely/blob/main/backend/models/record.py): `backend/models/record.py`
- [Document routes](https://github.com/yousif-gh/guidely/blob/main/backend/routes/documents.py): `backend/routes/documents.py`
- [Search and ask routes](https://github.com/yousif-gh/guidely/blob/main/backend/routes/search.py): `backend/routes/search.py`

### Document indexing

- [Text documents](https://github.com/yousif-gh/guidely/tree/main/backend/data/sample-docs): `backend/data/sample-docs`
- [Text parsing and chunks](https://github.com/yousif-gh/guidely/blob/main/backend/services/parsing.py): `backend/services/parsing.py`
- [Local embeddings](https://github.com/yousif-gh/guidely/blob/main/backend/services/embeddings.py): `backend/services/embeddings.py`

### Retrieval and answers

- [Vector indexing and retrieval](https://github.com/yousif-gh/guidely/blob/main/backend/services/vector_store.py): `backend/services/vector_store.py`
- [Answer generation](https://github.com/yousif-gh/guidely/blob/main/backend/services/llm.py): `backend/services/llm.py`

### State and metrics

- **FAISS index and chunks**
- **Embedding cache**
- [Request and cache metrics](https://github.com/yousif-gh/guidely/blob/main/backend/services/metrics.py): `backend/services/metrics.py`

### Other components

- **Employee**
- **Groq API**

## Connections

- Employee → Page navigation: uses (evidence: `frontend/src/App.jsx`)
- Page navigation → Ask and sources: renders (evidence: `frontend/src/App.jsx`)
- Page navigation → Document admin: renders (evidence: `frontend/src/App.jsx`)
- Ask and sources → Search and ask routes: submits question
- Ask and sources → Source display: renders sources (evidence: `frontend/src/pages/SearchPage.jsx`)
- Document admin → Document routes: manages documents
- FastAPI app → Document routes: registers (evidence: `backend/main.py`)
- FastAPI app → Search and ask routes: registers (evidence: `backend/main.py`)
- FastAPI app → Request and cache metrics: records requests (evidence: `backend/main.py`)
- FastAPI app → Request and cache metrics: reads snapshot (evidence: `backend/main.py`)
- FastAPI app → Vector indexing and retrieval: reads index state (evidence: `backend/main.py`)
- Search and ask routes → Search request: validates requests (evidence: `backend/routes/search.py`)
- Document routes → Text documents: writes and lists (evidence: `backend/routes/documents.py`)
- Document routes → Text parsing and chunks: validates upload (evidence: `backend/routes/documents.py`)
- Document routes → Vector indexing and retrieval: builds index (evidence: `backend/routes/documents.py`)
- Vector indexing and retrieval → Text documents: reads documents (evidence: `backend/services/vector_store.py`)
- Vector indexing and retrieval → Text parsing and chunks: chunks text (evidence: `backend/services/vector_store.py`)
- Vector indexing and retrieval → Local embeddings: embeds chunks (evidence: `backend/services/vector_store.py`)
- Vector indexing and retrieval → FAISS index and chunks: writes and searches (evidence: `backend/services/vector_store.py`)
- Local embeddings → Embedding cache: reads and writes (evidence: `backend/services/embeddings.py`)
- Local embeddings → Request and cache metrics: records cache (evidence: `backend/services/embeddings.py`)
- Search and ask routes → Vector indexing and retrieval: retrieves chunks (evidence: `backend/routes/search.py`)
- Search and ask routes → Answer generation: generates answer (evidence: `backend/routes/search.py`)
- Answer generation → Groq API: requests completion (evidence: `backend/services/llm.py`)
- Search and ask routes → Request and cache metrics: logs model errors (evidence: `backend/routes/search.py`)
