# geek007git/hogyoku-oss architecture

> Architecture diagram of the GitHub repository geek007git/hogyoku-oss, 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/geek007git/hogyoku-oss
- Repository: https://github.com/geek007git/hogyoku-oss

## Overview

Hogyoku is a self-hosted, multimodal RAG workspace: users upload private documents, ask questions in managed threads, and receive cited answers whose claims are independently checked before presentation. The documented lifecycle and sampled routes show upload-to-background-ingestion and ask-to-retrieval-to-verification. The graph also preserves the documented browser workspace and offline Python guardrails. Several capabilities, including parsing/OCR internals and answer verification, are documented but not excerpted; their subsystem paths are therefore exact enclosing directories, and uncertain implementation links are omitted.

Main entry points: [`src/services/ingestion.ts`](https://github.com/geek007git/hogyoku-oss/blob/main/src/services/ingestion.ts) (Document ingestion), [`src/http/threads.ts`](https://github.com/geek007git/hogyoku-oss/blob/main/src/http/threads.ts) (Thread routes), [`src/app.ts`](https://github.com/geek007git/hogyoku-oss/blob/main/src/app.ts) (Fastify API), [`src/services/ai.ts`](https://github.com/geek007git/hogyoku-oss/blob/main/src/services/ai.ts) (Model and embeddings)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Workspace and API"]
  node_browser["Browser workspace<br/>[app.js]"]
  node_api["Fastify API<br/>[app.ts]"]
  node_auth["Accounts and sessions<br/>[auth.ts]"]
  node_documents["Document routes<br/>[documents.ts]"]
  node_threads["Thread routes<br/>[threads.ts]"]
  node_server["Web server<br/>[server.ts]"]
end

subgraph group_ingest["Document ingestion"]
  node_queue["Ingestion queue<br/>[queue.ts]"]
  node_worker["Ingestion worker<br/>[worker.ts]"]
  node_ingestion["Document ingestion<br/>[ingestion.ts]"]
  node_extraction["Extraction and OCR"]
  node_chunking["Page-aware chunking<br/>[chunking.ts]"]
end

subgraph group_research["Conversational RAG"]
  node_conversation["Query rewriting<br/>[conversation.ts]"]
  node_retrieval["Hybrid retrieval<br/>[retrieval.ts]"]
  node_answers["Grounded verification<br/>[answers.ts]"]
end

subgraph group_infra["Persistence and providers"]
  node_ai["Model and embeddings<br/>[ai.ts]"]
  node_database[("PostgreSQL and pgvector<br/>[client.ts]")]
  node_storage[("Private object storage<br/>[storage.ts]")]
  node_redis[("Redis")]
  node_gemini["Google Gemini"]
end

subgraph group_guardrails["Offline guardrails"]
  node_guardrail_common["Guardrail utilities<br/>[common.py]"]
  node_citation_audit["Citation audit<br/>[citation_audit.py]"]
  node_chunk_audit["Chunk audit<br/>[chunk_audit.py]"]
  node_rag_lint["RAG lint<br/>[rag_lint.py]"]
  node_security_scan["Security scanning<br/>[security_scan.py]"]
  node_security_report["Security report<br/>[security_report.py]"]
end

node_user(("Workspace user"))

node_user -->|"uses"| node_browser
node_browser -.->|"calls API"| node_api
node_server -->|"starts"| node_api
node_api -->|"registers routes"| node_auth
node_api -->|"registers routes"| node_documents
node_api -->|"registers routes"| node_threads
node_documents -->|"uploads files"| node_storage
node_documents -->|"enqueues jobs"| node_queue
node_server -->|"ensures bucket"| node_storage
node_worker -->|"consumes jobs"| node_queue
node_worker -->|"invokes"| node_ingestion
node_ingestion -->|"reads and writes"| node_database
node_ingestion -->|"downloads object"| node_storage
node_ingestion -->|"extracts pages"| node_extraction
node_ingestion -->|"chunks pages"| node_chunking
node_ingestion -->|"embeds chunks"| node_ai
node_threads -->|"rewrites query"| node_conversation
node_threads -->|"retrieves evidence"| node_retrieval
node_threads -->|"requests answer"| node_answers
node_threads -->|"reads and saves turns"| node_database
node_retrieval -->|"embeds query"| node_ai
node_retrieval -->|"searches indexed chunks"| node_database
node_answers -->|"uses evidence"| node_retrieval
node_answers -->|"uses history"| node_conversation
node_answers -->|"generates and checks"| node_ai
node_ai -->|"calls when configured"| node_gemini
node_ai -.->|"embeds remotely"| node_gemini
node_citation_audit -->|"uses helpers"| node_guardrail_common
node_chunk_audit -->|"uses helpers"| node_guardrail_common
node_rag_lint -->|"uses helpers"| node_guardrail_common
node_security_scan -->|"uses helpers"| node_guardrail_common
node_security_report -->|"uses helpers"| node_guardrail_common
node_queue -.->|"stores jobs"| node_redis

click node_browser "https://github.com/geek007git/hogyoku-oss/blob/main/public/app.js"
click node_api "https://github.com/geek007git/hogyoku-oss/blob/main/src/app.ts"
click node_auth "https://github.com/geek007git/hogyoku-oss/blob/main/src/http/auth.ts"
click node_documents "https://github.com/geek007git/hogyoku-oss/blob/main/src/http/documents.ts"
click node_threads "https://github.com/geek007git/hogyoku-oss/blob/main/src/http/threads.ts"
click node_server "https://github.com/geek007git/hogyoku-oss/blob/main/src/server.ts"
click node_queue "https://github.com/geek007git/hogyoku-oss/blob/main/src/lib/queue.ts"
click node_worker "https://github.com/geek007git/hogyoku-oss/blob/main/src/worker.ts"
click node_ingestion "https://github.com/geek007git/hogyoku-oss/blob/main/src/services/ingestion.ts"
click node_extraction "https://github.com/geek007git/hogyoku-oss/tree/main/src/services"
click node_chunking "https://github.com/geek007git/hogyoku-oss/blob/main/src/lib/chunking.ts"
click node_conversation "https://github.com/geek007git/hogyoku-oss/blob/main/src/services/conversation.ts"
click node_retrieval "https://github.com/geek007git/hogyoku-oss/blob/main/src/services/retrieval.ts"
click node_answers "https://github.com/geek007git/hogyoku-oss/blob/main/src/services/answers.ts"
click node_ai "https://github.com/geek007git/hogyoku-oss/blob/main/src/services/ai.ts"
click node_database "https://github.com/geek007git/hogyoku-oss/blob/main/src/db/client.ts"
click node_storage "https://github.com/geek007git/hogyoku-oss/blob/main/src/lib/storage.ts"
click node_guardrail_common "https://github.com/geek007git/hogyoku-oss/blob/main/python/hogyoku_guardrails/common.py"
click node_citation_audit "https://github.com/geek007git/hogyoku-oss/blob/main/python/hogyoku_guardrails/citation_audit.py"
click node_chunk_audit "https://github.com/geek007git/hogyoku-oss/blob/main/python/hogyoku_guardrails/chunk_audit.py"
click node_rag_lint "https://github.com/geek007git/hogyoku-oss/blob/main/python/hogyoku_guardrails/rag_lint.py"
click node_security_scan "https://github.com/geek007git/hogyoku-oss/blob/main/python/hogyoku_guardrails/security_scan.py"
click node_security_report "https://github.com/geek007git/hogyoku-oss/blob/main/python/hogyoku_guardrails/security_report.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_browser,node_api,node_auth,node_documents,node_threads,node_server,node_user toneBlue
class node_queue,node_worker,node_ingestion,node_extraction,node_chunking toneAmber
class node_conversation,node_retrieval,node_answers toneMint
class node_ai,node_database,node_storage,node_redis,node_gemini toneRose
class node_guardrail_common,node_citation_audit,node_chunk_audit,node_rag_lint,node_security_scan,node_security_report toneIndigo
```

## Components

### Workspace and API

- [Browser workspace](https://github.com/geek007git/hogyoku-oss/blob/main/public/app.js): `public/app.js`
- [Fastify API](https://github.com/geek007git/hogyoku-oss/blob/main/src/app.ts): `src/app.ts`
- [Accounts and sessions](https://github.com/geek007git/hogyoku-oss/blob/main/src/http/auth.ts): `src/http/auth.ts`
- [Document routes](https://github.com/geek007git/hogyoku-oss/blob/main/src/http/documents.ts): `src/http/documents.ts`
- [Thread routes](https://github.com/geek007git/hogyoku-oss/blob/main/src/http/threads.ts): `src/http/threads.ts`
- [Web server](https://github.com/geek007git/hogyoku-oss/blob/main/src/server.ts): `src/server.ts`

### Document ingestion

- [Ingestion queue](https://github.com/geek007git/hogyoku-oss/blob/main/src/lib/queue.ts): `src/lib/queue.ts`
- [Ingestion worker](https://github.com/geek007git/hogyoku-oss/blob/main/src/worker.ts): `src/worker.ts`
- [Document ingestion](https://github.com/geek007git/hogyoku-oss/blob/main/src/services/ingestion.ts): `src/services/ingestion.ts`
- [Extraction and OCR](https://github.com/geek007git/hogyoku-oss/tree/main/src/services): `src/services`
- [Page-aware chunking](https://github.com/geek007git/hogyoku-oss/blob/main/src/lib/chunking.ts): `src/lib/chunking.ts`

### Conversational RAG

- [Query rewriting](https://github.com/geek007git/hogyoku-oss/blob/main/src/services/conversation.ts): `src/services/conversation.ts`
- [Hybrid retrieval](https://github.com/geek007git/hogyoku-oss/blob/main/src/services/retrieval.ts): `src/services/retrieval.ts`
- [Grounded verification](https://github.com/geek007git/hogyoku-oss/blob/main/src/services/answers.ts): `src/services/answers.ts`

### Persistence and providers

- [Model and embeddings](https://github.com/geek007git/hogyoku-oss/blob/main/src/services/ai.ts): `src/services/ai.ts`
- [PostgreSQL and pgvector](https://github.com/geek007git/hogyoku-oss/blob/main/src/db/client.ts): `src/db/client.ts`
- [Private object storage](https://github.com/geek007git/hogyoku-oss/blob/main/src/lib/storage.ts): `src/lib/storage.ts`
- **Redis**
- **Google Gemini**

### Offline guardrails

- [Guardrail utilities](https://github.com/geek007git/hogyoku-oss/blob/main/python/hogyoku_guardrails/common.py): `python/hogyoku_guardrails/common.py`
- [Citation audit](https://github.com/geek007git/hogyoku-oss/blob/main/python/hogyoku_guardrails/citation_audit.py): `python/hogyoku_guardrails/citation_audit.py`
- [Chunk audit](https://github.com/geek007git/hogyoku-oss/blob/main/python/hogyoku_guardrails/chunk_audit.py): `python/hogyoku_guardrails/chunk_audit.py`
- [RAG lint](https://github.com/geek007git/hogyoku-oss/blob/main/python/hogyoku_guardrails/rag_lint.py): `python/hogyoku_guardrails/rag_lint.py`
- [Security scanning](https://github.com/geek007git/hogyoku-oss/blob/main/python/hogyoku_guardrails/security_scan.py): `python/hogyoku_guardrails/security_scan.py`
- [Security report](https://github.com/geek007git/hogyoku-oss/blob/main/python/hogyoku_guardrails/security_report.py): `python/hogyoku_guardrails/security_report.py`

### Other components

- **Workspace user**

## Connections

- Workspace user → Browser workspace: uses (evidence: `README.md`)
- Browser workspace → Fastify API: calls API
- Web server → Fastify API: starts (evidence: `src/server.ts`)
- Fastify API → Accounts and sessions: registers routes (evidence: `src/app.ts`)
- Fastify API → Document routes: registers routes (evidence: `src/app.ts`)
- Fastify API → Thread routes: registers routes (evidence: `src/app.ts`)
- Document routes → Private object storage: uploads files (evidence: `src/http/documents.ts`)
- Document routes → Ingestion queue: enqueues jobs (evidence: `src/http/documents.ts`)
- Web server → Private object storage: ensures bucket (evidence: `src/server.ts`)
- Ingestion worker → Ingestion queue: consumes jobs (evidence: `src/worker.ts`)
- Ingestion worker → Document ingestion: invokes (evidence: `src/worker.ts`)
- Document ingestion → PostgreSQL and pgvector: reads and writes (evidence: `src/services/ingestion.ts`)
- Document ingestion → Private object storage: downloads object (evidence: `src/services/ingestion.ts`)
- Document ingestion → Extraction and OCR: extracts pages (evidence: `src/services/ingestion.ts`)
- Document ingestion → Page-aware chunking: chunks pages (evidence: `src/services/ingestion.ts`)
- Document ingestion → Model and embeddings: embeds chunks (evidence: `src/services/ingestion.ts`)
- Thread routes → Query rewriting: rewrites query (evidence: `src/http/threads.ts`)
- Thread routes → Hybrid retrieval: retrieves evidence (evidence: `src/http/threads.ts`)
- Thread routes → Grounded verification: requests answer (evidence: `src/http/threads.ts`)
- Thread routes → PostgreSQL and pgvector: reads and saves turns (evidence: `src/http/threads.ts`)
- Hybrid retrieval → Model and embeddings: embeds query (evidence: `src/services/retrieval.ts`)
- Hybrid retrieval → PostgreSQL and pgvector: searches indexed chunks (evidence: `src/services/retrieval.ts`)
- Grounded verification → Hybrid retrieval: uses evidence (evidence: `src/services/answers.ts`)
- Grounded verification → Query rewriting: uses history (evidence: `src/services/answers.ts`)
- Grounded verification → Model and embeddings: generates and checks (evidence: `src/services/answers.ts`)
- Model and embeddings → Google Gemini: calls when configured (evidence: `src/services/ai.ts`)
- Model and embeddings → Google Gemini: embeds remotely (evidence: `src/services/ai.ts`)
- Citation audit → Guardrail utilities: uses helpers (evidence: `python/hogyoku_guardrails/citation_audit.py`)
- Chunk audit → Guardrail utilities: uses helpers (evidence: `python/hogyoku_guardrails/chunk_audit.py`)
- RAG lint → Guardrail utilities: uses helpers (evidence: `python/hogyoku_guardrails/rag_lint.py`)
- Security scanning → Guardrail utilities: uses helpers (evidence: `python/hogyoku_guardrails/security_scan.py`)
- Security report → Guardrail utilities: uses helpers (evidence: `python/hogyoku_guardrails/security_report.py`)
- Ingestion queue → Redis: stores jobs