# timothylee58/naktahu-ai architecture

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

- Interactive diagram: https://gitdiagram.com/timothylee58/naktahu-ai
- Repository: https://github.com/timothylee58/naktahu-ai

## Overview

NakTahu AI is a Malaysian trilingual civic-answer platform with cited government-source retrieval, specialist agents, and supporting user and developer services. The main workflow runs from a user query through the streaming API, retrieval and answer synthesis, then returns tokens and citations; the web client also supports voice input and answer translation. The README documents additional agent, Warung Watch, parliamentary, history, sharing, and developer-API capabilities. Some of these implementations were not sampled, so their links are shown only where documented, and unsampled details are not inferred.

Main entry points: [`apps/api/app/main.py`](https://github.com/timothylee58/naktahu-ai/blob/main/apps/api/app/main.py) (API application), [`apps/api/app/routers/query.py`](https://github.com/timothylee58/naktahu-ai/blob/main/apps/api/app/routers/query.py) (Streaming query), [`apps/web/src/app/chat/page.tsx`](https://github.com/timothylee58/naktahu-ai/blob/main/apps/web/src/app/chat/page.tsx) (Chat interface), [`apps/api/app/agents/graph.py`](https://github.com/timothylee58/naktahu-ai/blob/main/apps/api/app/agents/graph.py) (Answer workflow)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["User experience"]
  node_chat["Chat interface<br/>[page.tsx]"]
  node_voice["Voice input<br/>[useVoiceInput.ts]"]
  node_translation["Answer translation<br/>[translate.py]"]
end

subgraph group_answers["Answer engine"]
  node_query["Streaming query<br/>[query.py]"]
  node_answer_graph["Answer workflow<br/>[graph.py]"]
  node_guard["Safety scanning<br/>[guard_node.py]"]
  node_retrieval["Hybrid retrieval<br/>[retriever.py]"]
  node_language_models["LLM client<br/>[llm_client.py]"]
end

subgraph group_agents["Agent services"]
  node_agents_router["Agent endpoints<br/>[agents.py]"]
  node_eligibility["Grant matching<br/>[eligibility.py]"]
  node_investor["Investor intelligence<br/>[investor.py]"]
  node_agent_runtime["Agent runtime<br/>[agent_runner.py]"]
  node_checkpointer[("Agent sessions<br/>[checkpointer.py]")]
  node_domain_agents["Specialist agents"]
  node_parliament["Parliament lookup"]
end

subgraph group_platform["Platform services"]
  node_api["API application<br/>[main.py]"]
  node_warung["Warung Watch<br/>[warung_watch.py]"]
  node_developer["Developer API<br/>[developer.py]"]
  node_api_keys["API key service<br/>[api_key_service.py]"]
  node_history["Query history<br/>[history.py]"]
  node_history_store[("History service<br/>[history.py]")]
  node_billing["Billing<br/>[billing.py]"]
  node_billing_service["Billing service<br/>[billing.py]"]
  node_configuration["Runtime configuration<br/>[config.py]"]
  node_rate_limits["Rate limiting<br/>[rate_limit.py]"]
  node_plan_gate["Plan gating<br/>[plan_gate.py]"]
  node_request_fields["Query metadata<br/>[_request_fields.py]"]
end

subgraph group_data["Data and integrations"]
  node_vector[("Vector store<br/>[vector_store.py]")]
  node_grant_data["Grant and welfare sources"]
  node_places["Google Places"]
end

node_user(("User"))
node_external_integrator(("External integrator"))

node_user -->|"asks"| node_chat
node_chat -->|"sends query"| node_query
node_voice -->|"dictates into"| node_chat
node_api -->|"routes to"| node_query
node_query -->|"runs workflow"| node_answer_graph
node_answer_graph -.->|"scans safely"| node_guard
node_answer_graph -.->|"retrieves sources"| node_retrieval
node_retrieval -.->|"searches corpus"| node_vector
node_answer_graph -.->|"synthesises answer"| node_language_models
node_query -->|"streams answer"| node_chat
node_translation -->|"translates answer"| node_chat
node_api -->|"routes to"| node_agents_router
node_api -->|"routes to"| node_eligibility
node_api -->|"routes to"| node_investor
node_agents_router -->|"runs agents"| node_agent_runtime
node_eligibility -->|"loads sessions"| node_checkpointer
node_eligibility -->|"invokes matching"| node_domain_agents
node_eligibility -.->|"matches schemes"| node_grant_data
node_investor -->|"runs intelligence"| node_domain_agents
node_domain_agents -.->|"uses grant sources"| node_grant_data
node_parliament -.->|"supports lookup"| node_query
node_api -->|"routes to"| node_warung
node_warung -.->|"searches nearby"| node_places
node_api -->|"routes to"| node_developer
node_developer -->|"manages keys"| node_api_keys
node_external_integrator -->|"calls API"| node_developer
node_api -->|"routes to"| node_history
node_history -->|"reads and writes"| node_history_store
node_api -->|"routes to"| node_billing
node_billing -->|"handles billing"| node_billing_service
node_query -->|"validates metadata"| node_request_fields
node_api -->|"configures runtime"| node_configuration
node_api -->|"applies limits"| node_rate_limits
node_agents_router -->|"checks plan"| node_plan_gate

click node_chat "https://github.com/timothylee58/naktahu-ai/blob/main/apps/web/src/app/chat/page.tsx"
click node_voice "https://github.com/timothylee58/naktahu-ai/blob/main/apps/web/src/lib/hooks/useVoiceInput.ts"
click node_translation "https://github.com/timothylee58/naktahu-ai/blob/main/apps/api/routers/translate.py"
click node_api "https://github.com/timothylee58/naktahu-ai/blob/main/apps/api/app/main.py"
click node_query "https://github.com/timothylee58/naktahu-ai/blob/main/apps/api/app/routers/query.py"
click node_answer_graph "https://github.com/timothylee58/naktahu-ai/blob/main/apps/api/app/agents/graph.py"
click node_guard "https://github.com/timothylee58/naktahu-ai/blob/main/apps/api/app/agents/guard_node.py"
click node_retrieval "https://github.com/timothylee58/naktahu-ai/blob/main/apps/api/rag/retriever.py"
click node_vector "https://github.com/timothylee58/naktahu-ai/blob/main/apps/api/app/services/vector_store.py"
click node_language_models "https://github.com/timothylee58/naktahu-ai/blob/main/apps/api/app/services/llm_client.py"
click node_agents_router "https://github.com/timothylee58/naktahu-ai/blob/main/apps/api/app/routers/agents.py"
click node_eligibility "https://github.com/timothylee58/naktahu-ai/blob/main/apps/api/app/routers/eligibility.py"
click node_investor "https://github.com/timothylee58/naktahu-ai/blob/main/apps/api/app/routers/investor.py"
click node_agent_runtime "https://github.com/timothylee58/naktahu-ai/blob/main/apps/api/app/services/agent_runner.py"
click node_checkpointer "https://github.com/timothylee58/naktahu-ai/blob/main/apps/api/app/agents/checkpointer.py"
click node_domain_agents "https://github.com/timothylee58/naktahu-ai/tree/main/apps/api/app/agents"
click node_parliament "https://github.com/timothylee58/naktahu-ai/blob/main/apps/api/app/agents/parliament_query_node.py"
click node_warung "https://github.com/timothylee58/naktahu-ai/blob/main/apps/api/routers/warung_watch.py"
click node_developer "https://github.com/timothylee58/naktahu-ai/blob/main/apps/api/routers/developer.py"
click node_api_keys "https://github.com/timothylee58/naktahu-ai/blob/main/apps/api/services/api_key_service.py"
click node_history "https://github.com/timothylee58/naktahu-ai/blob/main/apps/api/routers/history.py"
click node_history_store "https://github.com/timothylee58/naktahu-ai/blob/main/apps/api/services/history.py"
click node_billing "https://github.com/timothylee58/naktahu-ai/blob/main/apps/api/routers/billing.py"
click node_billing_service "https://github.com/timothylee58/naktahu-ai/blob/main/apps/api/services/billing.py"
click node_configuration "https://github.com/timothylee58/naktahu-ai/blob/main/apps/api/core/config.py"
click node_rate_limits "https://github.com/timothylee58/naktahu-ai/blob/main/apps/api/middleware/rate_limit.py"
click node_plan_gate "https://github.com/timothylee58/naktahu-ai/blob/main/apps/api/middleware/plan_gate.py"
click node_request_fields "https://github.com/timothylee58/naktahu-ai/blob/main/apps/api/routers/_request_fields.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_chat,node_voice,node_translation,node_user toneBlue
class node_query,node_answer_graph,node_guard,node_retrieval,node_language_models toneAmber
class node_agents_router,node_eligibility,node_investor,node_agent_runtime,node_checkpointer,node_domain_agents,node_parliament toneMint
class node_api,node_warung,node_developer,node_api_keys,node_history,node_history_store,node_billing,node_billing_service,node_configuration,node_rate_limits,node_plan_gate,node_request_fields toneRose
class node_vector,node_grant_data,node_places,node_external_integrator toneIndigo
```

## Components

### User experience

- [Chat interface](https://github.com/timothylee58/naktahu-ai/blob/main/apps/web/src/app/chat/page.tsx): `apps/web/src/app/chat/page.tsx`
- [Voice input](https://github.com/timothylee58/naktahu-ai/blob/main/apps/web/src/lib/hooks/useVoiceInput.ts): `apps/web/src/lib/hooks/useVoiceInput.ts`
- [Answer translation](https://github.com/timothylee58/naktahu-ai/blob/main/apps/api/routers/translate.py): `apps/api/routers/translate.py`

### Answer engine

- [Streaming query](https://github.com/timothylee58/naktahu-ai/blob/main/apps/api/app/routers/query.py): `apps/api/app/routers/query.py`
- [Answer workflow](https://github.com/timothylee58/naktahu-ai/blob/main/apps/api/app/agents/graph.py): `apps/api/app/agents/graph.py`
- [Safety scanning](https://github.com/timothylee58/naktahu-ai/blob/main/apps/api/app/agents/guard_node.py): `apps/api/app/agents/guard_node.py`
- [Hybrid retrieval](https://github.com/timothylee58/naktahu-ai/blob/main/apps/api/rag/retriever.py): `apps/api/rag/retriever.py`
- [LLM client](https://github.com/timothylee58/naktahu-ai/blob/main/apps/api/app/services/llm_client.py): `apps/api/app/services/llm_client.py`

### Agent services

- [Agent endpoints](https://github.com/timothylee58/naktahu-ai/blob/main/apps/api/app/routers/agents.py): `apps/api/app/routers/agents.py`
- [Grant matching](https://github.com/timothylee58/naktahu-ai/blob/main/apps/api/app/routers/eligibility.py): `apps/api/app/routers/eligibility.py`
- [Investor intelligence](https://github.com/timothylee58/naktahu-ai/blob/main/apps/api/app/routers/investor.py): `apps/api/app/routers/investor.py`
- [Agent runtime](https://github.com/timothylee58/naktahu-ai/blob/main/apps/api/app/services/agent_runner.py): `apps/api/app/services/agent_runner.py`
- [Agent sessions](https://github.com/timothylee58/naktahu-ai/blob/main/apps/api/app/agents/checkpointer.py): `apps/api/app/agents/checkpointer.py`
- [Specialist agents](https://github.com/timothylee58/naktahu-ai/tree/main/apps/api/app/agents): `apps/api/app/agents`
- [Parliament lookup](https://github.com/timothylee58/naktahu-ai/blob/main/apps/api/app/agents/parliament_query_node.py): `apps/api/app/agents/parliament_query_node.py`

### Platform services

- [API application](https://github.com/timothylee58/naktahu-ai/blob/main/apps/api/app/main.py): `apps/api/app/main.py`
- [Warung Watch](https://github.com/timothylee58/naktahu-ai/blob/main/apps/api/routers/warung_watch.py): `apps/api/routers/warung_watch.py`
- [Developer API](https://github.com/timothylee58/naktahu-ai/blob/main/apps/api/routers/developer.py): `apps/api/routers/developer.py`
- [API key service](https://github.com/timothylee58/naktahu-ai/blob/main/apps/api/services/api_key_service.py): `apps/api/services/api_key_service.py`
- [Query history](https://github.com/timothylee58/naktahu-ai/blob/main/apps/api/routers/history.py): `apps/api/routers/history.py`
- [History service](https://github.com/timothylee58/naktahu-ai/blob/main/apps/api/services/history.py): `apps/api/services/history.py`
- [Billing](https://github.com/timothylee58/naktahu-ai/blob/main/apps/api/routers/billing.py): `apps/api/routers/billing.py`
- [Billing service](https://github.com/timothylee58/naktahu-ai/blob/main/apps/api/services/billing.py): `apps/api/services/billing.py`
- [Runtime configuration](https://github.com/timothylee58/naktahu-ai/blob/main/apps/api/core/config.py): `apps/api/core/config.py`
- [Rate limiting](https://github.com/timothylee58/naktahu-ai/blob/main/apps/api/middleware/rate_limit.py): `apps/api/middleware/rate_limit.py`
- [Plan gating](https://github.com/timothylee58/naktahu-ai/blob/main/apps/api/middleware/plan_gate.py): `apps/api/middleware/plan_gate.py`
- [Query metadata](https://github.com/timothylee58/naktahu-ai/blob/main/apps/api/routers/_request_fields.py): `apps/api/routers/_request_fields.py`

### Data and integrations

- [Vector store](https://github.com/timothylee58/naktahu-ai/blob/main/apps/api/app/services/vector_store.py): `apps/api/app/services/vector_store.py`
- **Grant and welfare sources**
- **Google Places**

### Other components

- **User**
- **External integrator**

## Connections

- User → Chat interface: asks
- Chat interface → Streaming query: sends query
- Voice input → Chat interface: dictates into
- API application → Streaming query: routes to (evidence: `apps/api/app/main.py`)
- Streaming query → Answer workflow: runs workflow (evidence: `apps/api/app/routers/query.py`)
- Answer workflow → Safety scanning: scans safely
- Answer workflow → Hybrid retrieval: retrieves sources
- Hybrid retrieval → Vector store: searches corpus
- Answer workflow → LLM client: synthesises answer
- Streaming query → Chat interface: streams answer
- Answer translation → Chat interface: translates answer
- API application → Agent endpoints: routes to (evidence: `apps/api/app/main.py`)
- API application → Grant matching: routes to (evidence: `apps/api/app/main.py`)
- API application → Investor intelligence: routes to (evidence: `apps/api/app/main.py`)
- Agent endpoints → Agent runtime: runs agents (evidence: `apps/api/app/routers/agents.py`)
- Grant matching → Agent sessions: loads sessions (evidence: `apps/api/app/routers/eligibility.py`)
- Grant matching → Specialist agents: invokes matching (evidence: `apps/api/app/routers/eligibility.py`)
- Grant matching → Grant and welfare sources: matches schemes
- Investor intelligence → Specialist agents: runs intelligence (evidence: `apps/api/app/routers/investor.py`)
- Specialist agents → Grant and welfare sources: uses grant sources
- Parliament lookup → Streaming query: supports lookup
- API application → Warung Watch: routes to (evidence: `apps/api/app/main.py`)
- Warung Watch → Google Places: searches nearby
- API application → Developer API: routes to (evidence: `apps/api/app/main.py`)
- Developer API → API key service: manages keys (evidence: `apps/api/routers/developer.py`)
- External integrator → Developer API: calls API
- API application → Query history: routes to (evidence: `apps/api/app/main.py`)
- Query history → History service: reads and writes (evidence: `apps/api/routers/history.py`)
- API application → Billing: routes to (evidence: `apps/api/app/main.py`)
- Billing → Billing service: handles billing (evidence: `apps/api/routers/billing.py`)
- Streaming query → Query metadata: validates metadata (evidence: `apps/api/app/routers/query.py`)
- API application → Runtime configuration: configures runtime (evidence: `apps/api/app/main.py`)
- API application → Rate limiting: applies limits (evidence: `apps/api/app/main.py`)
- Agent endpoints → Plan gating: checks plan (evidence: `apps/api/app/routers/agents.py`)
