# ivancordonm/agentic-platform-starter-kit architecture

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

- Interactive diagram: https://gitdiagram.com/ivancordonm/agentic-platform-starter-kit
- Repository: https://github.com/ivancordonm/agentic-platform-starter-kit

## Overview

This is a configuration-first platform for building and running agent applications. The main workflow is: a caller submits input to the API, the API selects a versioned project runtime, and either an individual agent or a configured graph/orchestrator workflow executes; run results and events are retained for inspection. Project loading validates configuration and resolves models, prompts, schemas, and tools before execution. The Streamlit UI uses the API for project controls, execution, and traces. The README documents additional workflow modes, authentication, reload, and optional SQLite storage; unsampled details are represented only where documented.

Main entry points: [`app/api/routes.py`](https://github.com/ivancordonm/agentic-platform-starter-kit/blob/main/app/api/routes.py) (API routes), [`app/engine/project_runtime.py`](https://github.com/ivancordonm/agentic-platform-starter-kit/blob/main/app/engine/project_runtime.py) (Project runtime), [`app/engine/agent_executor.py`](https://github.com/ivancordonm/agentic-platform-starter-kit/blob/main/app/engine/agent_executor.py) (Agent executor), [`app/engine/runtime_manager.py`](https://github.com/ivancordonm/agentic-platform-starter-kit/blob/main/app/engine/runtime_manager.py) (Runtime manager)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_boundary["API and UI"]
  node_ui["Developer UI<br/>[streamlit_app.py]"]
  node_http_client["HTTP client<br/>[client.py]"]
  node_api["API routes<br/>[routes.py]"]
  node_contracts["HTTP contracts<br/>[models.py]"]
end

subgraph group_runtime["Runtime and configuration"]
  node_runtime_manager["Runtime manager<br/>[runtime_manager.py]"]
  node_project_runtime["Project runtime<br/>[project_runtime.py]"]
  node_config_loader["Config loading<br/>[config.py]"]
  node_definitions["Config definitions<br/>[definitions.py]"]
  node_agent_registry["Agent registry<br/>[agent_registry.py]"]
  node_model_registry["Model registry<br/>[model_registry.py]"]
  node_prompt_loader["Prompt loading<br/>[prompt_loader.py]"]
  node_schema_loader["Schema loading<br/>[schema_loader.py]"]
  node_tool_registry["Tool registry<br/>[tool_registry.py]"]
  node_project_files["Project definitions"]
end

subgraph group_execution["Agent execution"]
  node_agent_executor["Agent executor<br/>[agent_executor.py]"]
  node_agent_factory["Agent factory<br/>[agent_factory.py]"]
  node_workflow_executor["Workflow executor"]
end

subgraph group_observability["Run records"]
  node_run_repository[("Run repository<br/>[run_store.py]")]
  node_sqlite_store[("SQLite run store")]
end

node_caller(("API caller"))
node_model_service(("OpenAI model service"))
node_mcp_service(("MCP tool service"))

node_caller -->|"submits requests"| node_api
node_ui -->|"uses"| node_http_client
node_http_client -->|"calls API"| node_api
node_api -->|"validates requests"| node_contracts
node_api -->|"selects snapshot"| node_runtime_manager
node_api -->|"runs agent"| node_agent_executor
node_api -->|"runs workflow"| node_workflow_executor
node_runtime_manager -->|"builds runtime"| node_project_runtime
node_runtime_manager -->|"builds executor"| node_agent_executor
node_runtime_manager -->|"builds executor"| node_workflow_executor
node_project_runtime -->|"loads configuration"| node_config_loader
node_project_runtime -->|"initializes registry"| node_agent_registry
node_project_runtime -->|"initializes registry"| node_model_registry
node_project_runtime -->|"initializes loader"| node_prompt_loader
node_project_runtime -->|"initializes loader"| node_schema_loader
node_project_runtime -->|"initializes registry"| node_tool_registry
node_config_loader -->|"validates against"| node_definitions
node_config_loader -.->|"reads project config"| node_project_files
node_agent_executor -->|"builds agent"| node_agent_factory
node_agent_executor -->|"opens MCP tools"| node_tool_registry
node_agent_executor -.->|"invokes model"| node_model_service
node_tool_registry -.->|"connects to MCP"| node_mcp_service
node_workflow_executor -->|"runs workflow agents"| node_agent_executor
node_api -->|"records run events"| node_run_repository
node_api -->|"selects when configured"| node_sqlite_store
node_api -.->|"serves API responses"| node_http_client

click node_ui "https://github.com/ivancordonm/agentic-platform-starter-kit/blob/main/app/ui/streamlit_app.py"
click node_http_client "https://github.com/ivancordonm/agentic-platform-starter-kit/blob/main/app/ui/client.py"
click node_api "https://github.com/ivancordonm/agentic-platform-starter-kit/blob/main/app/api/routes.py"
click node_contracts "https://github.com/ivancordonm/agentic-platform-starter-kit/blob/main/app/api/models.py"
click node_runtime_manager "https://github.com/ivancordonm/agentic-platform-starter-kit/blob/main/app/engine/runtime_manager.py"
click node_project_runtime "https://github.com/ivancordonm/agentic-platform-starter-kit/blob/main/app/engine/project_runtime.py"
click node_config_loader "https://github.com/ivancordonm/agentic-platform-starter-kit/blob/main/app/engine/config.py"
click node_definitions "https://github.com/ivancordonm/agentic-platform-starter-kit/blob/main/app/engine/definitions.py"
click node_agent_registry "https://github.com/ivancordonm/agentic-platform-starter-kit/blob/main/app/engine/agent_registry.py"
click node_model_registry "https://github.com/ivancordonm/agentic-platform-starter-kit/blob/main/app/engine/model_registry.py"
click node_prompt_loader "https://github.com/ivancordonm/agentic-platform-starter-kit/blob/main/app/engine/prompt_loader.py"
click node_schema_loader "https://github.com/ivancordonm/agentic-platform-starter-kit/blob/main/app/engine/schema_loader.py"
click node_tool_registry "https://github.com/ivancordonm/agentic-platform-starter-kit/blob/main/app/engine/tool_registry.py"
click node_project_files "https://github.com/ivancordonm/agentic-platform-starter-kit/tree/main/project"
click node_agent_executor "https://github.com/ivancordonm/agentic-platform-starter-kit/blob/main/app/engine/agent_executor.py"
click node_agent_factory "https://github.com/ivancordonm/agentic-platform-starter-kit/blob/main/app/engine/agent_factory.py"
click node_workflow_executor "https://github.com/ivancordonm/agentic-platform-starter-kit/blob/main/app/engine/workflow_executor.py"
click node_run_repository "https://github.com/ivancordonm/agentic-platform-starter-kit/blob/main/app/engine/run_store.py"
click node_sqlite_store "https://github.com/ivancordonm/agentic-platform-starter-kit/blob/main/app/engine/sqlite_run_store.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_ui,node_http_client,node_api,node_contracts toneBlue
class node_runtime_manager,node_project_runtime,node_config_loader,node_definitions,node_agent_registry,node_model_registry,node_prompt_loader,node_schema_loader,node_tool_registry,node_project_files toneAmber
class node_agent_executor,node_agent_factory,node_workflow_executor,node_caller toneMint
class node_run_repository,node_sqlite_store toneRose
class node_model_service,node_mcp_service toneIndigo
```

## Components

### API and UI

- [Developer UI](https://github.com/ivancordonm/agentic-platform-starter-kit/blob/main/app/ui/streamlit_app.py): `app/ui/streamlit_app.py`
- [HTTP client](https://github.com/ivancordonm/agentic-platform-starter-kit/blob/main/app/ui/client.py): `app/ui/client.py`
- [API routes](https://github.com/ivancordonm/agentic-platform-starter-kit/blob/main/app/api/routes.py): `app/api/routes.py`
- [HTTP contracts](https://github.com/ivancordonm/agentic-platform-starter-kit/blob/main/app/api/models.py): `app/api/models.py`

### Runtime and configuration

- [Runtime manager](https://github.com/ivancordonm/agentic-platform-starter-kit/blob/main/app/engine/runtime_manager.py): `app/engine/runtime_manager.py`
- [Project runtime](https://github.com/ivancordonm/agentic-platform-starter-kit/blob/main/app/engine/project_runtime.py): `app/engine/project_runtime.py`
- [Config loading](https://github.com/ivancordonm/agentic-platform-starter-kit/blob/main/app/engine/config.py): `app/engine/config.py`
- [Config definitions](https://github.com/ivancordonm/agentic-platform-starter-kit/blob/main/app/engine/definitions.py): `app/engine/definitions.py`
- [Agent registry](https://github.com/ivancordonm/agentic-platform-starter-kit/blob/main/app/engine/agent_registry.py): `app/engine/agent_registry.py`
- [Model registry](https://github.com/ivancordonm/agentic-platform-starter-kit/blob/main/app/engine/model_registry.py): `app/engine/model_registry.py`
- [Prompt loading](https://github.com/ivancordonm/agentic-platform-starter-kit/blob/main/app/engine/prompt_loader.py): `app/engine/prompt_loader.py`
- [Schema loading](https://github.com/ivancordonm/agentic-platform-starter-kit/blob/main/app/engine/schema_loader.py): `app/engine/schema_loader.py`
- [Tool registry](https://github.com/ivancordonm/agentic-platform-starter-kit/blob/main/app/engine/tool_registry.py): `app/engine/tool_registry.py`
- [Project definitions](https://github.com/ivancordonm/agentic-platform-starter-kit/tree/main/project): `project`

### Agent execution

- [Agent executor](https://github.com/ivancordonm/agentic-platform-starter-kit/blob/main/app/engine/agent_executor.py): `app/engine/agent_executor.py`
- [Agent factory](https://github.com/ivancordonm/agentic-platform-starter-kit/blob/main/app/engine/agent_factory.py): `app/engine/agent_factory.py`
- [Workflow executor](https://github.com/ivancordonm/agentic-platform-starter-kit/blob/main/app/engine/workflow_executor.py): `app/engine/workflow_executor.py`

### Run records

- [Run repository](https://github.com/ivancordonm/agentic-platform-starter-kit/blob/main/app/engine/run_store.py): `app/engine/run_store.py`
- [SQLite run store](https://github.com/ivancordonm/agentic-platform-starter-kit/blob/main/app/engine/sqlite_run_store.py): `app/engine/sqlite_run_store.py`

### Other components

- **API caller**
- **OpenAI model service**
- **MCP tool service**

## Connections

- API caller → API routes: submits requests (evidence: `README.md`)
- Developer UI → HTTP client: uses (evidence: `app/ui/streamlit_app.py`)
- HTTP client → API routes: calls API (evidence: `README.md`)
- API routes → HTTP contracts: validates requests (evidence: `app/api/routes.py`)
- API routes → Runtime manager: selects snapshot (evidence: `app/api/routes.py`)
- API routes → Agent executor: runs agent (evidence: `app/api/routes.py`)
- API routes → Workflow executor: runs workflow (evidence: `app/api/routes.py`)
- Runtime manager → Project runtime: builds runtime (evidence: `app/engine/runtime_manager.py`)
- Runtime manager → Agent executor: builds executor (evidence: `app/engine/runtime_manager.py`)
- Runtime manager → Workflow executor: builds executor (evidence: `app/engine/runtime_manager.py`)
- Project runtime → Config loading: loads configuration (evidence: `app/engine/project_runtime.py`)
- Project runtime → Agent registry: initializes registry (evidence: `app/engine/project_runtime.py`)
- Project runtime → Model registry: initializes registry (evidence: `app/engine/project_runtime.py`)
- Project runtime → Prompt loading: initializes loader (evidence: `app/engine/project_runtime.py`)
- Project runtime → Schema loading: initializes loader (evidence: `app/engine/project_runtime.py`)
- Project runtime → Tool registry: initializes registry (evidence: `app/engine/project_runtime.py`)
- Config loading → Config definitions: validates against (evidence: `app/engine/config.py`)
- Config loading → Project definitions: reads project config (evidence: `README.md`)
- Agent executor → Agent factory: builds agent (evidence: `app/engine/agent_executor.py`)
- Agent executor → Tool registry: opens MCP tools (evidence: `app/engine/agent_executor.py`)
- Agent executor → OpenAI model service: invokes model (evidence: `README.md`)
- Tool registry → MCP tool service: connects to MCP (evidence: `README.md`)
- Workflow executor → Agent executor: runs workflow agents (evidence: `app/engine/workflow_executor.py`)
- API routes → Run repository: records run events (evidence: `app/api/routes.py`)
- API routes → SQLite run store: selects when configured (evidence: `app/api/routes.py`)
- API routes → HTTP client: serves API responses (evidence: `README.md`)
