# lahirusandeepa-lk/ai-assistent architecture

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

- Interactive diagram: https://gitdiagram.com/lahirusandeepa-lk/ai-assistent
- Repository: https://github.com/lahirusandeepa-lk/ai-assistent

## Overview

ABC Bank’s fictional enterprise assistant serves public banking questions with retrieval-grounded, cited answers. A chat request passes through the public UI and API, which handles identity, authorization, rate and token limits before invoking the LangGraph orchestrator. The agent routes the request, retrieves knowledge, calls tools or the model gateway, and returns a guarded answer with citations and usage. Admins upload and index documents and manage model configuration. The README documents the service boundaries; sampled code confirms several library-level calls, but not every service’s internal wiring.

Main entry points: [`services/ai-assistant-api/app/main.py`](https://github.com/lahirusandeepa-lk/ai-assistent/blob/main/services/ai-assistant-api/app/main.py) (Assistant API), [`libs/orchestrator/ops.py`](https://github.com/lahirusandeepa-lk/ai-assistent/blob/main/libs/orchestrator/ops.py) (Agent operations), [`libs/llm/provider.py`](https://github.com/lahirusandeepa-lk/ai-assistent/blob/main/libs/llm/provider.py) (Provider selection), [`services/ai-admin-service/app/main.py`](https://github.com/lahirusandeepa-lk/ai-assistent/blob/main/services/ai-admin-service/app/main.py) (Admin backend)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_edge["User experience and edge"]
  node_public_ui["Public chat UI<br/>[app.py]"]
  node_assistant_api["Assistant API<br/>[main.py]"]
  node_keycloak{{"Keycloak OIDC"}}
  node_rbac["Role authorization<br/>[rbac.py]"]
end

subgraph group_agent["Agent runtime"]
  node_agent_service["Orchestrator service<br/>[main.py]"]
  node_agent_graph["Agent graph<br/>[graph.py]"]
  node_agent_ops["Agent operations<br/>[ops.py]"]
  node_guardrails["Input and output guardrails<br/>[guardrails.py]"]
  node_tool_service["Tool service<br/>[main.py]"]
  node_tool_runtime["Tool runtime<br/>[tools.py]"]
end

subgraph group_knowledge["Knowledge management"]
  node_retrieval_service["Retrieval service<br/>[main.py]"]
  node_knowledge_index[("Hybrid knowledge index<br/>[store.py]")]
  node_ingestion_service["Ingestion service<br/>[main.py]"]
  node_ingest_pipeline["Document ingestion<br/>[ingest.py]"]
end

subgraph group_models["Models and state"]
  node_model_gateway["Model gateway<br/>[gateway.py]"]
  node_provider_chain["Provider selection<br/>[provider.py]"]
  node_conversation[("Conversation memory<br/>[conversation.py]")]
  node_usage[("Token budgets<br/>[usage.py]")]
  node_redis[("Redis")]
  node_postgres[("Postgres")]
  node_gemini{{"Google Gemini"}}
  node_openai{{"OpenAI fallback"}}
end

subgraph group_admin["Administration"]
  node_admin_ingest["Upload job runner<br/>[ingest_runner.py]"]
  node_admin_service["Admin backend<br/>[main.py]"]
  node_jobs[("Ingestion jobs<br/>[jobs.py]")]
  node_config_store[("LLM configuration<br/>[config_store.py]")]
end

node_user(("Chat user"))

node_user -->|"asks question"| node_public_ui
node_public_ui -->|"sends chat"| node_assistant_api
node_assistant_api -.->|"verifies identity"| node_keycloak
node_assistant_api -->|"checks roles"| node_rbac
node_assistant_api -->|"checks token budget"| node_usage
node_assistant_api -->|"runs agent"| node_agent_service
node_agent_service -->|"invokes graph"| node_agent_graph
node_agent_graph -->|"dispatches operations"| node_agent_ops
node_agent_graph -->|"applies guardrails"| node_guardrails
node_agent_ops -->|"searches knowledge"| node_retrieval_service
node_agent_ops -->|"requests completion"| node_model_gateway
node_agent_ops -->|"uses session memory"| node_conversation
node_agent_ops -.->|"calls tools"| node_tool_service
node_tool_service -->|"dispatches tools"| node_tool_runtime
node_retrieval_service -->|"searches index"| node_knowledge_index
node_ingestion_service -->|"ingests documents"| node_ingest_pipeline
node_ingest_pipeline -->|"writes chunks"| node_knowledge_index
node_admin_service -->|"indexes text"| node_ingest_pipeline
node_admin_service -->|"starts upload job"| node_admin_ingest
node_admin_ingest -->|"upserts chunks"| node_knowledge_index
node_admin_ingest -->|"updates progress"| node_jobs
node_admin_service -->|"manages providers"| node_config_store
node_model_gateway -->|"selects providers"| node_provider_chain
node_model_gateway -.->|"meters tokens"| node_usage
node_provider_chain -->|"reads settings"| node_config_store
node_provider_chain -->|"calls primary"| node_gemini
node_provider_chain -.->|"fails over"| node_openai
node_usage -->|"stores counters"| node_redis
node_conversation -.->|"persists history"| node_postgres

click node_public_ui "https://github.com/lahirusandeepa-lk/ai-assistent/blob/main/services/ui-public/app.py"
click node_assistant_api "https://github.com/lahirusandeepa-lk/ai-assistent/blob/main/services/ai-assistant-api/app/main.py"
click node_rbac "https://github.com/lahirusandeepa-lk/ai-assistent/blob/main/libs/authz/rbac.py"
click node_agent_service "https://github.com/lahirusandeepa-lk/ai-assistent/blob/main/services/ai-orchestrator/app/main.py"
click node_agent_graph "https://github.com/lahirusandeepa-lk/ai-assistent/blob/main/libs/orchestrator/graph.py"
click node_agent_ops "https://github.com/lahirusandeepa-lk/ai-assistent/blob/main/libs/orchestrator/ops.py"
click node_guardrails "https://github.com/lahirusandeepa-lk/ai-assistent/blob/main/libs/orchestrator/guardrails.py"
click node_tool_service "https://github.com/lahirusandeepa-lk/ai-assistent/blob/main/services/ai-tool-service/app/main.py"
click node_tool_runtime "https://github.com/lahirusandeepa-lk/ai-assistent/blob/main/libs/orchestrator/tools.py"
click node_retrieval_service "https://github.com/lahirusandeepa-lk/ai-assistent/blob/main/services/ai-knowledge-service/retrieval/app/main.py"
click node_knowledge_index "https://github.com/lahirusandeepa-lk/ai-assistent/blob/main/libs/rag/store.py"
click node_ingestion_service "https://github.com/lahirusandeepa-lk/ai-assistent/blob/main/services/ai-knowledge-service/ingestion/app/main.py"
click node_ingest_pipeline "https://github.com/lahirusandeepa-lk/ai-assistent/blob/main/libs/rag/ingest.py"
click node_admin_ingest "https://github.com/lahirusandeepa-lk/ai-assistent/blob/main/libs/admin/ingest_runner.py"
click node_admin_service "https://github.com/lahirusandeepa-lk/ai-assistent/blob/main/services/ai-admin-service/app/main.py"
click node_jobs "https://github.com/lahirusandeepa-lk/ai-assistent/blob/main/libs/admin/jobs.py"
click node_config_store "https://github.com/lahirusandeepa-lk/ai-assistent/blob/main/libs/llm/config_store.py"
click node_model_gateway "https://github.com/lahirusandeepa-lk/ai-assistent/blob/main/libs/llm/gateway.py"
click node_provider_chain "https://github.com/lahirusandeepa-lk/ai-assistent/blob/main/libs/llm/provider.py"
click node_conversation "https://github.com/lahirusandeepa-lk/ai-assistent/blob/main/libs/memory/conversation.py"
click node_usage "https://github.com/lahirusandeepa-lk/ai-assistent/blob/main/libs/memory/usage.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_public_ui,node_assistant_api,node_keycloak,node_rbac,node_user toneBlue
class node_agent_service,node_agent_graph,node_agent_ops,node_guardrails,node_tool_service,node_tool_runtime toneAmber
class node_retrieval_service,node_knowledge_index,node_ingestion_service,node_ingest_pipeline toneMint
class node_model_gateway,node_provider_chain,node_conversation,node_usage,node_redis,node_postgres,node_gemini,node_openai toneRose
class node_admin_ingest,node_admin_service,node_jobs,node_config_store toneIndigo
```

## Components

### User experience and edge

- [Public chat UI](https://github.com/lahirusandeepa-lk/ai-assistent/blob/main/services/ui-public/app.py): `services/ui-public/app.py`
- [Assistant API](https://github.com/lahirusandeepa-lk/ai-assistent/blob/main/services/ai-assistant-api/app/main.py): `services/ai-assistant-api/app/main.py`
- **Keycloak OIDC**
- [Role authorization](https://github.com/lahirusandeepa-lk/ai-assistent/blob/main/libs/authz/rbac.py): `libs/authz/rbac.py`

### Agent runtime

- [Orchestrator service](https://github.com/lahirusandeepa-lk/ai-assistent/blob/main/services/ai-orchestrator/app/main.py): `services/ai-orchestrator/app/main.py`
- [Agent graph](https://github.com/lahirusandeepa-lk/ai-assistent/blob/main/libs/orchestrator/graph.py): `libs/orchestrator/graph.py`
- [Agent operations](https://github.com/lahirusandeepa-lk/ai-assistent/blob/main/libs/orchestrator/ops.py): `libs/orchestrator/ops.py`
- [Input and output guardrails](https://github.com/lahirusandeepa-lk/ai-assistent/blob/main/libs/orchestrator/guardrails.py): `libs/orchestrator/guardrails.py`
- [Tool service](https://github.com/lahirusandeepa-lk/ai-assistent/blob/main/services/ai-tool-service/app/main.py): `services/ai-tool-service/app/main.py`
- [Tool runtime](https://github.com/lahirusandeepa-lk/ai-assistent/blob/main/libs/orchestrator/tools.py): `libs/orchestrator/tools.py`

### Knowledge management

- [Retrieval service](https://github.com/lahirusandeepa-lk/ai-assistent/blob/main/services/ai-knowledge-service/retrieval/app/main.py): `services/ai-knowledge-service/retrieval/app/main.py`
- [Hybrid knowledge index](https://github.com/lahirusandeepa-lk/ai-assistent/blob/main/libs/rag/store.py): `libs/rag/store.py`
- [Ingestion service](https://github.com/lahirusandeepa-lk/ai-assistent/blob/main/services/ai-knowledge-service/ingestion/app/main.py): `services/ai-knowledge-service/ingestion/app/main.py`
- [Document ingestion](https://github.com/lahirusandeepa-lk/ai-assistent/blob/main/libs/rag/ingest.py): `libs/rag/ingest.py`

### Models and state

- [Model gateway](https://github.com/lahirusandeepa-lk/ai-assistent/blob/main/libs/llm/gateway.py): `libs/llm/gateway.py`
- [Provider selection](https://github.com/lahirusandeepa-lk/ai-assistent/blob/main/libs/llm/provider.py): `libs/llm/provider.py`
- [Conversation memory](https://github.com/lahirusandeepa-lk/ai-assistent/blob/main/libs/memory/conversation.py): `libs/memory/conversation.py`
- [Token budgets](https://github.com/lahirusandeepa-lk/ai-assistent/blob/main/libs/memory/usage.py): `libs/memory/usage.py`
- **Redis**
- **Postgres**
- **Google Gemini**
- **OpenAI fallback**

### Administration

- [Upload job runner](https://github.com/lahirusandeepa-lk/ai-assistent/blob/main/libs/admin/ingest_runner.py): `libs/admin/ingest_runner.py`
- [Admin backend](https://github.com/lahirusandeepa-lk/ai-assistent/blob/main/services/ai-admin-service/app/main.py): `services/ai-admin-service/app/main.py`
- [Ingestion jobs](https://github.com/lahirusandeepa-lk/ai-assistent/blob/main/libs/admin/jobs.py): `libs/admin/jobs.py`
- [LLM configuration](https://github.com/lahirusandeepa-lk/ai-assistent/blob/main/libs/llm/config_store.py): `libs/llm/config_store.py`

### Other components

- **Chat user**

## Connections

- Chat user → Public chat UI: asks question
- Public chat UI → Assistant API: sends chat
- Assistant API → Keycloak OIDC: verifies identity
- Assistant API → Role authorization: checks roles (evidence: `services/ai-assistant-api/app/main.py`)
- Assistant API → Token budgets: checks token budget (evidence: `services/ai-assistant-api/app/main.py`)
- Assistant API → Orchestrator service: runs agent
- Orchestrator service → Agent graph: invokes graph (evidence: `services/ai-orchestrator/app/main.py`)
- Agent graph → Agent operations: dispatches operations (evidence: `libs/orchestrator/graph.py`)
- Agent graph → Input and output guardrails: applies guardrails (evidence: `libs/orchestrator/graph.py`)
- Agent operations → Retrieval service: searches knowledge
- Agent operations → Model gateway: requests completion (evidence: `libs/orchestrator/ops.py`)
- Agent operations → Conversation memory: uses session memory (evidence: `libs/orchestrator/ops.py`)
- Agent operations → Tool service: calls tools
- Tool service → Tool runtime: dispatches tools (evidence: `services/ai-tool-service/app/main.py`)
- Retrieval service → Hybrid knowledge index: searches index (evidence: `services/ai-knowledge-service/retrieval/app/main.py`)
- Ingestion service → Document ingestion: ingests documents (evidence: `services/ai-knowledge-service/ingestion/app/main.py`)
- Document ingestion → Hybrid knowledge index: writes chunks (evidence: `libs/rag/ingest.py`)
- Admin backend → Document ingestion: indexes text (evidence: `services/ai-admin-service/app/main.py`)
- Admin backend → Upload job runner: starts upload job (evidence: `services/ai-admin-service/app/main.py`)
- Upload job runner → Hybrid knowledge index: upserts chunks (evidence: `libs/admin/ingest_runner.py`)
- Upload job runner → Ingestion jobs: updates progress (evidence: `libs/admin/ingest_runner.py`)
- Admin backend → LLM configuration: manages providers (evidence: `services/ai-admin-service/app/main.py`)
- Model gateway → Provider selection: selects providers (evidence: `libs/llm/gateway.py`)
- Model gateway → Token budgets: meters tokens (evidence: `libs/llm/gateway.py`)
- Provider selection → LLM configuration: reads settings (evidence: `libs/llm/provider.py`)
- Provider selection → Google Gemini: calls primary
- Provider selection → OpenAI fallback: fails over
- Token budgets → Redis: stores counters (evidence: `libs/memory/usage.py`)
- Conversation memory → Postgres: persists history (evidence: `libs/memory/conversation.py`)