# phani465/agentforge architecture

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

## Overview

AgentForge is a platform for defining agents, executing governed multi-step runs, evaluating changes, and inspecting costs and traces. The main workflow is dashboard or API client → gateway → runtime → persisted run and trace; evaluation suites take a separate gateway-to-evaluation-service path. The graph also preserves authentication, SDK, and dashboard capabilities. Several service connections are documented in the README or source index; unsampled implementations and integrations are shown only where documented.

Main entry points: [`services/api-gateway/main.py`](https://github.com/phani465/agentforge/blob/main/services/api-gateway/main.py) (API gateway), [`services/agent-runtime/engine.py`](https://github.com/phani465/agentforge/blob/main/services/agent-runtime/engine.py) (Agent execution loop), [`packages/common/agentforge_common/db.py`](https://github.com/phani465/agentforge/blob/main/packages/common/agentforge_common/db.py) (Database sessions), [`dashboard/src/api/client.ts`](https://github.com/phani465/agentforge/blob/main/dashboard/src/api/client.ts) (Dashboard API client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["User Experience"]
  node_dashboard["Dashboard routes<br/>[App.tsx]"]
  node_dashboard_auth["Dashboard auth<br/>[auth.tsx]"]
  node_dashboard_api["Dashboard API client<br/>[client.ts]"]
  node_dashboard_pages["Agent, trace, eval, analytics, settings"]
  node_sdk["Python SDK"]
  node_cli["Go CLI"]
end

subgraph group_gateway["API and Identity"]
  node_gateway["API gateway<br/>[main.py]"]
  node_agent_routes["Agent management<br/>[agents.py]"]
  node_run_routes["Run orchestration<br/>[runs.py]"]
  node_eval_routes["Evaluation routes<br/>[evals.py]"]
  node_analytics_traces["Analytics and traces"]
  node_auth_service["Login and token issuer<br/>[main.go]"]
  node_gateway_dependencies["Gateway auth dependencies<br/>[dependencies.py]"]
end

subgraph group_execution["Agent Execution"]
  node_runtime["Agent execution loop<br/>[engine.py]"]
  node_runtime_http["Runtime API<br/>[runs.py]"]
  node_runtime_controls["Safety, scope, tools"]
  node_runtime_optimization["Routing and compression<br/>[routing.py]"]
  node_trace_collector["Trace collector<br/>[main.py]"]
end

subgraph group_evaluation["Evaluation"]
  node_eval_service["Evaluation runner and scoring<br/>[runner.py]"]
end

subgraph group_data["Shared Data"]
  node_common_models["Shared domain models<br/>[models.py]"]
  node_orm["Persistence mappings<br/>[orm.py]"]
  node_db_setup["Database sessions<br/>[db.py]"]
  node_shared_security["Shared security and errors<br/>[security.py]"]
end

node_user(("User"))
node_llm["LLM provider"]
node_postgres[("PostgreSQL")]
node_redis[("Redis cache")]

node_user -->|"uses"| node_dashboard
node_dashboard -->|"provides auth"| node_dashboard_auth
node_dashboard -->|"routes to"| node_dashboard_pages
node_dashboard_pages -->|"requests data"| node_dashboard_api
node_dashboard_auth -->|"uses key storage"| node_dashboard_api
node_dashboard_api -->|"calls API"| node_gateway
node_dashboard_api -->|"auth requests"| node_auth_service
node_sdk -.->|"uses platform API"| node_gateway
node_cli -.->|"uses platform API"| node_gateway
node_gateway -->|"registers routes"| node_agent_routes
node_gateway -->|"registers routes"| node_run_routes
node_gateway -->|"registers routes"| node_eval_routes
node_gateway -->|"registers routes"| node_analytics_traces
node_run_routes -->|"posts run"| node_runtime_http
node_runtime_http -.->|"executes run"| node_runtime
node_runtime -->|"applies controls"| node_runtime_controls
node_runtime -->|"uses optimization"| node_runtime_optimization
node_runtime -->|"requests completions"| node_llm
node_runtime -->|"exports traces"| node_trace_collector
node_eval_routes -->|"posts suite"| node_eval_service
node_eval_service -.->|"executes agent"| node_runtime
node_gateway -->|"uses sessions"| node_db_setup
node_runtime_http -.->|"uses sessions"| node_db_setup
node_eval_service -->|"uses sessions"| node_db_setup
node_trace_collector -->|"uses sessions"| node_db_setup
node_db_setup -->|"connects"| node_postgres
node_orm -->|"uses base"| node_db_setup
node_gateway -.->|"persists domain data"| node_orm
node_runtime -->|"uses response cache"| node_redis
node_runtime -->|"uses run models"| node_common_models
node_orm -.->|"maps domain models"| node_common_models
node_gateway -.->|"uses auth dependencies"| node_gateway_dependencies
node_gateway_dependencies -.->|"checks credentials"| node_shared_security
node_auth_service -->|"reads and writes users"| node_postgres

click node_dashboard "https://github.com/phani465/agentforge/blob/main/dashboard/src/App.tsx"
click node_dashboard_auth "https://github.com/phani465/agentforge/blob/main/dashboard/src/lib/auth.tsx"
click node_dashboard_api "https://github.com/phani465/agentforge/blob/main/dashboard/src/api/client.ts"
click node_dashboard_pages "https://github.com/phani465/agentforge/tree/main/dashboard/src/pages"
click node_sdk "https://github.com/phani465/agentforge/tree/main/packages/sdk/agentforge"
click node_cli "https://github.com/phani465/agentforge/tree/main/packages/cli-go/cmd"
click node_gateway "https://github.com/phani465/agentforge/blob/main/services/api-gateway/main.py"
click node_agent_routes "https://github.com/phani465/agentforge/blob/main/services/api-gateway/routers/agents.py"
click node_run_routes "https://github.com/phani465/agentforge/blob/main/services/api-gateway/routers/runs.py"
click node_eval_routes "https://github.com/phani465/agentforge/blob/main/services/api-gateway/routers/evals.py"
click node_analytics_traces "https://github.com/phani465/agentforge/tree/main/services/api-gateway/routers"
click node_auth_service "https://github.com/phani465/agentforge/blob/main/services/auth-service/main.go"
click node_runtime "https://github.com/phani465/agentforge/blob/main/services/agent-runtime/engine.py"
click node_runtime_http "https://github.com/phani465/agentforge/blob/main/services/agent-runtime/routers/runs.py"
click node_runtime_controls "https://github.com/phani465/agentforge/tree/main/services/agent-runtime"
click node_runtime_optimization "https://github.com/phani465/agentforge/blob/main/services/agent-runtime/routing.py"
click node_eval_service "https://github.com/phani465/agentforge/blob/main/services/eval-service/runner.py"
click node_trace_collector "https://github.com/phani465/agentforge/blob/main/services/trace-collector/main.py"
click node_common_models "https://github.com/phani465/agentforge/blob/main/packages/common/agentforge_common/models.py"
click node_orm "https://github.com/phani465/agentforge/blob/main/packages/common/agentforge_common/orm.py"
click node_db_setup "https://github.com/phani465/agentforge/blob/main/packages/common/agentforge_common/db.py"
click node_shared_security "https://github.com/phani465/agentforge/blob/main/packages/common/agentforge_common/security.py"
click node_gateway_dependencies "https://github.com/phani465/agentforge/blob/main/services/api-gateway/dependencies.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_dashboard,node_dashboard_auth,node_dashboard_api,node_dashboard_pages,node_sdk,node_cli,node_user toneBlue
class node_gateway,node_agent_routes,node_run_routes,node_eval_routes,node_analytics_traces,node_auth_service,node_gateway_dependencies,node_postgres,node_redis toneAmber
class node_runtime,node_runtime_http,node_runtime_controls,node_runtime_optimization,node_trace_collector toneMint
class node_eval_service toneRose
class node_common_models,node_orm,node_db_setup,node_shared_security,node_llm toneIndigo
```

## Components

### User Experience

- [Dashboard routes](https://github.com/phani465/agentforge/blob/main/dashboard/src/App.tsx): `dashboard/src/App.tsx`
- [Dashboard auth](https://github.com/phani465/agentforge/blob/main/dashboard/src/lib/auth.tsx): `dashboard/src/lib/auth.tsx`
- [Dashboard API client](https://github.com/phani465/agentforge/blob/main/dashboard/src/api/client.ts): `dashboard/src/api/client.ts`
- [Agent, trace, eval, analytics, settings](https://github.com/phani465/agentforge/tree/main/dashboard/src/pages): `dashboard/src/pages`
- [Python SDK](https://github.com/phani465/agentforge/tree/main/packages/sdk/agentforge): `packages/sdk/agentforge`
- [Go CLI](https://github.com/phani465/agentforge/tree/main/packages/cli-go/cmd): `packages/cli-go/cmd`

### API and Identity

- [API gateway](https://github.com/phani465/agentforge/blob/main/services/api-gateway/main.py): `services/api-gateway/main.py`
- [Agent management](https://github.com/phani465/agentforge/blob/main/services/api-gateway/routers/agents.py): `services/api-gateway/routers/agents.py`
- [Run orchestration](https://github.com/phani465/agentforge/blob/main/services/api-gateway/routers/runs.py): `services/api-gateway/routers/runs.py`
- [Evaluation routes](https://github.com/phani465/agentforge/blob/main/services/api-gateway/routers/evals.py): `services/api-gateway/routers/evals.py`
- [Analytics and traces](https://github.com/phani465/agentforge/tree/main/services/api-gateway/routers): `services/api-gateway/routers`
- [Login and token issuer](https://github.com/phani465/agentforge/blob/main/services/auth-service/main.go): `services/auth-service/main.go`
- [Gateway auth dependencies](https://github.com/phani465/agentforge/blob/main/services/api-gateway/dependencies.py): `services/api-gateway/dependencies.py`

### Agent Execution

- [Agent execution loop](https://github.com/phani465/agentforge/blob/main/services/agent-runtime/engine.py): `services/agent-runtime/engine.py`
- [Runtime API](https://github.com/phani465/agentforge/blob/main/services/agent-runtime/routers/runs.py): `services/agent-runtime/routers/runs.py`
- [Safety, scope, tools](https://github.com/phani465/agentforge/tree/main/services/agent-runtime): `services/agent-runtime`
- [Routing and compression](https://github.com/phani465/agentforge/blob/main/services/agent-runtime/routing.py): `services/agent-runtime/routing.py`
- [Trace collector](https://github.com/phani465/agentforge/blob/main/services/trace-collector/main.py): `services/trace-collector/main.py`

### Evaluation

- [Evaluation runner and scoring](https://github.com/phani465/agentforge/blob/main/services/eval-service/runner.py): `services/eval-service/runner.py`

### Shared Data

- [Shared domain models](https://github.com/phani465/agentforge/blob/main/packages/common/agentforge_common/models.py): `packages/common/agentforge_common/models.py`
- [Persistence mappings](https://github.com/phani465/agentforge/blob/main/packages/common/agentforge_common/orm.py): `packages/common/agentforge_common/orm.py`
- [Database sessions](https://github.com/phani465/agentforge/blob/main/packages/common/agentforge_common/db.py): `packages/common/agentforge_common/db.py`
- [Shared security and errors](https://github.com/phani465/agentforge/blob/main/packages/common/agentforge_common/security.py): `packages/common/agentforge_common/security.py`

### Other components

- **User**
- **LLM provider**
- **PostgreSQL**
- **Redis cache**

## Connections

- User → Dashboard routes: uses (evidence: `README.md`)
- Dashboard routes → Dashboard auth: provides auth (evidence: `dashboard/src/App.tsx`)
- Dashboard routes → Agent, trace, eval, analytics, settings: routes to (evidence: `dashboard/src/App.tsx`)
- Agent, trace, eval, analytics, settings → Dashboard API client: requests data (evidence: `dashboard/src/pages/AgentCatalog.tsx`)
- Dashboard auth → Dashboard API client: uses key storage (evidence: `dashboard/src/lib/auth.tsx`)
- Dashboard API client → API gateway: calls API (evidence: `README.md`)
- Dashboard API client → Login and token issuer: auth requests (evidence: `dashboard/src/api/client.ts`)
- Python SDK → API gateway: uses platform API
- Go CLI → API gateway: uses platform API
- API gateway → Agent management: registers routes (evidence: `services/api-gateway/main.py`)
- API gateway → Run orchestration: registers routes (evidence: `services/api-gateway/main.py`)
- API gateway → Evaluation routes: registers routes (evidence: `services/api-gateway/main.py`)
- API gateway → Analytics and traces: registers routes (evidence: `services/api-gateway/main.py`)
- Run orchestration → Runtime API: posts run (evidence: `services/api-gateway/routers/runs.py`)
- Runtime API → Agent execution loop: executes run
- Agent execution loop → Safety, scope, tools: applies controls (evidence: `services/agent-runtime/engine.py`)
- Agent execution loop → Routing and compression: uses optimization (evidence: `services/agent-runtime/engine.py`)
- Agent execution loop → LLM provider: requests completions (evidence: `README.md`)
- Agent execution loop → Trace collector: exports traces (evidence: `README.md`)
- Evaluation routes → Evaluation runner and scoring: posts suite (evidence: `services/api-gateway/routers/evals.py`)
- Evaluation runner and scoring → Agent execution loop: executes agent
- API gateway → Database sessions: uses sessions (evidence: `services/api-gateway/main.py`)
- Runtime API → Database sessions: uses sessions
- Evaluation runner and scoring → Database sessions: uses sessions
- Trace collector → Database sessions: uses sessions (evidence: `services/trace-collector/main.py`)
- Database sessions → PostgreSQL: connects (evidence: `packages/common/agentforge_common/db.py`)
- Persistence mappings → Database sessions: uses base (evidence: `packages/common/agentforge_common/orm.py`)
- API gateway → Persistence mappings: persists domain data
- Agent execution loop → Redis cache: uses response cache (evidence: `README.md`)
- Agent execution loop → Shared domain models: uses run models (evidence: `services/agent-runtime/engine.py`)
- Persistence mappings → Shared domain models: maps domain models
- API gateway → Gateway auth dependencies: uses auth dependencies
- Gateway auth dependencies → Shared security and errors: checks credentials
- Login and token issuer → PostgreSQL: reads and writes users (evidence: `services/auth-service/main.go`)
