# edyoda/genai-aiagent architecture

> Architecture diagram of the GitHub repository edyoda/genai-aiagent, 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/edyoda/genai-aiagent
- Repository: https://github.com/edyoda/genai-aiagent

## Overview

This repository is a collection of GenAI agent examples rather than one unified application: standalone agents, MCP client/server demos, and document-processing experiments. The clearest user-to-result flow is a question entering an agent, which uses a model and tools before returning a response. The MCP demo adds OAuth-protected weather, document-search, and read-only SQL services. The README provides no feature map, so the graph preserves substantial modules listed in the source index; some subsystem links are omitted where sampled source does not establish runtime wiring.

Main entry points: [`src/projects/mcp-demo/server/docs_server/server.py`](https://github.com/edyoda/genai-aiagent/blob/main/src/projects/mcp-demo/server/docs_server/server.py) (Document search), [`src/projects/mcp-demo/server/common/config.py`](https://github.com/edyoda/genai-aiagent/blob/main/src/projects/mcp-demo/server/common/config.py) (Server configuration), [`src/projects/mcp-demo/server/weather_server/server.py`](https://github.com/edyoda/genai-aiagent/blob/main/src/projects/mcp-demo/server/weather_server/server.py) (Weather tools), [`src/projects/mcp-demo/server/sql_server/server.py`](https://github.com/edyoda/genai-aiagent/blob/main/src/projects/mcp-demo/server/sql_server/server.py) (SQL analytics)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_agents["Agent examples"]
  node_deep_entry["Deep agent app<br/>[main.py]"]
  node_deep_runtime["Agent runtime<br/>[agent.py]"]
  node_deep_model["Model factory<br/>[models.py]"]
  node_deep_tools["Custom tools<br/>[tools.py]"]
  node_skills["Skills agent<br/>[agent.py]"]
  node_skills_app["Skills app<br/>[main.py]"]
  node_hitl_agent["Human-review agent<br/>[agent.py]"]
  node_hitl_models["Review models<br/>[models.py]"]
  node_hitl_app["Review app<br/>[main.py]"]
end

subgraph group_mcp_clients["MCP clients"]
  node_codebase_ui["Codebase chat UI<br/>[streamlit_app.py]"]
  node_sqlite_client["SQLite MCP client<br/>[client.py]"]
  node_test_client["Tool demo client<br/>[client.py]"]
  node_model_instance["Model instance<br/>[model_instance.py]"]
  node_mcp_demo_app["MCP demo client<br/>[main.py]"]
  node_mcp_connections["MCP connections<br/>[mcp_connections.py]"]
  node_mcp_auth_client["Client auth<br/>[auth.py]"]
end

subgraph group_mcp_servers["MCP services"]
  node_server_supervisor["Server supervisor<br/>[main.py]"]
  node_auth_service["OAuth issuer<br/>[app.py]"]
  node_server_config["Server configuration<br/>[config.py]"]
  node_token_verifier["Token verifier<br/>[auth.py]"]
  node_server_runtime["Server runtime<br/>[serve.py]"]
  node_request_logs["Request logging<br/>[logs.py]"]
  node_weather_service["Weather tools<br/>[server.py]"]
  node_docs_service["Document search<br/>[server.py]"]
  node_docs_store[("Document index store<br/>[store.py]")]
  node_sql_service["SQL analytics<br/>[server.py]"]
  node_sql_seed["SQL database seeding<br/>[seed_db.py]"]
end

subgraph group_documents["Document processing"]
  node_doc_processor["Document processing"]
  node_response_generator["Response generation"]
  node_inference["Inference and vectors<br/>[model_inference.py]"]
end

node_user(("User"))

node_user -->|"asks"| node_deep_entry
node_deep_entry -->|"builds agent"| node_deep_runtime
node_deep_entry -->|"uses model"| node_deep_model
node_deep_runtime -->|"builds with"| node_deep_model
node_deep_runtime -->|"loads tools"| node_deep_tools
node_skills -->|"uses model"| node_deep_model
node_skills -->|"uses tools"| node_deep_tools
node_skills_app -->|"uses runtime"| node_deep_runtime
node_skills_app -->|"uses model"| node_deep_model
node_hitl_agent -->|"uses models"| node_hitl_models
node_hitl_app -->|"uses agent"| node_hitl_agent
node_hitl_app -->|"uses models"| node_hitl_models
node_codebase_ui -->|"invokes"| node_sqlite_client
node_codebase_ui -->|"invokes"| node_test_client
node_sqlite_client -->|"uses model"| node_model_instance
node_test_client -->|"uses model"| node_model_instance
node_user -->|"asks"| node_mcp_demo_app
node_mcp_demo_app -->|"uses agent"| node_deep_runtime
node_mcp_demo_app -->|"uses model"| node_deep_model
node_mcp_demo_app -->|"opens connections"| node_mcp_connections
node_mcp_connections -->|"uses auth"| node_mcp_auth_client
node_server_supervisor -->|"starts service"| node_auth_service
node_server_supervisor -->|"starts service"| node_weather_service
node_server_supervisor -->|"starts service"| node_docs_service
node_server_supervisor -->|"starts service"| node_sql_service
node_auth_service -->|"reads settings"| node_server_config
node_token_verifier -->|"reads settings"| node_server_config
node_server_runtime -->|"reads settings"| node_server_config
node_weather_service -->|"configures auth"| node_token_verifier
node_weather_service -->|"reads settings"| node_server_config
node_weather_service -->|"uses logging"| node_request_logs
node_weather_service -->|"runs through"| node_server_runtime
node_docs_service -->|"configures auth"| node_token_verifier
node_docs_service -->|"reads settings"| node_server_config
node_docs_service -->|"uses logging"| node_request_logs
node_docs_service -->|"searches index"| node_docs_store
node_docs_service -->|"runs through"| node_server_runtime
node_sql_service -->|"configures auth"| node_token_verifier
node_sql_service -->|"reads settings"| node_server_config
node_sql_service -->|"uses logging"| node_request_logs
node_sql_service -->|"runs through"| node_server_runtime
node_sql_seed -->|"reads settings"| node_server_config
node_doc_processor -->|"uses inference"| node_inference
node_response_generator -->|"uses inference"| node_inference

click node_deep_entry "https://github.com/edyoda/genai-aiagent/blob/main/src/deepagents/main.py"
click node_deep_runtime "https://github.com/edyoda/genai-aiagent/blob/main/src/deepagents/agent.py"
click node_deep_model "https://github.com/edyoda/genai-aiagent/blob/main/src/deepagents/models.py"
click node_deep_tools "https://github.com/edyoda/genai-aiagent/blob/main/src/deepagents/tools.py"
click node_skills "https://github.com/edyoda/genai-aiagent/blob/main/src/agent-with-skills/agent.py"
click node_skills_app "https://github.com/edyoda/genai-aiagent/blob/main/src/agent-with-skills/main.py"
click node_hitl_agent "https://github.com/edyoda/genai-aiagent/blob/main/src/hitl_agent/agent.py"
click node_hitl_models "https://github.com/edyoda/genai-aiagent/blob/main/src/hitl_agent/models.py"
click node_hitl_app "https://github.com/edyoda/genai-aiagent/blob/main/src/hitl_agent/main.py"
click node_codebase_ui "https://github.com/edyoda/genai-aiagent/blob/main/src/mcp_codebase/streamlit_app.py"
click node_sqlite_client "https://github.com/edyoda/genai-aiagent/blob/main/src/mcp_codebase/sqlite_server/client.py"
click node_test_client "https://github.com/edyoda/genai-aiagent/blob/main/src/mcp_codebase/test_servers/client.py"
click node_model_instance "https://github.com/edyoda/genai-aiagent/blob/main/src/mcp_codebase/model_instance.py"
click node_mcp_demo_app "https://github.com/edyoda/genai-aiagent/blob/main/src/projects/mcp-demo/client/main.py"
click node_mcp_connections "https://github.com/edyoda/genai-aiagent/blob/main/src/projects/mcp-demo/client/mcp_connections.py"
click node_mcp_auth_client "https://github.com/edyoda/genai-aiagent/blob/main/src/projects/mcp-demo/client/auth.py"
click node_server_supervisor "https://github.com/edyoda/genai-aiagent/blob/main/src/projects/mcp-demo/server/main.py"
click node_auth_service "https://github.com/edyoda/genai-aiagent/blob/main/src/projects/mcp-demo/server/auth_server/app.py"
click node_server_config "https://github.com/edyoda/genai-aiagent/blob/main/src/projects/mcp-demo/server/common/config.py"
click node_token_verifier "https://github.com/edyoda/genai-aiagent/blob/main/src/projects/mcp-demo/server/common/auth.py"
click node_server_runtime "https://github.com/edyoda/genai-aiagent/blob/main/src/projects/mcp-demo/server/common/serve.py"
click node_request_logs "https://github.com/edyoda/genai-aiagent/blob/main/src/projects/mcp-demo/server/common/logs.py"
click node_weather_service "https://github.com/edyoda/genai-aiagent/blob/main/src/projects/mcp-demo/server/weather_server/server.py"
click node_docs_service "https://github.com/edyoda/genai-aiagent/blob/main/src/projects/mcp-demo/server/docs_server/server.py"
click node_docs_store "https://github.com/edyoda/genai-aiagent/blob/main/src/projects/mcp-demo/server/docs_server/store.py"
click node_sql_service "https://github.com/edyoda/genai-aiagent/blob/main/src/projects/mcp-demo/server/sql_server/server.py"
click node_sql_seed "https://github.com/edyoda/genai-aiagent/blob/main/src/projects/mcp-demo/server/sql_server/seed_db.py"
click node_doc_processor "https://github.com/edyoda/genai-aiagent/blob/main/src/projects/unstructured_documents/process_document.py"
click node_response_generator "https://github.com/edyoda/genai-aiagent/blob/main/src/projects/unstructured_documents/generate_response.py"
click node_inference "https://github.com/edyoda/genai-aiagent/blob/main/src/projects/unstructured_documents/model_inference.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_deep_entry,node_deep_runtime,node_deep_model,node_deep_tools,node_skills,node_skills_app,node_hitl_agent,node_hitl_models,node_hitl_app,node_user toneBlue
class node_codebase_ui,node_sqlite_client,node_test_client,node_model_instance,node_mcp_demo_app,node_mcp_connections,node_mcp_auth_client toneAmber
class node_server_supervisor,node_auth_service,node_server_config,node_token_verifier,node_server_runtime,node_request_logs,node_weather_service,node_docs_service,node_docs_store,node_sql_service,node_sql_seed toneMint
class node_doc_processor,node_response_generator,node_inference toneRose
```

## Components

### Agent examples

- [Deep agent app](https://github.com/edyoda/genai-aiagent/blob/main/src/deepagents/main.py): `src/deepagents/main.py`
- [Agent runtime](https://github.com/edyoda/genai-aiagent/blob/main/src/deepagents/agent.py): `src/deepagents/agent.py`
- [Model factory](https://github.com/edyoda/genai-aiagent/blob/main/src/deepagents/models.py): `src/deepagents/models.py`
- [Custom tools](https://github.com/edyoda/genai-aiagent/blob/main/src/deepagents/tools.py): `src/deepagents/tools.py`
- [Skills agent](https://github.com/edyoda/genai-aiagent/blob/main/src/agent-with-skills/agent.py): `src/agent-with-skills/agent.py`
- [Skills app](https://github.com/edyoda/genai-aiagent/blob/main/src/agent-with-skills/main.py): `src/agent-with-skills/main.py`
- [Human-review agent](https://github.com/edyoda/genai-aiagent/blob/main/src/hitl_agent/agent.py): `src/hitl_agent/agent.py`
- [Review models](https://github.com/edyoda/genai-aiagent/blob/main/src/hitl_agent/models.py): `src/hitl_agent/models.py`
- [Review app](https://github.com/edyoda/genai-aiagent/blob/main/src/hitl_agent/main.py): `src/hitl_agent/main.py`

### MCP clients

- [Codebase chat UI](https://github.com/edyoda/genai-aiagent/blob/main/src/mcp_codebase/streamlit_app.py): `src/mcp_codebase/streamlit_app.py`
- [SQLite MCP client](https://github.com/edyoda/genai-aiagent/blob/main/src/mcp_codebase/sqlite_server/client.py): `src/mcp_codebase/sqlite_server/client.py`
- [Tool demo client](https://github.com/edyoda/genai-aiagent/blob/main/src/mcp_codebase/test_servers/client.py): `src/mcp_codebase/test_servers/client.py`
- [Model instance](https://github.com/edyoda/genai-aiagent/blob/main/src/mcp_codebase/model_instance.py): `src/mcp_codebase/model_instance.py`
- [MCP demo client](https://github.com/edyoda/genai-aiagent/blob/main/src/projects/mcp-demo/client/main.py): `src/projects/mcp-demo/client/main.py`
- [MCP connections](https://github.com/edyoda/genai-aiagent/blob/main/src/projects/mcp-demo/client/mcp_connections.py): `src/projects/mcp-demo/client/mcp_connections.py`
- [Client auth](https://github.com/edyoda/genai-aiagent/blob/main/src/projects/mcp-demo/client/auth.py): `src/projects/mcp-demo/client/auth.py`

### MCP services

- [Server supervisor](https://github.com/edyoda/genai-aiagent/blob/main/src/projects/mcp-demo/server/main.py): `src/projects/mcp-demo/server/main.py`
- [OAuth issuer](https://github.com/edyoda/genai-aiagent/blob/main/src/projects/mcp-demo/server/auth_server/app.py): `src/projects/mcp-demo/server/auth_server/app.py`
- [Server configuration](https://github.com/edyoda/genai-aiagent/blob/main/src/projects/mcp-demo/server/common/config.py): `src/projects/mcp-demo/server/common/config.py`
- [Token verifier](https://github.com/edyoda/genai-aiagent/blob/main/src/projects/mcp-demo/server/common/auth.py): `src/projects/mcp-demo/server/common/auth.py`
- [Server runtime](https://github.com/edyoda/genai-aiagent/blob/main/src/projects/mcp-demo/server/common/serve.py): `src/projects/mcp-demo/server/common/serve.py`
- [Request logging](https://github.com/edyoda/genai-aiagent/blob/main/src/projects/mcp-demo/server/common/logs.py): `src/projects/mcp-demo/server/common/logs.py`
- [Weather tools](https://github.com/edyoda/genai-aiagent/blob/main/src/projects/mcp-demo/server/weather_server/server.py): `src/projects/mcp-demo/server/weather_server/server.py`
- [Document search](https://github.com/edyoda/genai-aiagent/blob/main/src/projects/mcp-demo/server/docs_server/server.py): `src/projects/mcp-demo/server/docs_server/server.py`
- [Document index store](https://github.com/edyoda/genai-aiagent/blob/main/src/projects/mcp-demo/server/docs_server/store.py): `src/projects/mcp-demo/server/docs_server/store.py`
- [SQL analytics](https://github.com/edyoda/genai-aiagent/blob/main/src/projects/mcp-demo/server/sql_server/server.py): `src/projects/mcp-demo/server/sql_server/server.py`
- [SQL database seeding](https://github.com/edyoda/genai-aiagent/blob/main/src/projects/mcp-demo/server/sql_server/seed_db.py): `src/projects/mcp-demo/server/sql_server/seed_db.py`

### Document processing

- [Document processing](https://github.com/edyoda/genai-aiagent/blob/main/src/projects/unstructured_documents/process_document.py): `src/projects/unstructured_documents/process_document.py`
- [Response generation](https://github.com/edyoda/genai-aiagent/blob/main/src/projects/unstructured_documents/generate_response.py): `src/projects/unstructured_documents/generate_response.py`
- [Inference and vectors](https://github.com/edyoda/genai-aiagent/blob/main/src/projects/unstructured_documents/model_inference.py): `src/projects/unstructured_documents/model_inference.py`

### Other components

- **User**

## Connections

- User → Deep agent app: asks (evidence: `src/deepagents/main.py`)
- Deep agent app → Agent runtime: builds agent (evidence: `src/deepagents/main.py`)
- Deep agent app → Model factory: uses model (evidence: `src/deepagents/main.py`)
- Agent runtime → Model factory: builds with (evidence: `src/deepagents/agent.py`)
- Agent runtime → Custom tools: loads tools (evidence: `src/deepagents/agent.py`)
- Skills agent → Model factory: uses model (evidence: `src/agent-with-skills/agent.py`)
- Skills agent → Custom tools: uses tools (evidence: `src/agent-with-skills/agent.py`)
- Skills app → Agent runtime: uses runtime (evidence: `src/agent-with-skills/main.py`)
- Skills app → Model factory: uses model (evidence: `src/agent-with-skills/main.py`)
- Human-review agent → Review models: uses models (evidence: `src/hitl_agent/agent.py`)
- Review app → Human-review agent: uses agent (evidence: `src/hitl_agent/main.py`)
- Review app → Review models: uses models (evidence: `src/hitl_agent/main.py`)
- Codebase chat UI → SQLite MCP client: invokes (evidence: `src/mcp_codebase/streamlit_app.py`)
- Codebase chat UI → Tool demo client: invokes (evidence: `src/mcp_codebase/streamlit_app.py`)
- SQLite MCP client → Model instance: uses model (evidence: `src/mcp_codebase/sqlite_server/client.py`)
- Tool demo client → Model instance: uses model (evidence: `src/mcp_codebase/test_servers/client.py`)
- User → MCP demo client: asks (evidence: `src/projects/mcp-demo/client/main.py`)
- MCP demo client → Agent runtime: uses agent (evidence: `src/projects/mcp-demo/client/main.py`)
- MCP demo client → Model factory: uses model (evidence: `src/projects/mcp-demo/client/main.py`)
- MCP demo client → MCP connections: opens connections (evidence: `src/projects/mcp-demo/client/main.py`)
- MCP connections → Client auth: uses auth (evidence: `src/projects/mcp-demo/client/mcp_connections.py`)
- Server supervisor → OAuth issuer: starts service (evidence: `src/projects/mcp-demo/server/main.py`)
- Server supervisor → Weather tools: starts service (evidence: `src/projects/mcp-demo/server/main.py`)
- Server supervisor → Document search: starts service (evidence: `src/projects/mcp-demo/server/main.py`)
- Server supervisor → SQL analytics: starts service (evidence: `src/projects/mcp-demo/server/main.py`)
- OAuth issuer → Server configuration: reads settings (evidence: `src/projects/mcp-demo/server/auth_server/app.py`)
- Token verifier → Server configuration: reads settings (evidence: `src/projects/mcp-demo/server/common/auth.py`)
- Server runtime → Server configuration: reads settings (evidence: `src/projects/mcp-demo/server/common/serve.py`)
- Weather tools → Token verifier: configures auth (evidence: `src/projects/mcp-demo/server/weather_server/server.py`)
- Weather tools → Server configuration: reads settings (evidence: `src/projects/mcp-demo/server/weather_server/server.py`)
- Weather tools → Request logging: uses logging (evidence: `src/projects/mcp-demo/server/weather_server/server.py`)
- Weather tools → Server runtime: runs through (evidence: `src/projects/mcp-demo/server/weather_server/server.py`)
- Document search → Token verifier: configures auth (evidence: `src/projects/mcp-demo/server/docs_server/server.py`)
- Document search → Server configuration: reads settings (evidence: `src/projects/mcp-demo/server/docs_server/server.py`)
- Document search → Request logging: uses logging (evidence: `src/projects/mcp-demo/server/docs_server/server.py`)
- Document search → Document index store: searches index (evidence: `src/projects/mcp-demo/server/docs_server/server.py`)
- Document search → Server runtime: runs through (evidence: `src/projects/mcp-demo/server/docs_server/server.py`)
- SQL analytics → Token verifier: configures auth (evidence: `src/projects/mcp-demo/server/sql_server/server.py`)
- SQL analytics → Server configuration: reads settings (evidence: `src/projects/mcp-demo/server/sql_server/server.py`)
- SQL analytics → Request logging: uses logging (evidence: `src/projects/mcp-demo/server/sql_server/server.py`)
- SQL analytics → Server runtime: runs through (evidence: `src/projects/mcp-demo/server/sql_server/server.py`)
- SQL database seeding → Server configuration: reads settings (evidence: `src/projects/mcp-demo/server/sql_server/seed_db.py`)
- Document processing → Inference and vectors: uses inference (evidence: `src/projects/unstructured_documents/process_document.py`)
- Response generation → Inference and vectors: uses inference (evidence: `src/projects/unstructured_documents/generate_response.py`)