# umr-se/knowflow architecture

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

- Interactive diagram: https://gitdiagram.com/umr-se/knowflow
- Repository: https://github.com/umr-se/knowflow

## Overview

KnowFlow is a local document-chat application: users upload supported files, ask questions, and receive answers grounded in retrieved passages with citations, or a general local-model response when retrieval finds no useful context. The graph follows the visible frontend-to-API workflow through ingestion and RAG, and includes conversation history and document management. README capabilities such as health/model status and broad file-format support are represented; implementation wiring beyond the supplied excerpts is omitted where uncertain.

Main entry points: [`backend/app/db.py`](https://github.com/umr-se/knowflow/blob/main/backend/app/db.py) (Database access), [`backend/app/main.py`](https://github.com/umr-se/knowflow/blob/main/backend/app/main.py) (API application), [`backend/app/api/documents.py`](https://github.com/umr-se/knowflow/blob/main/backend/app/api/documents.py) (Document endpoints), [`backend/app/api/chat.py`](https://github.com/umr-se/knowflow/blob/main/backend/app/api/chat.py) (Chat endpoint)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["User interface"]
  node_dashboard["Knowledge dashboard<br/>[Dashboard.tsx]"]
  node_page["App page<br/>[page.tsx]"]
end

subgraph group_api["FastAPI endpoints"]
  node_main["API application<br/>[main.py]"]
  node_documents_api["Document endpoints<br/>[documents.py]"]
  node_chat_api["Chat endpoint<br/>[chat.py]"]
  node_conversations_api["Conversation endpoints<br/>[conversations.py]"]
end

subgraph group_rag["Document and RAG services"]
  node_ingestion["File extraction<br/>[ingestion.py]"]
  node_chunking["Text chunking<br/>[chunking.py]"]
  node_embeddings["Embedding generation<br/>[embeddings.py]"]
  node_retrieval["Vector retrieval<br/>[retrieval.py]"]
  node_llm["Answer generation<br/>[llm.py]"]
end

subgraph group_state["Persistence and models"]
  node_db_access["Database access<br/>[db.py]"]
  node_postgres[("PostgreSQL pgvector")]
  node_ollama["Ollama local model"]
  node_embedding_model["MiniLM model"]
end

node_user(("User"))

node_user -->|"uses"| node_dashboard
node_page -->|"renders"| node_dashboard
node_dashboard -->|"uploads, lists, deletes"| node_documents_api
node_dashboard -->|"asks questions"| node_chat_api
node_main -->|"registers"| node_documents_api
node_main -->|"registers"| node_chat_api
node_main -->|"registers"| node_conversations_api
node_main -->|"initializes schema"| node_db_access
node_documents_api -->|"extracts and chunks"| node_ingestion
node_ingestion -->|"splits text"| node_chunking
node_documents_api -->|"embeds chunks"| node_embeddings
node_documents_api -->|"stores and manages"| node_db_access
node_chat_api -->|"loads and saves history"| node_db_access
node_chat_api -->|"retrieves context"| node_retrieval
node_retrieval -->|"embeds query"| node_embeddings
node_retrieval -->|"queries chunks"| node_db_access
node_chat_api -->|"generates answer"| node_llm
node_llm -->|"sends prompt"| node_ollama
node_embeddings -->|"encodes text"| node_embedding_model
node_db_access -->|"reads and writes"| node_postgres
node_conversations_api -->|"reads conversations"| node_db_access
node_main -->|"checks model health"| node_llm

click node_dashboard "https://github.com/umr-se/knowflow/blob/main/frontend/components/Dashboard.tsx"
click node_page "https://github.com/umr-se/knowflow/blob/main/frontend/app/page.tsx"
click node_main "https://github.com/umr-se/knowflow/blob/main/backend/app/main.py"
click node_documents_api "https://github.com/umr-se/knowflow/blob/main/backend/app/api/documents.py"
click node_chat_api "https://github.com/umr-se/knowflow/blob/main/backend/app/api/chat.py"
click node_conversations_api "https://github.com/umr-se/knowflow/blob/main/backend/app/api/conversations.py"
click node_ingestion "https://github.com/umr-se/knowflow/blob/main/backend/app/services/ingestion.py"
click node_chunking "https://github.com/umr-se/knowflow/blob/main/backend/app/services/chunking.py"
click node_embeddings "https://github.com/umr-se/knowflow/blob/main/backend/app/services/embeddings.py"
click node_retrieval "https://github.com/umr-se/knowflow/blob/main/backend/app/services/retrieval.py"
click node_llm "https://github.com/umr-se/knowflow/blob/main/backend/app/services/llm.py"
click node_db_access "https://github.com/umr-se/knowflow/blob/main/backend/app/db.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_dashboard,node_page,node_user toneBlue
class node_main,node_documents_api,node_chat_api,node_conversations_api toneAmber
class node_ingestion,node_chunking,node_embeddings,node_retrieval,node_llm toneMint
class node_db_access,node_postgres,node_ollama,node_embedding_model toneRose
```

## Components

### User interface

- [Knowledge dashboard](https://github.com/umr-se/knowflow/blob/main/frontend/components/Dashboard.tsx): `frontend/components/Dashboard.tsx`
- [App page](https://github.com/umr-se/knowflow/blob/main/frontend/app/page.tsx): `frontend/app/page.tsx`

### FastAPI endpoints

- [API application](https://github.com/umr-se/knowflow/blob/main/backend/app/main.py): `backend/app/main.py`
- [Document endpoints](https://github.com/umr-se/knowflow/blob/main/backend/app/api/documents.py): `backend/app/api/documents.py`
- [Chat endpoint](https://github.com/umr-se/knowflow/blob/main/backend/app/api/chat.py): `backend/app/api/chat.py`
- [Conversation endpoints](https://github.com/umr-se/knowflow/blob/main/backend/app/api/conversations.py): `backend/app/api/conversations.py`

### Document and RAG services

- [File extraction](https://github.com/umr-se/knowflow/blob/main/backend/app/services/ingestion.py): `backend/app/services/ingestion.py`
- [Text chunking](https://github.com/umr-se/knowflow/blob/main/backend/app/services/chunking.py): `backend/app/services/chunking.py`
- [Embedding generation](https://github.com/umr-se/knowflow/blob/main/backend/app/services/embeddings.py): `backend/app/services/embeddings.py`
- [Vector retrieval](https://github.com/umr-se/knowflow/blob/main/backend/app/services/retrieval.py): `backend/app/services/retrieval.py`
- [Answer generation](https://github.com/umr-se/knowflow/blob/main/backend/app/services/llm.py): `backend/app/services/llm.py`

### Persistence and models

- [Database access](https://github.com/umr-se/knowflow/blob/main/backend/app/db.py): `backend/app/db.py`
- **PostgreSQL pgvector**
- **Ollama local model**
- **MiniLM model**

### Other components

- **User**

## Connections

- User → Knowledge dashboard: uses
- App page → Knowledge dashboard: renders
- Knowledge dashboard → Document endpoints: uploads, lists, deletes
- Knowledge dashboard → Chat endpoint: asks questions
- API application → Document endpoints: registers
- API application → Chat endpoint: registers
- API application → Conversation endpoints: registers
- API application → Database access: initializes schema
- Document endpoints → File extraction: extracts and chunks
- File extraction → Text chunking: splits text
- Document endpoints → Embedding generation: embeds chunks
- Document endpoints → Database access: stores and manages
- Chat endpoint → Database access: loads and saves history
- Chat endpoint → Vector retrieval: retrieves context
- Vector retrieval → Embedding generation: embeds query
- Vector retrieval → Database access: queries chunks
- Chat endpoint → Answer generation: generates answer
- Answer generation → Ollama local model: sends prompt
- Embedding generation → MiniLM model: encodes text
- Database access → PostgreSQL pgvector: reads and writes
- Conversation endpoints → Database access: reads conversations
- API application → Answer generation: checks model health