How hongweihsu/dev-atlas works
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: router.py API routes · App.tsx Research workspace · ingest_document.py Document preparation · search_documents.py Hybrid search
Components 28
Web experience
- Research workspace
apps/web/src/App.tsx - API client
apps/web/src/api.ts - Sign-in UI
apps/web/src/AuthPanel.tsx - Workspace controls
apps/web/src/WorkspaceControls.tsx
Identity and scope
- Authentication and access
apps/api/src/retrieval_works/api/dependencies/authentication.py - Workspace management
apps/api/src/retrieval_works/api/routes/workspaces.py
Knowledge workflows
- Knowledge-base management
apps/api/src/retrieval_works/api/routes/knowledge_bases.py - Ingestion job API
apps/api/src/retrieval_works/api/routes/ingestion_jobs.py - Job management
apps/api/src/retrieval_works/application/manage_ingestion_jobs.py - Ingestion worker
apps/api/src/retrieval_works/worker.py - Document preparation
apps/api/src/retrieval_works/application/ingest_document.py - Normalize and chunk
apps/api/src/retrieval_works/domain/document_ingestion.py - Embedding provider
apps/api/src/retrieval_works/infrastructure/embedding/openai.py - Embedding contract
apps/api/src/retrieval_works/application/ports/embedding.py
API and persistence
- FastAPI service
apps/api/src/retrieval_works/main.py - API routes
apps/api/src/retrieval_works/api/router.py - Job persistence
apps/api/src/retrieval_works/infrastructure/persistence/ingestion_jobs.py - Document persistence
apps/api/src/retrieval_works/infrastructure/persistence/repository.py - Observability
apps/api/src/retrieval_works/infrastructure/observability.py
Research capabilities
- Hybrid search
apps/api/src/retrieval_works/application/search_documents.py - Grounded answers
apps/api/src/retrieval_works/api/routes/answers.py - Research and tools
apps/api/src/retrieval_works/api/routes/research.py - Conversation memory
apps/api/src/retrieval_works/application/manage_conversations.py
Other components
- Platform user
- PostgreSQL
- Redis queue
- OpenAI services
- Cognito identity
Connections 33
- Platform user → Research workspace: uses
README.md - Research workspace → API client: requests
apps/web/src/App.tsx - Research workspace → Sign-in UI: renders
apps/web/src/App.tsx - Research workspace → Workspace controls: renders
apps/web/src/App.tsx - API client → FastAPI service: calls
README.md - FastAPI service → API routes: mounts
apps/api/src/retrieval_works/api/router.py - API routes → Authentication and access: authorizes
apps/api/src/retrieval_works/api/dependencies/authentication.py - Authentication and access → Cognito identity: verifies tokens
README.md - Authentication and access → PostgreSQL: resolves membership
README.md - API routes → Workspace management: routes workspace actions
apps/api/src/retrieval_works/api/router.py - API routes → Knowledge-base management: routes scope actions
apps/api/src/retrieval_works/api/router.py - API routes → Ingestion job API: routes job actions
apps/api/src/retrieval_works/api/router.py - Ingestion job API → Job management: submits jobs
apps/api/src/retrieval_works/api/routes/ingestion_jobs.py - Job management → Job persistence: creates or reads
apps/api/src/retrieval_works/application/manage_ingestion_jobs.py - Job persistence → PostgreSQL: persists jobs
apps/api/src/retrieval_works/infrastructure/persistence/ingestion_jobs.py - Job persistence → Redis queue: dispatches jobs
README.md - Redis queue → Ingestion worker: delivers jobs
README.md - Ingestion worker → Document preparation: runs ingestion
apps/api/src/retrieval_works/worker.py - Document preparation → Normalize and chunk: prepares text
apps/api/src/retrieval_works/application/ingest_document.py - Document preparation → Embedding contract: requests vectors
apps/api/src/retrieval_works/application/ingest_document.py - Embedding provider → Embedding contract: implements
apps/api/src/retrieval_works/infrastructure/embedding/openai.py - Embedding provider → OpenAI services: requests embeddings
README.md - Document preparation → Document persistence: persists chunks
README.md - Document persistence → PostgreSQL: stores documents
README.md - API routes → Hybrid search: routes search
apps/api/src/retrieval_works/api/router.py - API routes → Grounded answers: routes answers
apps/api/src/retrieval_works/api/router.py - API routes → Research and tools: routes research
apps/api/src/retrieval_works/api/router.py - API routes → Conversation memory: routes conversations
apps/api/src/retrieval_works/api/router.py - Hybrid search → PostgreSQL: searches chunks
README.md - Grounded answers → Hybrid search: grounds answers
README.md - Research and tools → Hybrid search: searches authorized scope
README.md - Conversation memory → PostgreSQL: stores turns
README.md - FastAPI service → Observability: records outcomes
README.md