# goshikavs/goshikq-agent-framework architecture

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

- Interactive diagram: https://gitdiagram.com/goshikavs/goshikq-agent-framework
- Repository: https://github.com/goshikavs/goshikq-agent-framework

## Overview

Goshikq is an AI agent framework: Python and TypeScript SDKs define agents, tools, and goal contracts; a Rust server/runtime executes runs and verifies outcomes against state. The product also provides durable recovery, multi-agent and workflow execution, approvals, evidence/change-impact analysis, protocol integrations, and Studio’s execution explorer. The graph follows documented SDK-to-runtime and Studio-to-runtime flows; unsampled subsystems are represented from README capabilities, with links omitted where implementation-level callers were not shown.

Main entry points: [`crates/goshikq-runtime/src/runtime.rs`](https://github.com/goshikavs/goshikq-agent-framework/blob/main/crates/goshikq-runtime/src/runtime.rs) (Runtime), [`crates/goshikq-server/src/routes/runs.rs`](https://github.com/goshikavs/goshikq-agent-framework/blob/main/crates/goshikq-server/src/routes/runs.rs) (HTTP API), [`sdk/python/src/goshikq_ai/client.py`](https://github.com/goshikavs/goshikq-agent-framework/blob/main/sdk/python/src/goshikq_ai/client.py) (Runtime Clients), [`sdk/python/src/goshikq_ai/agent.py`](https://github.com/goshikavs/goshikq-agent-framework/blob/main/sdk/python/src/goshikq_ai/agent.py) (Agent Definitions)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_sdk["Agent SDKs"]
  node_builder["Agent Definitions<br/>[agent.py]"]
  node_contracts["Goals and Tools<br/>[goal.py]"]
  node_pyworker["Python Worker<br/>[worker.py]"]
  node_tsworker["TypeScript Worker<br/>[worker.ts]"]
  node_sdkclient["Runtime Clients<br/>[client.py]"]
end

subgraph group_runtime["Execution Runtime"]
  node_protocol["Run Protocol<br/>[run.rs]"]
  node_runtimeentry["Runtime<br/>[runtime.rs]"]
  node_executor["Execution Loop<br/>[executor.rs]"]
  node_recovery["Durable Recovery<br/>[supervisor.rs]"]
  node_workflow["Workflow Engine<br/>[workflow_exec.rs]"]
end

subgraph group_server["Server and API"]
  node_server["HTTP API<br/>[runs.rs]"]
  node_tasks["Delegated Tasks<br/>[tasks.rs]"]
  node_catalog["Capability Catalog<br/>[catalog.rs]"]
  node_identity["Auth and Tenancy<br/>[auth.rs]"]
  node_configuration["Server Configuration<br/>[config.rs]"]
end

subgraph group_data["Durability and Evidence"]
  node_coverage["Evidence Coverage<br/>[coverage.rs]"]
  node_impact["Impact Revalidation<br/>[impact.rs]"]
  node_persistence[("Run and Event Store<br/>[runs.rs]")]
  node_approvals[("Approval Gates<br/>[approvals.rs]")]
end

subgraph group_console["Studio Console"]
  node_studio["Execution Explorer<br/>[page.tsx]"]
  node_studioapi["Runtime Proxy<br/>[route.ts]"]
end

node_actor(("Agent Developer"))
node_postgres[("PostgreSQL")]
node_externaltraces(("External Trace Sources"))

node_actor -->|"defines agent"| node_builder
node_builder -->|"declares goals"| node_contracts
node_pyworker -->|"polls and responds"| node_sdkclient
node_tsworker -->|"polls and responds"| node_sdkclient
node_sdkclient -->|"calls API"| node_server
node_server -->|"authorizes requests"| node_identity
node_server -->|"dispatches runs"| node_runtimeentry
node_runtimeentry -->|"executes runs"| node_executor
node_runtimeentry -->|"uses run protocol"| node_protocol
node_runtimeentry -->|"persists runs"| node_persistence
node_persistence -->|"stores durable data"| node_postgres
node_runtimeentry -.->|"supervises recovery"| node_recovery
node_runtimeentry -->|"executes workflows"| node_workflow
node_runtimeentry -.->|"gates actions"| node_approvals
node_runtimeentry -.->|"checks evidence"| node_coverage
node_runtimeentry -.->|"revalidates changes"| node_impact
node_runtimeentry -.->|"delegates tasks"| node_tasks
node_server -.->|"serves capabilities"| node_catalog
node_studio -->|"requests runtime data"| node_studioapi
node_studioapi -->|"proxies requests"| node_server
node_externaltraces -->|"ingests OTLP"| node_server

click node_builder "https://github.com/goshikavs/goshikq-agent-framework/blob/main/sdk/python/src/goshikq_ai/agent.py"
click node_contracts "https://github.com/goshikavs/goshikq-agent-framework/blob/main/sdk/python/src/goshikq_ai/goal.py"
click node_pyworker "https://github.com/goshikavs/goshikq-agent-framework/blob/main/sdk/python/src/goshikq_ai/worker.py"
click node_tsworker "https://github.com/goshikavs/goshikq-agent-framework/blob/main/sdk/typescript/src/worker.ts"
click node_sdkclient "https://github.com/goshikavs/goshikq-agent-framework/blob/main/sdk/python/src/goshikq_ai/client.py"
click node_protocol "https://github.com/goshikavs/goshikq-agent-framework/blob/main/crates/goshikq-protocol/src/run.rs"
click node_runtimeentry "https://github.com/goshikavs/goshikq-agent-framework/blob/main/crates/goshikq-runtime/src/runtime.rs"
click node_executor "https://github.com/goshikavs/goshikq-agent-framework/blob/main/crates/goshikq-runtime/src/executor.rs"
click node_recovery "https://github.com/goshikavs/goshikq-agent-framework/blob/main/crates/goshikq-runtime/src/supervisor.rs"
click node_workflow "https://github.com/goshikavs/goshikq-agent-framework/blob/main/crates/goshikq-runtime/src/workflow_exec.rs"
click node_server "https://github.com/goshikavs/goshikq-agent-framework/blob/main/crates/goshikq-server/src/routes/runs.rs"
click node_tasks "https://github.com/goshikavs/goshikq-agent-framework/blob/main/crates/goshikq-server/src/routes/tasks.rs"
click node_catalog "https://github.com/goshikavs/goshikq-agent-framework/blob/main/crates/goshikq-server/src/routes/catalog.rs"
click node_identity "https://github.com/goshikavs/goshikq-agent-framework/blob/main/crates/goshikq-server/src/auth.rs"
click node_configuration "https://github.com/goshikavs/goshikq-agent-framework/blob/main/crates/goshikq-server/src/config.rs"
click node_coverage "https://github.com/goshikavs/goshikq-agent-framework/blob/main/crates/goshikq-core/src/coverage.rs"
click node_impact "https://github.com/goshikavs/goshikq-agent-framework/blob/main/crates/goshikq-core/src/impact.rs"
click node_persistence "https://github.com/goshikavs/goshikq-agent-framework/blob/main/crates/goshikq-storage/src/runs.rs"
click node_approvals "https://github.com/goshikavs/goshikq-agent-framework/blob/main/crates/goshikq-storage/src/approvals.rs"
click node_studio "https://github.com/goshikavs/goshikq-agent-framework/blob/main/apps/studio/src/app/executions/%5Bid%5D/page.tsx"
click node_studioapi "https://github.com/goshikavs/goshikq-agent-framework/blob/main/apps/studio/src/app/api/runtime/%5B...path%5D/route.ts"

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_builder,node_contracts,node_pyworker,node_tsworker,node_sdkclient toneBlue
class node_protocol,node_runtimeentry,node_executor,node_recovery,node_workflow,node_postgres toneAmber
class node_server,node_tasks,node_catalog,node_identity,node_configuration toneMint
class node_coverage,node_impact,node_persistence,node_approvals toneRose
class node_studio,node_studioapi,node_actor,node_externaltraces toneIndigo
```

## Components

### Agent SDKs

- [Agent Definitions](https://github.com/goshikavs/goshikq-agent-framework/blob/main/sdk/python/src/goshikq_ai/agent.py): `sdk/python/src/goshikq_ai/agent.py`
- [Goals and Tools](https://github.com/goshikavs/goshikq-agent-framework/blob/main/sdk/python/src/goshikq_ai/goal.py): `sdk/python/src/goshikq_ai/goal.py`
- [Python Worker](https://github.com/goshikavs/goshikq-agent-framework/blob/main/sdk/python/src/goshikq_ai/worker.py): `sdk/python/src/goshikq_ai/worker.py`
- [TypeScript Worker](https://github.com/goshikavs/goshikq-agent-framework/blob/main/sdk/typescript/src/worker.ts): `sdk/typescript/src/worker.ts`
- [Runtime Clients](https://github.com/goshikavs/goshikq-agent-framework/blob/main/sdk/python/src/goshikq_ai/client.py): `sdk/python/src/goshikq_ai/client.py`

### Execution Runtime

- [Run Protocol](https://github.com/goshikavs/goshikq-agent-framework/blob/main/crates/goshikq-protocol/src/run.rs): `crates/goshikq-protocol/src/run.rs`
- [Runtime](https://github.com/goshikavs/goshikq-agent-framework/blob/main/crates/goshikq-runtime/src/runtime.rs): `crates/goshikq-runtime/src/runtime.rs`
- [Execution Loop](https://github.com/goshikavs/goshikq-agent-framework/blob/main/crates/goshikq-runtime/src/executor.rs): `crates/goshikq-runtime/src/executor.rs`
- [Durable Recovery](https://github.com/goshikavs/goshikq-agent-framework/blob/main/crates/goshikq-runtime/src/supervisor.rs): `crates/goshikq-runtime/src/supervisor.rs`
- [Workflow Engine](https://github.com/goshikavs/goshikq-agent-framework/blob/main/crates/goshikq-runtime/src/workflow_exec.rs): `crates/goshikq-runtime/src/workflow_exec.rs`

### Server and API

- [HTTP API](https://github.com/goshikavs/goshikq-agent-framework/blob/main/crates/goshikq-server/src/routes/runs.rs): `crates/goshikq-server/src/routes/runs.rs`
- [Delegated Tasks](https://github.com/goshikavs/goshikq-agent-framework/blob/main/crates/goshikq-server/src/routes/tasks.rs): `crates/goshikq-server/src/routes/tasks.rs`
- [Capability Catalog](https://github.com/goshikavs/goshikq-agent-framework/blob/main/crates/goshikq-server/src/routes/catalog.rs): `crates/goshikq-server/src/routes/catalog.rs`
- [Auth and Tenancy](https://github.com/goshikavs/goshikq-agent-framework/blob/main/crates/goshikq-server/src/auth.rs): `crates/goshikq-server/src/auth.rs`
- [Server Configuration](https://github.com/goshikavs/goshikq-agent-framework/blob/main/crates/goshikq-server/src/config.rs): `crates/goshikq-server/src/config.rs`

### Durability and Evidence

- [Evidence Coverage](https://github.com/goshikavs/goshikq-agent-framework/blob/main/crates/goshikq-core/src/coverage.rs): `crates/goshikq-core/src/coverage.rs`
- [Impact Revalidation](https://github.com/goshikavs/goshikq-agent-framework/blob/main/crates/goshikq-core/src/impact.rs): `crates/goshikq-core/src/impact.rs`
- [Run and Event Store](https://github.com/goshikavs/goshikq-agent-framework/blob/main/crates/goshikq-storage/src/runs.rs): `crates/goshikq-storage/src/runs.rs`
- [Approval Gates](https://github.com/goshikavs/goshikq-agent-framework/blob/main/crates/goshikq-storage/src/approvals.rs): `crates/goshikq-storage/src/approvals.rs`

### Studio Console

- [Execution Explorer](https://github.com/goshikavs/goshikq-agent-framework/blob/main/apps/studio/src/app/executions/%5Bid%5D/page.tsx): `apps/studio/src/app/executions/[id]/page.tsx`
- [Runtime Proxy](https://github.com/goshikavs/goshikq-agent-framework/blob/main/apps/studio/src/app/api/runtime/%5B...path%5D/route.ts): `apps/studio/src/app/api/runtime/[...path]/route.ts`

### Other components

- **Agent Developer**
- **PostgreSQL**
- **External Trace Sources**

## Connections

- Agent Developer → Agent Definitions: defines agent (evidence: `README.md`)
- Agent Definitions → Goals and Tools: declares goals (evidence: `README.md`)
- Python Worker → Runtime Clients: polls and responds (evidence: `sdk/python/src/goshikq_ai/worker.py`)
- TypeScript Worker → Runtime Clients: polls and responds (evidence: `sdk/typescript/src/worker.ts`)
- Runtime Clients → HTTP API: calls API (evidence: `README.md`)
- HTTP API → Auth and Tenancy: authorizes requests (evidence: `crates/goshikq-server/src/auth.rs`)
- HTTP API → Runtime: dispatches runs (evidence: `README.md`)
- Runtime → Execution Loop: executes runs (evidence: `crates/goshikq-runtime/src/runtime.rs`)
- Runtime → Run Protocol: uses run protocol (evidence: `crates/goshikq-runtime/src/runtime.rs`)
- Runtime → Run and Event Store: persists runs (evidence: `README.md`)
- Run and Event Store → PostgreSQL: stores durable data (evidence: `README.md`)
- Runtime → Durable Recovery: supervises recovery (evidence: `crates/goshikq-runtime/src/runtime.rs`)
- Runtime → Workflow Engine: executes workflows (evidence: `README.md`)
- Runtime → Approval Gates: gates actions
- Runtime → Evidence Coverage: checks evidence
- Runtime → Impact Revalidation: revalidates changes
- Runtime → Delegated Tasks: delegates tasks
- HTTP API → Capability Catalog: serves capabilities
- Execution Explorer → Runtime Proxy: requests runtime data (evidence: `README.md`)
- Runtime Proxy → HTTP API: proxies requests (evidence: `README.md`)
- External Trace Sources → HTTP API: ingests OTLP (evidence: `README.md`)
