# lyx0902/apexlogic architecture

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

- Interactive diagram: https://gitdiagram.com/lyx0902/apexlogic
- Repository: https://github.com/lyx0902/apexlogic

## Overview

ApexLogic is a resumable multi-agent deep-research system. Its main workflow takes a topic through retrieval, evidence selection, report drafting, and review; review routes the run back to research or writing until accepted, limited, or capped. Separate capabilities include persistent run recovery, source-evidence memory, PostgreSQL background execution, and report follow-up operations. The README documents several subsystem links whose implementations were not sampled, so the graph includes those documented capabilities without asserting uncertain internal calls.

Main entry points: [`core/runner.py`](https://github.com/lyx0902/apexlogic/blob/master/core/runner.py) (Run orchestrator), [`agents/researchers.py`](https://github.com/lyx0902/apexlogic/blob/master/agents/researchers.py) (Research agent), [`core/storage.py`](https://github.com/lyx0902/apexlogic/blob/master/core/storage.py) (Backend selection), [`core/background.py`](https://github.com/lyx0902/apexlogic/blob/master/core/background.py) (Background worker)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User entry"]
  node_app["Streamlit UI<br/>[app.py]"]
  node_cli["CLI<br/>[main.py]"]
end

subgraph group_research["Research workflow"]
  node_researcher["Research agent<br/>[researchers.py]"]
  node_writer["Writer agent<br/>[writer.py]"]
  node_reviewer["Reviewer agent<br/>[reviewer.py]"]
  node_planner["Query planning<br/>[query_planner.py]"]
  node_search["Search tools<br/>[search_tool.py]"]
  node_arxiv["arXiv search<br/>[arxiv_tool.py]"]
  node_graph_expand["Concept expansion<br/>[graph_expand.py]"]
  node_iterative["Multi-hop search"]
  node_mab["Adaptive allocation<br/>[mab_search.py]"]
end

subgraph group_evidence["Evidence and memory"]
  node_retriever["Vector retrieval<br/>[retriever.py]"]
  node_reranker["Evidence reranking<br/>[reranker.py]"]
  node_embedding["Embedding client<br/>[embeddings.py]"]
  node_memory_service["Memory service<br/>[service.py]"]
  node_memory_repo[("Memory repository<br/>[repository.py]")]
end

subgraph group_runtime["Execution and storage"]
  node_runner["Run orchestrator<br/>[runner.py]"]
  node_worker["Background worker<br/>[background.py]"]
  node_storage["Backend selection<br/>[storage.py]"]
  node_run_repo[("Run repository<br/>[run_repository.py]")]
  node_postgres_repo[("Postgres run store")]
  node_checkpoint[("Checkpoint persistence<br/>[persistence.py]")]
  node_postgres[("Postgres access<br/>[postgres.py]")]
  node_redis_cache["Request cache<br/>[cache.py]"]
end

subgraph group_operations["Report operations"]
  node_intent["Intent routing<br/>[intent.py]"]
  node_followup["Follow-up answers<br/>[followup.py]"]
  node_report_ops["Report operations"]
  node_conversation["Conversation queue<br/>[conversation.py]"]
end

node_user(("Researcher"))
node_llm(("LLM service"))
node_search_services(("Search providers"))
node_bge_service(("BGE API"))
node_redis[("Redis")]
node_report["Research report"]

node_user -->|"submits topic"| node_app
node_user -->|"submits topic"| node_cli
node_app -->|"creates or resumes"| node_runner
node_cli -->|"creates or resumes"| node_runner
node_runner -->|"runs research"| node_researcher
node_runner -->|"runs drafting"| node_writer
node_runner -->|"runs review"| node_reviewer
node_reviewer -->|"routes iteration"| node_runner
node_researcher -->|"decomposes queries"| node_planner
node_researcher -->|"requests search"| node_search
node_researcher -->|"requests search"| node_arxiv
node_researcher -->|"expands concepts"| node_graph_expand
node_researcher -->|"retrieves gaps"| node_iterative
node_researcher -->|"allocates results"| node_mab
node_search -->|"queries providers"| node_search_services
node_arxiv -->|"queries arXiv"| node_search_services
node_researcher -->|"selects evidence"| node_retriever
node_retriever -->|"embeds texts"| node_embedding
node_retriever -->|"ranks candidates"| node_reranker
node_embedding -->|"requests vectors"| node_bge_service
node_researcher -->|"recalls evidence"| node_memory_service
node_runner -->|"publishes accepted sources"| node_memory_service
node_memory_service -->|"reads and writes"| node_memory_repo
node_memory_service -->|"embeds evidence"| node_embedding
node_writer -->|"generates draft"| node_llm
node_reviewer -->|"evaluates draft"| node_llm
node_app -->|"classifies operation"| node_intent
node_intent -.->|"requests fallback"| node_llm
node_app -->|"queues operation"| node_conversation
node_worker -->|"processes turns"| node_conversation
node_worker -->|"executes research"| node_runner
node_worker -->|"answers follow-up"| node_followup
node_worker -->|"updates or verifies"| node_report_ops
node_followup -->|"returns answer"| node_report
node_report_ops -->|"fetches new sources"| node_search_services
node_report_ops -->|"creates version"| node_report
node_runner -->|"produces report"| node_report
node_runner -->|"selects persistence"| node_storage
node_storage -->|"selects SQLite"| node_run_repo
node_storage -->|"selects PostgreSQL"| node_postgres_repo
node_storage -->|"opens SQLite checkpoint"| node_checkpoint
node_storage -->|"opens PostgreSQL checkpoint"| node_postgres
node_runner -->|"saves run state"| node_checkpoint
node_runner -->|"records run"| node_run_repo
node_runner -->|"records run"| node_postgres_repo
node_search -.->|"uses optional cache"| node_redis_cache
node_embedding -.->|"uses optional cache"| node_redis_cache
node_redis_cache -.->|"reads and writes"| node_redis

click node_app "https://github.com/lyx0902/apexlogic/blob/master/app.py"
click node_cli "https://github.com/lyx0902/apexlogic/blob/master/main.py"
click node_runner "https://github.com/lyx0902/apexlogic/blob/master/core/runner.py"
click node_researcher "https://github.com/lyx0902/apexlogic/blob/master/agents/researchers.py"
click node_writer "https://github.com/lyx0902/apexlogic/blob/master/agents/writer.py"
click node_reviewer "https://github.com/lyx0902/apexlogic/blob/master/agents/reviewer.py"
click node_planner "https://github.com/lyx0902/apexlogic/blob/master/optim/query_planner.py"
click node_search "https://github.com/lyx0902/apexlogic/blob/master/tools/search_tool.py"
click node_arxiv "https://github.com/lyx0902/apexlogic/blob/master/tools/arxiv_tool.py"
click node_graph_expand "https://github.com/lyx0902/apexlogic/blob/master/optim/graph_expand.py"
click node_iterative "https://github.com/lyx0902/apexlogic/blob/master/optim/iterative_retrieval.py"
click node_mab "https://github.com/lyx0902/apexlogic/blob/master/optim/mab_search.py"
click node_retriever "https://github.com/lyx0902/apexlogic/blob/master/bge/retriever.py"
click node_reranker "https://github.com/lyx0902/apexlogic/blob/master/bge/reranker.py"
click node_embedding "https://github.com/lyx0902/apexlogic/blob/master/bge/embeddings.py"
click node_memory_service "https://github.com/lyx0902/apexlogic/blob/master/memory/service.py"
click node_memory_repo "https://github.com/lyx0902/apexlogic/blob/master/memory/repository.py"
click node_intent "https://github.com/lyx0902/apexlogic/blob/master/core/intent.py"
click node_followup "https://github.com/lyx0902/apexlogic/blob/master/core/followup.py"
click node_report_ops "https://github.com/lyx0902/apexlogic/blob/master/core/report_operations.py"
click node_conversation "https://github.com/lyx0902/apexlogic/blob/master/core/conversation.py"
click node_worker "https://github.com/lyx0902/apexlogic/blob/master/core/background.py"
click node_storage "https://github.com/lyx0902/apexlogic/blob/master/core/storage.py"
click node_run_repo "https://github.com/lyx0902/apexlogic/blob/master/core/run_repository.py"
click node_postgres_repo "https://github.com/lyx0902/apexlogic/blob/master/core/postgres_repository.py"
click node_checkpoint "https://github.com/lyx0902/apexlogic/blob/master/core/persistence.py"
click node_postgres "https://github.com/lyx0902/apexlogic/blob/master/core/postgres.py"
click node_redis_cache "https://github.com/lyx0902/apexlogic/blob/master/core/cache.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_app,node_cli toneBlue
class node_researcher,node_writer,node_reviewer,node_planner,node_search,node_arxiv,node_graph_expand,node_iterative,node_mab,node_redis toneAmber
class node_retriever,node_reranker,node_embedding,node_memory_service,node_memory_repo,node_bge_service toneMint
class node_runner,node_worker,node_storage,node_run_repo,node_postgres_repo,node_checkpoint,node_postgres,node_redis_cache toneRose
class node_intent,node_followup,node_report_ops,node_conversation,node_user,node_llm,node_search_services,node_report toneIndigo
```

## Components

### User entry

- [Streamlit UI](https://github.com/lyx0902/apexlogic/blob/master/app.py): `app.py`
- [CLI](https://github.com/lyx0902/apexlogic/blob/master/main.py): `main.py`

### Research workflow

- [Research agent](https://github.com/lyx0902/apexlogic/blob/master/agents/researchers.py): `agents/researchers.py`
- [Writer agent](https://github.com/lyx0902/apexlogic/blob/master/agents/writer.py): `agents/writer.py`
- [Reviewer agent](https://github.com/lyx0902/apexlogic/blob/master/agents/reviewer.py): `agents/reviewer.py`
- [Query planning](https://github.com/lyx0902/apexlogic/blob/master/optim/query_planner.py): `optim/query_planner.py`
- [Search tools](https://github.com/lyx0902/apexlogic/blob/master/tools/search_tool.py): `tools/search_tool.py`
- [arXiv search](https://github.com/lyx0902/apexlogic/blob/master/tools/arxiv_tool.py): `tools/arxiv_tool.py`
- [Concept expansion](https://github.com/lyx0902/apexlogic/blob/master/optim/graph_expand.py): `optim/graph_expand.py`
- [Multi-hop search](https://github.com/lyx0902/apexlogic/blob/master/optim/iterative_retrieval.py): `optim/iterative_retrieval.py`
- [Adaptive allocation](https://github.com/lyx0902/apexlogic/blob/master/optim/mab_search.py): `optim/mab_search.py`

### Evidence and memory

- [Vector retrieval](https://github.com/lyx0902/apexlogic/blob/master/bge/retriever.py): `bge/retriever.py`
- [Evidence reranking](https://github.com/lyx0902/apexlogic/blob/master/bge/reranker.py): `bge/reranker.py`
- [Embedding client](https://github.com/lyx0902/apexlogic/blob/master/bge/embeddings.py): `bge/embeddings.py`
- [Memory service](https://github.com/lyx0902/apexlogic/blob/master/memory/service.py): `memory/service.py`
- [Memory repository](https://github.com/lyx0902/apexlogic/blob/master/memory/repository.py): `memory/repository.py`

### Execution and storage

- [Run orchestrator](https://github.com/lyx0902/apexlogic/blob/master/core/runner.py): `core/runner.py`
- [Background worker](https://github.com/lyx0902/apexlogic/blob/master/core/background.py): `core/background.py`
- [Backend selection](https://github.com/lyx0902/apexlogic/blob/master/core/storage.py): `core/storage.py`
- [Run repository](https://github.com/lyx0902/apexlogic/blob/master/core/run_repository.py): `core/run_repository.py`
- [Postgres run store](https://github.com/lyx0902/apexlogic/blob/master/core/postgres_repository.py): `core/postgres_repository.py`
- [Checkpoint persistence](https://github.com/lyx0902/apexlogic/blob/master/core/persistence.py): `core/persistence.py`
- [Postgres access](https://github.com/lyx0902/apexlogic/blob/master/core/postgres.py): `core/postgres.py`
- [Request cache](https://github.com/lyx0902/apexlogic/blob/master/core/cache.py): `core/cache.py`

### Report operations

- [Intent routing](https://github.com/lyx0902/apexlogic/blob/master/core/intent.py): `core/intent.py`
- [Follow-up answers](https://github.com/lyx0902/apexlogic/blob/master/core/followup.py): `core/followup.py`
- [Report operations](https://github.com/lyx0902/apexlogic/blob/master/core/report_operations.py): `core/report_operations.py`
- [Conversation queue](https://github.com/lyx0902/apexlogic/blob/master/core/conversation.py): `core/conversation.py`

### Other components

- **Researcher**
- **LLM service**
- **Search providers**
- **BGE API**
- **Redis**
- **Research report**

## Connections

- Researcher → Streamlit UI: submits topic
- Researcher → CLI: submits topic
- Streamlit UI → Run orchestrator: creates or resumes
- CLI → Run orchestrator: creates or resumes
- Run orchestrator → Research agent: runs research
- Run orchestrator → Writer agent: runs drafting
- Run orchestrator → Reviewer agent: runs review
- Reviewer agent → Run orchestrator: routes iteration
- Research agent → Query planning: decomposes queries
- Research agent → Search tools: requests search
- Research agent → arXiv search: requests search
- Research agent → Concept expansion: expands concepts
- Research agent → Multi-hop search: retrieves gaps
- Research agent → Adaptive allocation: allocates results
- Search tools → Search providers: queries providers
- arXiv search → Search providers: queries arXiv
- Research agent → Vector retrieval: selects evidence
- Vector retrieval → Embedding client: embeds texts
- Vector retrieval → Evidence reranking: ranks candidates
- Embedding client → BGE API: requests vectors
- Research agent → Memory service: recalls evidence
- Run orchestrator → Memory service: publishes accepted sources
- Memory service → Memory repository: reads and writes
- Memory service → Embedding client: embeds evidence
- Writer agent → LLM service: generates draft
- Reviewer agent → LLM service: evaluates draft
- Streamlit UI → Intent routing: classifies operation
- Intent routing → LLM service: requests fallback
- Streamlit UI → Conversation queue: queues operation
- Background worker → Conversation queue: processes turns
- Background worker → Run orchestrator: executes research
- Background worker → Follow-up answers: answers follow-up
- Background worker → Report operations: updates or verifies
- Follow-up answers → Research report: returns answer
- Report operations → Search providers: fetches new sources
- Report operations → Research report: creates version
- Run orchestrator → Research report: produces report
- Run orchestrator → Backend selection: selects persistence
- Backend selection → Run repository: selects SQLite
- Backend selection → Postgres run store: selects PostgreSQL
- Backend selection → Checkpoint persistence: opens SQLite checkpoint
- Backend selection → Postgres access: opens PostgreSQL checkpoint
- Run orchestrator → Checkpoint persistence: saves run state
- Run orchestrator → Run repository: records run
- Run orchestrator → Postgres run store: records run
- Search tools → Request cache: uses optional cache
- Embedding client → Request cache: uses optional cache
- Request cache → Redis: reads and writes