# sohan1625/own-your-ai architecture

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

- Interactive diagram: https://gitdiagram.com/sohan1625/own-your-ai
- Repository: https://github.com/sohan1625/own-your-ai

## Overview

Own Your Intelligence is a local PDF question-answering app. Users upload PDFs, choose documents, and ask questions through a web UI; the API extracts page text, chunks it, indexes it, retrieves and fuses passages, then generates a grounded answer and resolves citations. PostgreSQL stores documents, chunks, embeddings, and chat history; local Ollama supplies embeddings and generation. The retrieval and answer path is documented in the README, while several API internals are only partially excerpted, so uncertain call links are omitted or marked unverified.

Main entry points: [`src/api.py`](https://github.com/sohan1625/own-your-ai/blob/main/src/api.py) (FastAPI), [`src/db.py`](https://github.com/sohan1625/own-your-ai/blob/main/src/db.py) (Persistence access), [`src/retrieve.py`](https://github.com/sohan1625/own-your-ai/blob/main/src/retrieve.py) (Keyword and vector search), [`static/index.html`](https://github.com/sohan1625/own-your-ai/blob/main/static/index.html) (Web UI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["User interface"]
  node_webui["Web UI<br/>[index.html]"]
  node_api["FastAPI<br/>[api.py]"]
end

subgraph group_documents["Document indexing"]
  node_ingest["PDF extraction<br/>[ingest.py]"]
  node_chunk["Text chunking<br/>[chunk.py]"]
  node_index["BM25 and embeddings<br/>[index.py]"]
end

subgraph group_retrieval["Search and answers"]
  node_retrieve["Keyword and vector search<br/>[retrieve.py]"]
  node_fusion["Rank fusion<br/>[fuse.py]"]
  node_answer["Grounded generation<br/>[answer.py]"]
  node_cite["Citation resolution<br/>[cite.py]"]
end

subgraph group_persistence["Local persistence"]
  node_db["Persistence access<br/>[db.py]"]
  node_pg[("PostgreSQL pgvector")]
  node_cache["Answer cache<br/>[cache.py]"]
end

node_user(("User"))
node_ollama["Local Ollama"]

node_user -->|"uses"| node_webui
node_webui -.->|"requests"| node_api
node_api -->|"serves"| node_webui
node_api -->|"extracts PDFs"| node_ingest
node_api -->|"chunks pages"| node_chunk
node_api -->|"embeds chunks"| node_index
node_api -->|"stores documents"| node_db
node_db -->|"reads and writes"| node_pg
node_api -->|"retrieves passages"| node_retrieve
node_retrieve -->|"uses BM25 and embeddings"| node_index
node_api -->|"fuses rankings"| node_fusion
node_api -->|"generates answer"| node_answer
node_answer -->|"calls local model"| node_ollama
node_api -->|"resolves citations"| node_cite
node_api -.->|"checks and updates"| node_cache
node_index -->|"embeds text"| node_ollama
node_retrieve -.->|"searches stored vectors"| node_db
node_api -->|"loads chat history"| node_db

click node_webui "https://github.com/sohan1625/own-your-ai/blob/main/static/index.html"
click node_api "https://github.com/sohan1625/own-your-ai/blob/main/src/api.py"
click node_ingest "https://github.com/sohan1625/own-your-ai/blob/main/src/ingest.py"
click node_chunk "https://github.com/sohan1625/own-your-ai/blob/main/src/chunk.py"
click node_index "https://github.com/sohan1625/own-your-ai/blob/main/src/index.py"
click node_db "https://github.com/sohan1625/own-your-ai/blob/main/src/db.py"
click node_cache "https://github.com/sohan1625/own-your-ai/blob/main/src/cache.py"
click node_retrieve "https://github.com/sohan1625/own-your-ai/blob/main/src/retrieve.py"
click node_fusion "https://github.com/sohan1625/own-your-ai/blob/main/src/fuse.py"
click node_answer "https://github.com/sohan1625/own-your-ai/blob/main/src/answer.py"
click node_cite "https://github.com/sohan1625/own-your-ai/blob/main/src/cite.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_webui,node_api,node_user toneBlue
class node_ingest,node_chunk,node_index toneAmber
class node_retrieve,node_fusion,node_answer,node_cite toneMint
class node_db,node_pg,node_cache toneRose
class node_ollama toneIndigo
```

## Components

### User interface

- [Web UI](https://github.com/sohan1625/own-your-ai/blob/main/static/index.html): `static/index.html`
- [FastAPI](https://github.com/sohan1625/own-your-ai/blob/main/src/api.py): `src/api.py`

### Document indexing

- [PDF extraction](https://github.com/sohan1625/own-your-ai/blob/main/src/ingest.py): `src/ingest.py`
- [Text chunking](https://github.com/sohan1625/own-your-ai/blob/main/src/chunk.py): `src/chunk.py`
- [BM25 and embeddings](https://github.com/sohan1625/own-your-ai/blob/main/src/index.py): `src/index.py`

### Search and answers

- [Keyword and vector search](https://github.com/sohan1625/own-your-ai/blob/main/src/retrieve.py): `src/retrieve.py`
- [Rank fusion](https://github.com/sohan1625/own-your-ai/blob/main/src/fuse.py): `src/fuse.py`
- [Grounded generation](https://github.com/sohan1625/own-your-ai/blob/main/src/answer.py): `src/answer.py`
- [Citation resolution](https://github.com/sohan1625/own-your-ai/blob/main/src/cite.py): `src/cite.py`

### Local persistence

- [Persistence access](https://github.com/sohan1625/own-your-ai/blob/main/src/db.py): `src/db.py`
- **PostgreSQL pgvector**
- [Answer cache](https://github.com/sohan1625/own-your-ai/blob/main/src/cache.py): `src/cache.py`

### Other components

- **User**
- **Local Ollama**

## Connections

- User → Web UI: uses (evidence: `README.md`)
- Web UI → FastAPI: requests
- FastAPI → Web UI: serves (evidence: `src/api.py`)
- FastAPI → PDF extraction: extracts PDFs (evidence: `README.md`)
- FastAPI → Text chunking: chunks pages (evidence: `src/api.py`)
- FastAPI → BM25 and embeddings: embeds chunks (evidence: `src/api.py`)
- FastAPI → Persistence access: stores documents (evidence: `src/api.py`)
- Persistence access → PostgreSQL pgvector: reads and writes (evidence: `src/db.py`)
- FastAPI → Keyword and vector search: retrieves passages (evidence: `README.md`)
- Keyword and vector search → BM25 and embeddings: uses BM25 and embeddings (evidence: `src/retrieve.py`)
- FastAPI → Rank fusion: fuses rankings (evidence: `README.md`)
- FastAPI → Grounded generation: generates answer (evidence: `README.md`)
- Grounded generation → Local Ollama: calls local model (evidence: `README.md`)
- FastAPI → Citation resolution: resolves citations (evidence: `README.md`)
- FastAPI → Answer cache: checks and updates (evidence: `src/api.py`)
- BM25 and embeddings → Local Ollama: embeds text (evidence: `src/index.py`)
- Keyword and vector search → Persistence access: searches stored vectors
- FastAPI → Persistence access: loads chat history (evidence: `README.md`)
