# sntl84/velocity architecture

> Architecture diagram of the GitHub repository sntl84/velocity, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sntl84/velocity
- Repository: https://github.com/sntl84/velocity

## Overview

Open Velocity’s implemented core is a backend for agentic development: requests enter through the server or CLI, the orchestrator creates and runs agents, and agents use a model gateway and development tools to carry out tasks. Supporting stages include policy checks, shared swarm coordination, memory snapshots, artifact storage, auditing, and persistent database state. The README describes several backend capabilities whose implementation is present in the tree but was not sampled; those links are identified as documented rather than source-verified.

Main entry points: [`newcore/src/orchestrator/agent.ts`](https://github.com/sntl84/velocity/blob/main/newcore/src/orchestrator/agent.ts) (Agent runtime), [`newcore/src/orchestrator/index.ts`](https://github.com/sntl84/velocity/blob/main/newcore/src/orchestrator/index.ts) (Agent orchestrator), [`newcore/src/db/tables`](https://github.com/sntl84/velocity/tree/main/newcore/src/db/tables) (Domain tables), [`newcore/src/gateway/index.ts`](https://github.com/sntl84/velocity/blob/main/newcore/src/gateway/index.ts) (Model gateway)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry points"]
  node_http["HTTP server<br/>[server.ts]"]
  node_cli["CLI commands<br/>[cli.ts]"]
end

subgraph group_execution["Agent execution"]
  node_orchestrator["Agent orchestrator<br/>[index.ts]"]
  node_agent["Agent runtime<br/>[agent.ts]"]
  node_gateway["Model gateway<br/>[index.ts]"]
  node_providers["LLM providers<br/>[anthropic.ts]"]
  node_toolregistry["Tool registry<br/>[index.ts]"]
  node_devtools["Development tools<br/>[z3-solver.ts]"]
end

subgraph group_coordination["Swarm coordination"]
  node_messagebus["Swarm message bus<br/>[messagebus.ts]"]
  node_locks["File lock manager<br/>[locks.ts]"]
end

subgraph group_services["Agent services"]
  node_policy["Safety policy<br/>[index.ts]"]
  node_memory["Agent memory<br/>[liquid.ts]"]
  node_snapshots["Memory snapshots<br/>[snapshot.ts]"]
  node_artifacts["Artifact store<br/>[index.ts]"]
  node_audit["Audit logger<br/>[index.ts]"]
  node_config["Configuration<br/>[index.ts]"]
end

subgraph group_persistence["Persistence"]
  node_database[("SQLite database<br/>[index.ts]")]
  node_tables[("Domain tables")]
end

node_developer(("Developer / client"))

node_developer -.->|"sends requests"| node_http
node_developer -.->|"runs commands"| node_cli
node_http -->|"routes requests"| node_orchestrator
node_cli -.->|"uses engine"| node_orchestrator
node_orchestrator -->|"creates agents"| node_agent
node_orchestrator -->|"constructs gateway"| node_gateway
node_orchestrator -->|"constructs registry"| node_toolregistry
node_orchestrator -->|"constructs store"| node_artifacts
node_orchestrator -->|"constructs logger"| node_audit
node_orchestrator -->|"constructs policy"| node_policy
node_agent -->|"requests completions"| node_gateway
node_agent -->|"executes tools"| node_toolregistry
node_agent -->|"creates artifacts"| node_artifacts
node_agent -->|"logs actions"| node_audit
node_agent -->|"checks actions"| node_policy
node_toolregistry -->|"registers tools"| node_devtools
node_gateway -->|"registers providers"| node_providers
node_agent -->|"persists state"| node_database
node_agent -->|"saves snapshots"| node_snapshots
node_snapshots -->|"snapshots state"| node_memory
node_artifacts -->|"indexes artifacts"| node_tables
node_audit -->|"persists events"| node_tables
node_tables -.->|"queries database"| node_database
node_messagebus -.->|"stores messages"| node_tables
node_locks -.->|"stores locks"| node_tables
node_gateway -->|"records costs"| node_tables
node_http -->|"loads settings"| node_config

click node_http "https://github.com/sntl84/velocity/blob/main/newcore/src/server.ts"
click node_cli "https://github.com/sntl84/velocity/blob/main/newcore/src/cli.ts"
click node_orchestrator "https://github.com/sntl84/velocity/blob/main/newcore/src/orchestrator/index.ts"
click node_agent "https://github.com/sntl84/velocity/blob/main/newcore/src/orchestrator/agent.ts"
click node_gateway "https://github.com/sntl84/velocity/blob/main/newcore/src/gateway/index.ts"
click node_providers "https://github.com/sntl84/velocity/blob/main/newcore/src/gateway/providers/anthropic.ts"
click node_toolregistry "https://github.com/sntl84/velocity/blob/main/newcore/src/tools/index.ts"
click node_devtools "https://github.com/sntl84/velocity/blob/main/newcore/src/tools/z3-solver.ts"
click node_policy "https://github.com/sntl84/velocity/blob/main/newcore/src/policy/index.ts"
click node_messagebus "https://github.com/sntl84/velocity/blob/main/newcore/src/orchestrator/messagebus.ts"
click node_locks "https://github.com/sntl84/velocity/blob/main/newcore/src/orchestrator/locks.ts"
click node_memory "https://github.com/sntl84/velocity/blob/main/newcore/src/memory/liquid.ts"
click node_snapshots "https://github.com/sntl84/velocity/blob/main/newcore/src/memory/snapshot.ts"
click node_artifacts "https://github.com/sntl84/velocity/blob/main/newcore/src/artifacts/index.ts"
click node_audit "https://github.com/sntl84/velocity/blob/main/newcore/src/audit/index.ts"
click node_database "https://github.com/sntl84/velocity/blob/main/newcore/src/db/index.ts"
click node_tables "https://github.com/sntl84/velocity/tree/main/newcore/src/db/tables"
click node_config "https://github.com/sntl84/velocity/blob/main/newcore/src/config/index.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_http,node_cli,node_developer toneBlue
class node_orchestrator,node_agent,node_gateway,node_providers,node_toolregistry,node_devtools toneAmber
class node_messagebus,node_locks toneMint
class node_policy,node_memory,node_snapshots,node_artifacts,node_audit,node_config toneRose
class node_database,node_tables toneIndigo
```

## Components

### Entry points

- [HTTP server](https://github.com/sntl84/velocity/blob/main/newcore/src/server.ts): `newcore/src/server.ts`
- [CLI commands](https://github.com/sntl84/velocity/blob/main/newcore/src/cli.ts): `newcore/src/cli.ts`

### Agent execution

- [Agent orchestrator](https://github.com/sntl84/velocity/blob/main/newcore/src/orchestrator/index.ts): `newcore/src/orchestrator/index.ts`
- [Agent runtime](https://github.com/sntl84/velocity/blob/main/newcore/src/orchestrator/agent.ts): `newcore/src/orchestrator/agent.ts`
- [Model gateway](https://github.com/sntl84/velocity/blob/main/newcore/src/gateway/index.ts): `newcore/src/gateway/index.ts`
- [LLM providers](https://github.com/sntl84/velocity/blob/main/newcore/src/gateway/providers/anthropic.ts): `newcore/src/gateway/providers/anthropic.ts`
- [Tool registry](https://github.com/sntl84/velocity/blob/main/newcore/src/tools/index.ts): `newcore/src/tools/index.ts`
- [Development tools](https://github.com/sntl84/velocity/blob/main/newcore/src/tools/z3-solver.ts): `newcore/src/tools/z3-solver.ts`

### Swarm coordination

- [Swarm message bus](https://github.com/sntl84/velocity/blob/main/newcore/src/orchestrator/messagebus.ts): `newcore/src/orchestrator/messagebus.ts`
- [File lock manager](https://github.com/sntl84/velocity/blob/main/newcore/src/orchestrator/locks.ts): `newcore/src/orchestrator/locks.ts`

### Agent services

- [Safety policy](https://github.com/sntl84/velocity/blob/main/newcore/src/policy/index.ts): `newcore/src/policy/index.ts`
- [Agent memory](https://github.com/sntl84/velocity/blob/main/newcore/src/memory/liquid.ts): `newcore/src/memory/liquid.ts`
- [Memory snapshots](https://github.com/sntl84/velocity/blob/main/newcore/src/memory/snapshot.ts): `newcore/src/memory/snapshot.ts`
- [Artifact store](https://github.com/sntl84/velocity/blob/main/newcore/src/artifacts/index.ts): `newcore/src/artifacts/index.ts`
- [Audit logger](https://github.com/sntl84/velocity/blob/main/newcore/src/audit/index.ts): `newcore/src/audit/index.ts`
- [Configuration](https://github.com/sntl84/velocity/blob/main/newcore/src/config/index.ts): `newcore/src/config/index.ts`

### Persistence

- [SQLite database](https://github.com/sntl84/velocity/blob/main/newcore/src/db/index.ts): `newcore/src/db/index.ts`
- [Domain tables](https://github.com/sntl84/velocity/tree/main/newcore/src/db/tables): `newcore/src/db/tables`

### Other components

- **Developer / client**

## Connections

- Developer / client → HTTP server: sends requests (evidence: `README.md`)
- Developer / client → CLI commands: runs commands (evidence: `README.md`)
- HTTP server → Agent orchestrator: routes requests (evidence: `newcore/src/server.ts`)
- CLI commands → Agent orchestrator: uses engine (evidence: `README.md`)
- Agent orchestrator → Agent runtime: creates agents (evidence: `newcore/src/orchestrator/index.ts`)
- Agent orchestrator → Model gateway: constructs gateway (evidence: `newcore/src/orchestrator/index.ts`)
- Agent orchestrator → Tool registry: constructs registry (evidence: `newcore/src/orchestrator/index.ts`)
- Agent orchestrator → Artifact store: constructs store (evidence: `newcore/src/orchestrator/index.ts`)
- Agent orchestrator → Audit logger: constructs logger (evidence: `newcore/src/orchestrator/index.ts`)
- Agent orchestrator → Safety policy: constructs policy (evidence: `newcore/src/orchestrator/index.ts`)
- Agent runtime → Model gateway: requests completions (evidence: `newcore/src/orchestrator/agent.ts`)
- Agent runtime → Tool registry: executes tools (evidence: `newcore/src/orchestrator/agent.ts`)
- Agent runtime → Artifact store: creates artifacts (evidence: `newcore/src/orchestrator/agent.ts`)
- Agent runtime → Audit logger: logs actions (evidence: `newcore/src/orchestrator/agent.ts`)
- Agent runtime → Safety policy: checks actions (evidence: `newcore/src/orchestrator/agent.ts`)
- Tool registry → Development tools: registers tools (evidence: `newcore/src/tools/index.ts`)
- Model gateway → LLM providers: registers providers (evidence: `newcore/src/gateway/index.ts`)
- Agent runtime → SQLite database: persists state (evidence: `newcore/src/orchestrator/agent.ts`)
- Agent runtime → Memory snapshots: saves snapshots (evidence: `newcore/src/orchestrator/agent.ts`)
- Memory snapshots → Agent memory: snapshots state (evidence: `newcore/src/memory/snapshot.ts`)
- Artifact store → Domain tables: indexes artifacts (evidence: `newcore/src/artifacts/index.ts`)
- Audit logger → Domain tables: persists events (evidence: `newcore/src/audit/index.ts`)
- Domain tables → SQLite database: queries database (evidence: `newcore/src/db/tables/agents.ts`)
- Swarm message bus → Domain tables: stores messages (evidence: `README.md`)
- File lock manager → Domain tables: stores locks (evidence: `README.md`)
- Model gateway → Domain tables: records costs (evidence: `newcore/src/gateway/index.ts`)
- HTTP server → Configuration: loads settings (evidence: `newcore/src/server.ts`)