# phoo1911/startup architecture

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

- Interactive diagram: https://gitdiagram.com/phoo1911/startup
- Repository: https://github.com/phoo1911/startup

## Overview

This is a startup-support information search, recommendation, and chatbot service. The principal workflow is Browser → FastAPI → the current agentic_hybrid query graph → cached retrieval index → policy-aware generated response. A separate administrative workflow recollects public data, rebuilds the index, and reinitializes the service. The README documents the current pipeline stages and rebuild flow; sampled code confirms selected graph, retrieval, and legacy components, but not every runtime call.

Main entry points: [`agentic_hybrid/graph.py`](https://github.com/phoo1911/startup/blob/main/agentic_hybrid/graph.py) (Query graph), [`agentic_hybrid/nodes/retrieve_node.py`](https://github.com/phoo1911/startup/blob/main/agentic_hybrid/nodes/retrieve_node.py) (Document retrieval), [`legacy_core/orchestrator.py`](https://github.com/phoo1911/startup/blob/main/legacy_core/orchestrator.py) (Legacy index orchestrator), [`web/fastapi_app.py`](https://github.com/phoo1911/startup/blob/main/web/fastapi_app.py) (FastAPI routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_service["Web service"]
  node_fastapi["FastAPI routes<br/>[fastapi_app.py]"]
  node_runtime["Agentic runtime<br/>[main_agentic.py]"]
end

subgraph group_query["Query workflow"]
  node_graph["Query graph<br/>[graph.py]"]
  node_state["Query state<br/>[state.py]"]
  node_intent["Intent classification"]
  node_expansion["Query expansion"]
  node_router["Document-type routing"]
  node_planner["Policy planning<br/>[planner_node.py]"]
  node_generate["Answer generation<br/>[generate_node.py]"]
  node_revise["Answer revision<br/>[revise_node.py]"]
end

subgraph group_retrieval["Retrieval and policy"]
  node_retrieve["Document retrieval<br/>[retrieve_node.py]"]
  node_vector["Vector search"]
  node_hybrid["Hybrid ranking<br/>[hybrid_rrf.py]"]
  node_bm25["BM25 search<br/>[bm25_retriever.py]"]
  node_geo["Geographic search<br/>[geo_retriever.py]"]
  node_rerank["Result reranking<br/>[rerank_node.py]"]
  node_filter["Eligibility filtering<br/>[filter_node.py]"]
  node_freshness["Freshness ranking"]
  node_dedup["Deduplication<br/>[dedup_node.py]"]
  node_crossdoc["Cross-document enrichment"]
  node_index[("Cached RAG index")]
end

subgraph group_production["Index production"]
  node_orchestrator["Legacy index orchestrator<br/>[orchestrator.py]"]
  node_collector["Data collection<br/>[data_collector.py]"]
  node_builder["RAG index builder<br/>[rag_builder.py]"]
end

node_browser(("Browser user"))
node_publicapi["Public data API"]

node_browser -->|"sends requests"| node_fastapi
node_fastapi -->|"routes queries"| node_runtime
node_runtime -->|"runs graph"| node_graph
node_graph -->|"dispatches"| node_intent
node_graph -->|"dispatches"| node_expansion
node_graph -->|"dispatches"| node_retrieve
node_graph -->|"dispatches"| node_router
node_graph -->|"dispatches"| node_rerank
node_graph -->|"dispatches"| node_planner
node_graph -->|"dispatches"| node_filter
node_graph -->|"dispatches"| node_freshness
node_graph -->|"dispatches"| node_dedup
node_graph -->|"dispatches"| node_crossdoc
node_graph -->|"dispatches"| node_generate
node_graph -->|"dispatches"| node_revise
node_graph -->|"uses state"| node_state
node_retrieve -->|"calls"| node_hybrid
node_hybrid -.->|"searches"| node_vector
node_hybrid -.->|"searches"| node_bm25
node_retrieve -.->|"searches"| node_geo
node_retrieve -.->|"reads"| node_index
node_fastapi -->|"rebuilds index"| node_orchestrator
node_orchestrator -->|"collects data"| node_collector
node_orchestrator -->|"builds index"| node_builder
node_collector -.->|"fetches records"| node_publicapi
node_builder -->|"writes index"| node_index
node_orchestrator -->|"refreshes cache"| node_index

click node_fastapi "https://github.com/phoo1911/startup/blob/main/web/fastapi_app.py"
click node_runtime "https://github.com/phoo1911/startup/blob/main/agentic_hybrid/main_agentic.py"
click node_graph "https://github.com/phoo1911/startup/blob/main/agentic_hybrid/graph.py"
click node_state "https://github.com/phoo1911/startup/blob/main/agentic_hybrid/state.py"
click node_intent "https://github.com/phoo1911/startup/blob/main/agentic_hybrid/nodes/intent_classifier_node.py"
click node_expansion "https://github.com/phoo1911/startup/blob/main/agentic_hybrid/nodes/query_expansion_node.py"
click node_retrieve "https://github.com/phoo1911/startup/blob/main/agentic_hybrid/nodes/retrieve_node.py"
click node_vector "https://github.com/phoo1911/startup/blob/main/agentic_hybrid/retrieval/vector_retriever.py"
click node_hybrid "https://github.com/phoo1911/startup/blob/main/agentic_hybrid/retrieval/hybrid_rrf.py"
click node_bm25 "https://github.com/phoo1911/startup/blob/main/agentic_hybrid/retrieval/bm25_retriever.py"
click node_geo "https://github.com/phoo1911/startup/blob/main/agentic_hybrid/retrieval/geo_retriever.py"
click node_router "https://github.com/phoo1911/startup/blob/main/agentic_hybrid/nodes/doc_type_router_node.py"
click node_rerank "https://github.com/phoo1911/startup/blob/main/agentic_hybrid/nodes/rerank_node.py"
click node_planner "https://github.com/phoo1911/startup/blob/main/agentic_hybrid/nodes/planner_node.py"
click node_filter "https://github.com/phoo1911/startup/blob/main/agentic_hybrid/nodes/filter_node.py"
click node_freshness "https://github.com/phoo1911/startup/blob/main/agentic_hybrid/retrieval/freshness_reranker.py"
click node_dedup "https://github.com/phoo1911/startup/blob/main/agentic_hybrid/nodes/dedup_node.py"
click node_crossdoc "https://github.com/phoo1911/startup/blob/main/agentic_hybrid/retrieval/cross_doc_linker.py"
click node_generate "https://github.com/phoo1911/startup/blob/main/agentic_hybrid/nodes/generate_node.py"
click node_revise "https://github.com/phoo1911/startup/blob/main/agentic_hybrid/nodes/revise_node.py"
click node_orchestrator "https://github.com/phoo1911/startup/blob/main/legacy_core/orchestrator.py"
click node_collector "https://github.com/phoo1911/startup/blob/main/legacy_agents/data_collector.py"
click node_builder "https://github.com/phoo1911/startup/blob/main/legacy_agents/rag_builder.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_fastapi,node_runtime,node_browser toneBlue
class node_graph,node_state,node_intent,node_expansion,node_router,node_planner,node_generate,node_revise toneAmber
class node_retrieve,node_vector,node_hybrid,node_bm25,node_geo,node_rerank,node_filter,node_freshness,node_dedup,node_crossdoc,node_index,node_publicapi toneMint
class node_orchestrator,node_collector,node_builder toneRose
```

## Components

### Web service

- [FastAPI routes](https://github.com/phoo1911/startup/blob/main/web/fastapi_app.py): `web/fastapi_app.py`
- [Agentic runtime](https://github.com/phoo1911/startup/blob/main/agentic_hybrid/main_agentic.py): `agentic_hybrid/main_agentic.py`

### Query workflow

- [Query graph](https://github.com/phoo1911/startup/blob/main/agentic_hybrid/graph.py): `agentic_hybrid/graph.py`
- [Query state](https://github.com/phoo1911/startup/blob/main/agentic_hybrid/state.py): `agentic_hybrid/state.py`
- [Intent classification](https://github.com/phoo1911/startup/blob/main/agentic_hybrid/nodes/intent_classifier_node.py): `agentic_hybrid/nodes/intent_classifier_node.py`
- [Query expansion](https://github.com/phoo1911/startup/blob/main/agentic_hybrid/nodes/query_expansion_node.py): `agentic_hybrid/nodes/query_expansion_node.py`
- [Document-type routing](https://github.com/phoo1911/startup/blob/main/agentic_hybrid/nodes/doc_type_router_node.py): `agentic_hybrid/nodes/doc_type_router_node.py`
- [Policy planning](https://github.com/phoo1911/startup/blob/main/agentic_hybrid/nodes/planner_node.py): `agentic_hybrid/nodes/planner_node.py`
- [Answer generation](https://github.com/phoo1911/startup/blob/main/agentic_hybrid/nodes/generate_node.py): `agentic_hybrid/nodes/generate_node.py`
- [Answer revision](https://github.com/phoo1911/startup/blob/main/agentic_hybrid/nodes/revise_node.py): `agentic_hybrid/nodes/revise_node.py`

### Retrieval and policy

- [Document retrieval](https://github.com/phoo1911/startup/blob/main/agentic_hybrid/nodes/retrieve_node.py): `agentic_hybrid/nodes/retrieve_node.py`
- [Vector search](https://github.com/phoo1911/startup/blob/main/agentic_hybrid/retrieval/vector_retriever.py): `agentic_hybrid/retrieval/vector_retriever.py`
- [Hybrid ranking](https://github.com/phoo1911/startup/blob/main/agentic_hybrid/retrieval/hybrid_rrf.py): `agentic_hybrid/retrieval/hybrid_rrf.py`
- [BM25 search](https://github.com/phoo1911/startup/blob/main/agentic_hybrid/retrieval/bm25_retriever.py): `agentic_hybrid/retrieval/bm25_retriever.py`
- [Geographic search](https://github.com/phoo1911/startup/blob/main/agentic_hybrid/retrieval/geo_retriever.py): `agentic_hybrid/retrieval/geo_retriever.py`
- [Result reranking](https://github.com/phoo1911/startup/blob/main/agentic_hybrid/nodes/rerank_node.py): `agentic_hybrid/nodes/rerank_node.py`
- [Eligibility filtering](https://github.com/phoo1911/startup/blob/main/agentic_hybrid/nodes/filter_node.py): `agentic_hybrid/nodes/filter_node.py`
- [Freshness ranking](https://github.com/phoo1911/startup/blob/main/agentic_hybrid/retrieval/freshness_reranker.py): `agentic_hybrid/retrieval/freshness_reranker.py`
- [Deduplication](https://github.com/phoo1911/startup/blob/main/agentic_hybrid/nodes/dedup_node.py): `agentic_hybrid/nodes/dedup_node.py`
- [Cross-document enrichment](https://github.com/phoo1911/startup/blob/main/agentic_hybrid/retrieval/cross_doc_linker.py): `agentic_hybrid/retrieval/cross_doc_linker.py`
- **Cached RAG index**

### Index production

- [Legacy index orchestrator](https://github.com/phoo1911/startup/blob/main/legacy_core/orchestrator.py): `legacy_core/orchestrator.py`
- [Data collection](https://github.com/phoo1911/startup/blob/main/legacy_agents/data_collector.py): `legacy_agents/data_collector.py`
- [RAG index builder](https://github.com/phoo1911/startup/blob/main/legacy_agents/rag_builder.py): `legacy_agents/rag_builder.py`

### Other components

- **Browser user**
- **Public data API**

## Connections

- Browser user → FastAPI routes: sends requests
- FastAPI routes → Agentic runtime: routes queries (evidence: `web/fastapi_app.py`)
- Agentic runtime → Query graph: runs graph (evidence: `agentic_hybrid/main_agentic.py`)
- Query graph → Intent classification: dispatches (evidence: `agentic_hybrid/graph.py`)
- Query graph → Query expansion: dispatches (evidence: `agentic_hybrid/graph.py`)
- Query graph → Document retrieval: dispatches (evidence: `agentic_hybrid/graph.py`)
- Query graph → Document-type routing: dispatches (evidence: `agentic_hybrid/graph.py`)
- Query graph → Result reranking: dispatches (evidence: `agentic_hybrid/graph.py`)
- Query graph → Policy planning: dispatches (evidence: `agentic_hybrid/graph.py`)
- Query graph → Eligibility filtering: dispatches (evidence: `agentic_hybrid/graph.py`)
- Query graph → Freshness ranking: dispatches (evidence: `agentic_hybrid/graph.py`)
- Query graph → Deduplication: dispatches (evidence: `agentic_hybrid/graph.py`)
- Query graph → Cross-document enrichment: dispatches (evidence: `agentic_hybrid/graph.py`)
- Query graph → Answer generation: dispatches (evidence: `agentic_hybrid/graph.py`)
- Query graph → Answer revision: dispatches (evidence: `agentic_hybrid/graph.py`)
- Query graph → Query state: uses state (evidence: `agentic_hybrid/graph.py`)
- Document retrieval → Hybrid ranking: calls (evidence: `agentic_hybrid/nodes/retrieve_node.py`)
- Hybrid ranking → Vector search: searches
- Hybrid ranking → BM25 search: searches
- Document retrieval → Geographic search: searches
- Document retrieval → Cached RAG index: reads
- FastAPI routes → Legacy index orchestrator: rebuilds index (evidence: `web/fastapi_app.py`)
- Legacy index orchestrator → Data collection: collects data (evidence: `legacy_core/orchestrator.py`)
- Legacy index orchestrator → RAG index builder: builds index (evidence: `legacy_core/orchestrator.py`)
- Data collection → Public data API: fetches records
- RAG index builder → Cached RAG index: writes index
- Legacy index orchestrator → Cached RAG index: refreshes cache
