# hongweihsu/dev-atlas architecture

> Architecture diagram of the GitHub repository hongweihsu/dev-atlas, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/hongweihsu/dev-atlas
- Repository: https://github.com/hongweihsu/dev-atlas

## Overview

Retrieval Works is a permission-aware technical knowledge and research platform. Users authenticate, select an authorized workspace and knowledge base, ingest documents asynchronously, and then search or ask questions grounded in retrieved, versioned sources. The API also supports conversations, corrective answers, tool-based workspace questions, agentic research, and document lifecycle management. The graph combines sampled wiring and calls with capabilities documented in the README; unsampled implementation links are included only where documented, and evaluation internals are omitted.

Main entry points: [`apps/api/src/retrieval_works/api/router.py`](https://github.com/hongweihsu/dev-atlas/blob/main/apps/api/src/retrieval_works/api/router.py) (API routes), [`apps/web/src/App.tsx`](https://github.com/hongweihsu/dev-atlas/blob/main/apps/web/src/App.tsx) (Research workspace), [`apps/api/src/retrieval_works/application/ingest_document.py`](https://github.com/hongweihsu/dev-atlas/blob/main/apps/api/src/retrieval_works/application/ingest_document.py) (Document preparation), [`apps/api/src/retrieval_works/application/search_documents.py`](https://github.com/hongweihsu/dev-atlas/blob/main/apps/api/src/retrieval_works/application/search_documents.py) (Hybrid search)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web experience"]
  node_webapp["Research workspace<br/>[App.tsx]"]
  node_webapi["API client<br/>[api.ts]"]
  node_authui["Sign-in UI<br/>[AuthPanel.tsx]"]
  node_workspaceui["Workspace controls"]
end

subgraph group_access["Identity and scope"]
  node_authz["Authentication and access<br/>[authentication.py]"]
  node_workspace["Workspace management<br/>[workspaces.py]"]
end

subgraph group_knowledge["Knowledge workflows"]
  node_knowledgebase["Knowledge-base management<br/>[knowledge_bases.py]"]
  node_ingestapi["Ingestion job API<br/>[ingestion_jobs.py]"]
  node_jobservice["Job management"]
  node_worker["Ingestion worker<br/>[worker.py]"]
  node_ingestion["Document preparation<br/>[ingest_document.py]"]
  node_domain["Normalize and chunk"]
  node_embedding["Embedding provider<br/>[openai.py]"]
  node_embeddingport["Embedding contract<br/>[embedding.py]"]
end

subgraph group_runtime["API and persistence"]
  node_api["FastAPI service<br/>[main.py]"]
  node_routes["API routes<br/>[router.py]"]
  node_jobstore[("Job persistence<br/>[ingestion_jobs.py]")]
  node_docstore[("Document persistence<br/>[repository.py]")]
  node_metrics["Observability<br/>[observability.py]"]
end

subgraph group_research["Research capabilities"]
  node_retrieval["Hybrid search"]
  node_answers["Grounded answers<br/>[answers.py]"]
  node_researchapi["Research and tools<br/>[research.py]"]
  node_conversation["Conversation memory"]
end

node_user(("Platform user"))
node_postgres[("PostgreSQL")]
node_redis["Redis queue"]
node_openai["OpenAI services"]
node_cognito["Cognito identity"]

node_user -->|"uses"| node_webapp
node_webapp -->|"requests"| node_webapi
node_webapp -->|"renders"| node_authui
node_webapp -->|"renders"| node_workspaceui
node_webapi -->|"calls"| node_api
node_api -->|"mounts"| node_routes
node_routes -->|"authorizes"| node_authz
node_authz -.->|"verifies tokens"| node_cognito
node_authz -.->|"resolves membership"| node_postgres
node_routes -->|"routes workspace actions"| node_workspace
node_routes -->|"routes scope actions"| node_knowledgebase
node_routes -->|"routes job actions"| node_ingestapi
node_ingestapi -->|"submits jobs"| node_jobservice
node_jobservice -->|"creates or reads"| node_jobstore
node_jobstore -->|"persists jobs"| node_postgres
node_jobstore -.->|"dispatches jobs"| node_redis
node_redis -.->|"delivers jobs"| node_worker
node_worker -->|"runs ingestion"| node_ingestion
node_ingestion -->|"prepares text"| node_domain
node_ingestion -->|"requests vectors"| node_embeddingport
node_embedding -->|"implements"| node_embeddingport
node_embedding -.->|"requests embeddings"| node_openai
node_ingestion -.->|"persists chunks"| node_docstore
node_docstore -.->|"stores documents"| node_postgres
node_routes -->|"routes search"| node_retrieval
node_routes -->|"routes answers"| node_answers
node_routes -->|"routes research"| node_researchapi
node_routes -->|"routes conversations"| node_conversation
node_retrieval -.->|"searches chunks"| node_postgres
node_answers -.->|"grounds answers"| node_retrieval
node_researchapi -.->|"searches authorized scope"| node_retrieval
node_conversation -.->|"stores turns"| node_postgres
node_api -.->|"records outcomes"| node_metrics

click node_webapp "https://github.com/hongweihsu/dev-atlas/blob/main/apps/web/src/App.tsx"
click node_webapi "https://github.com/hongweihsu/dev-atlas/blob/main/apps/web/src/api.ts"
click node_authui "https://github.com/hongweihsu/dev-atlas/blob/main/apps/web/src/AuthPanel.tsx"
click node_workspaceui "https://github.com/hongweihsu/dev-atlas/blob/main/apps/web/src/WorkspaceControls.tsx"
click node_api "https://github.com/hongweihsu/dev-atlas/blob/main/apps/api/src/retrieval_works/main.py"
click node_routes "https://github.com/hongweihsu/dev-atlas/blob/main/apps/api/src/retrieval_works/api/router.py"
click node_authz "https://github.com/hongweihsu/dev-atlas/blob/main/apps/api/src/retrieval_works/api/dependencies/authentication.py"
click node_workspace "https://github.com/hongweihsu/dev-atlas/blob/main/apps/api/src/retrieval_works/api/routes/workspaces.py"
click node_knowledgebase "https://github.com/hongweihsu/dev-atlas/blob/main/apps/api/src/retrieval_works/api/routes/knowledge_bases.py"
click node_ingestapi "https://github.com/hongweihsu/dev-atlas/blob/main/apps/api/src/retrieval_works/api/routes/ingestion_jobs.py"
click node_jobservice "https://github.com/hongweihsu/dev-atlas/blob/main/apps/api/src/retrieval_works/application/manage_ingestion_jobs.py"
click node_jobstore "https://github.com/hongweihsu/dev-atlas/blob/main/apps/api/src/retrieval_works/infrastructure/persistence/ingestion_jobs.py"
click node_worker "https://github.com/hongweihsu/dev-atlas/blob/main/apps/api/src/retrieval_works/worker.py"
click node_ingestion "https://github.com/hongweihsu/dev-atlas/blob/main/apps/api/src/retrieval_works/application/ingest_document.py"
click node_domain "https://github.com/hongweihsu/dev-atlas/blob/main/apps/api/src/retrieval_works/domain/document_ingestion.py"
click node_embedding "https://github.com/hongweihsu/dev-atlas/blob/main/apps/api/src/retrieval_works/infrastructure/embedding/openai.py"
click node_embeddingport "https://github.com/hongweihsu/dev-atlas/blob/main/apps/api/src/retrieval_works/application/ports/embedding.py"
click node_docstore "https://github.com/hongweihsu/dev-atlas/blob/main/apps/api/src/retrieval_works/infrastructure/persistence/repository.py"
click node_retrieval "https://github.com/hongweihsu/dev-atlas/blob/main/apps/api/src/retrieval_works/application/search_documents.py"
click node_answers "https://github.com/hongweihsu/dev-atlas/blob/main/apps/api/src/retrieval_works/api/routes/answers.py"
click node_researchapi "https://github.com/hongweihsu/dev-atlas/blob/main/apps/api/src/retrieval_works/api/routes/research.py"
click node_conversation "https://github.com/hongweihsu/dev-atlas/blob/main/apps/api/src/retrieval_works/application/manage_conversations.py"
click node_metrics "https://github.com/hongweihsu/dev-atlas/blob/main/apps/api/src/retrieval_works/infrastructure/observability.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_webapp,node_webapi,node_authui,node_workspaceui,node_user toneBlue
class node_authz,node_workspace,node_postgres,node_redis toneAmber
class node_knowledgebase,node_ingestapi,node_jobservice,node_worker,node_ingestion,node_domain,node_embedding,node_embeddingport toneMint
class node_api,node_routes,node_jobstore,node_docstore,node_metrics toneRose
class node_retrieval,node_answers,node_researchapi,node_conversation,node_openai,node_cognito toneIndigo
```

## Components

### Web experience

- [Research workspace](https://github.com/hongweihsu/dev-atlas/blob/main/apps/web/src/App.tsx): `apps/web/src/App.tsx`
- [API client](https://github.com/hongweihsu/dev-atlas/blob/main/apps/web/src/api.ts): `apps/web/src/api.ts`
- [Sign-in UI](https://github.com/hongweihsu/dev-atlas/blob/main/apps/web/src/AuthPanel.tsx): `apps/web/src/AuthPanel.tsx`
- [Workspace controls](https://github.com/hongweihsu/dev-atlas/blob/main/apps/web/src/WorkspaceControls.tsx): `apps/web/src/WorkspaceControls.tsx`

### Identity and scope

- [Authentication and access](https://github.com/hongweihsu/dev-atlas/blob/main/apps/api/src/retrieval_works/api/dependencies/authentication.py): `apps/api/src/retrieval_works/api/dependencies/authentication.py`
- [Workspace management](https://github.com/hongweihsu/dev-atlas/blob/main/apps/api/src/retrieval_works/api/routes/workspaces.py): `apps/api/src/retrieval_works/api/routes/workspaces.py`

### Knowledge workflows

- [Knowledge-base management](https://github.com/hongweihsu/dev-atlas/blob/main/apps/api/src/retrieval_works/api/routes/knowledge_bases.py): `apps/api/src/retrieval_works/api/routes/knowledge_bases.py`
- [Ingestion job API](https://github.com/hongweihsu/dev-atlas/blob/main/apps/api/src/retrieval_works/api/routes/ingestion_jobs.py): `apps/api/src/retrieval_works/api/routes/ingestion_jobs.py`
- [Job management](https://github.com/hongweihsu/dev-atlas/blob/main/apps/api/src/retrieval_works/application/manage_ingestion_jobs.py): `apps/api/src/retrieval_works/application/manage_ingestion_jobs.py`
- [Ingestion worker](https://github.com/hongweihsu/dev-atlas/blob/main/apps/api/src/retrieval_works/worker.py): `apps/api/src/retrieval_works/worker.py`
- [Document preparation](https://github.com/hongweihsu/dev-atlas/blob/main/apps/api/src/retrieval_works/application/ingest_document.py): `apps/api/src/retrieval_works/application/ingest_document.py`
- [Normalize and chunk](https://github.com/hongweihsu/dev-atlas/blob/main/apps/api/src/retrieval_works/domain/document_ingestion.py): `apps/api/src/retrieval_works/domain/document_ingestion.py`
- [Embedding provider](https://github.com/hongweihsu/dev-atlas/blob/main/apps/api/src/retrieval_works/infrastructure/embedding/openai.py): `apps/api/src/retrieval_works/infrastructure/embedding/openai.py`
- [Embedding contract](https://github.com/hongweihsu/dev-atlas/blob/main/apps/api/src/retrieval_works/application/ports/embedding.py): `apps/api/src/retrieval_works/application/ports/embedding.py`

### API and persistence

- [FastAPI service](https://github.com/hongweihsu/dev-atlas/blob/main/apps/api/src/retrieval_works/main.py): `apps/api/src/retrieval_works/main.py`
- [API routes](https://github.com/hongweihsu/dev-atlas/blob/main/apps/api/src/retrieval_works/api/router.py): `apps/api/src/retrieval_works/api/router.py`
- [Job persistence](https://github.com/hongweihsu/dev-atlas/blob/main/apps/api/src/retrieval_works/infrastructure/persistence/ingestion_jobs.py): `apps/api/src/retrieval_works/infrastructure/persistence/ingestion_jobs.py`
- [Document persistence](https://github.com/hongweihsu/dev-atlas/blob/main/apps/api/src/retrieval_works/infrastructure/persistence/repository.py): `apps/api/src/retrieval_works/infrastructure/persistence/repository.py`
- [Observability](https://github.com/hongweihsu/dev-atlas/blob/main/apps/api/src/retrieval_works/infrastructure/observability.py): `apps/api/src/retrieval_works/infrastructure/observability.py`

### Research capabilities

- [Hybrid search](https://github.com/hongweihsu/dev-atlas/blob/main/apps/api/src/retrieval_works/application/search_documents.py): `apps/api/src/retrieval_works/application/search_documents.py`
- [Grounded answers](https://github.com/hongweihsu/dev-atlas/blob/main/apps/api/src/retrieval_works/api/routes/answers.py): `apps/api/src/retrieval_works/api/routes/answers.py`
- [Research and tools](https://github.com/hongweihsu/dev-atlas/blob/main/apps/api/src/retrieval_works/api/routes/research.py): `apps/api/src/retrieval_works/api/routes/research.py`
- [Conversation memory](https://github.com/hongweihsu/dev-atlas/blob/main/apps/api/src/retrieval_works/application/manage_conversations.py): `apps/api/src/retrieval_works/application/manage_conversations.py`

### Other components

- **Platform user**
- **PostgreSQL**
- **Redis queue**
- **OpenAI services**
- **Cognito identity**

## Connections

- Platform user → Research workspace: uses (evidence: `README.md`)
- Research workspace → API client: requests (evidence: `apps/web/src/App.tsx`)
- Research workspace → Sign-in UI: renders (evidence: `apps/web/src/App.tsx`)
- Research workspace → Workspace controls: renders (evidence: `apps/web/src/App.tsx`)
- API client → FastAPI service: calls (evidence: `README.md`)
- FastAPI service → API routes: mounts (evidence: `apps/api/src/retrieval_works/api/router.py`)
- API routes → Authentication and access: authorizes (evidence: `apps/api/src/retrieval_works/api/dependencies/authentication.py`)
- Authentication and access → Cognito identity: verifies tokens (evidence: `README.md`)
- Authentication and access → PostgreSQL: resolves membership (evidence: `README.md`)
- API routes → Workspace management: routes workspace actions (evidence: `apps/api/src/retrieval_works/api/router.py`)
- API routes → Knowledge-base management: routes scope actions (evidence: `apps/api/src/retrieval_works/api/router.py`)
- API routes → Ingestion job API: routes job actions (evidence: `apps/api/src/retrieval_works/api/router.py`)
- Ingestion job API → Job management: submits jobs (evidence: `apps/api/src/retrieval_works/api/routes/ingestion_jobs.py`)
- Job management → Job persistence: creates or reads (evidence: `apps/api/src/retrieval_works/application/manage_ingestion_jobs.py`)
- Job persistence → PostgreSQL: persists jobs (evidence: `apps/api/src/retrieval_works/infrastructure/persistence/ingestion_jobs.py`)
- Job persistence → Redis queue: dispatches jobs (evidence: `README.md`)
- Redis queue → Ingestion worker: delivers jobs (evidence: `README.md`)
- Ingestion worker → Document preparation: runs ingestion (evidence: `apps/api/src/retrieval_works/worker.py`)
- Document preparation → Normalize and chunk: prepares text (evidence: `apps/api/src/retrieval_works/application/ingest_document.py`)
- Document preparation → Embedding contract: requests vectors (evidence: `apps/api/src/retrieval_works/application/ingest_document.py`)
- Embedding provider → Embedding contract: implements (evidence: `apps/api/src/retrieval_works/infrastructure/embedding/openai.py`)
- Embedding provider → OpenAI services: requests embeddings (evidence: `README.md`)
- Document preparation → Document persistence: persists chunks (evidence: `README.md`)
- Document persistence → PostgreSQL: stores documents (evidence: `README.md`)
- API routes → Hybrid search: routes search (evidence: `apps/api/src/retrieval_works/api/router.py`)
- API routes → Grounded answers: routes answers (evidence: `apps/api/src/retrieval_works/api/router.py`)
- API routes → Research and tools: routes research (evidence: `apps/api/src/retrieval_works/api/router.py`)
- API routes → Conversation memory: routes conversations (evidence: `apps/api/src/retrieval_works/api/router.py`)
- Hybrid search → PostgreSQL: searches chunks (evidence: `README.md`)
- Grounded answers → Hybrid search: grounds answers (evidence: `README.md`)
- Research and tools → Hybrid search: searches authorized scope (evidence: `README.md`)
- Conversation memory → PostgreSQL: stores turns (evidence: `README.md`)
- FastAPI service → Observability: records outcomes (evidence: `README.md`)
