# c4rohan/lampline architecture

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

- Interactive diagram: https://gitdiagram.com/c4rohan/lampline
- Repository: https://github.com/c4rohan/lampline

## Overview

Lampline is a local-first platform for authoring, testing, and running phone agents, including Dialogflow CX and CX Agent Studio imports and exports. The main workflow is to keep an agent as YAML/Markdown, lint and test it with `vk`, then run conversations through the engine and optionally connect phone services. The graph also preserves the builder, evaluations, integrations, knowledge, tools, and triggers described by the README. Some subsystem links rely on README documentation because their implementation was not sampled.

Main entry points: [`engine/src/vpengine/server.py`](https://github.com/c4rohan/lampline/blob/prod/engine/src/vpengine/server.py) (Engine API), [`cli/src/vk/cli.py`](https://github.com/c4rohan/lampline/blob/prod/cli/src/vk/cli.py) (vk CLI), [`engine/src/vpengine/session.py`](https://github.com/c4rohan/lampline/blob/prod/engine/src/vpengine/session.py) (Conversation session), [`cli/src/vk/agentfs.py`](https://github.com/c4rohan/lampline/blob/prod/cli/src/vk/agentfs.py) (Agent files)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_authoring["Agent authoring"]
  node_agent_files["Agent files<br/>[agentfs.py]"]
  node_vk_cli["vk CLI<br/>[cli.py]"]
  node_lint["Agent lint<br/>[lint.py]"]
  node_scenario["Scenario tests<br/>[scenario.py]"]
  node_importers["Google importers"]
  node_exporters["Google exporters"]
end

subgraph group_engine["Conversation engine"]
  node_engine_api["Engine API<br/>[server.py]"]
  node_agent_graph["Agent graph<br/>[graph.py]"]
  node_session["Conversation session<br/>[session.py]"]
  node_flow["Flow controller<br/>[flow.py]"]
  node_model_speech["Model and speech<br/>[services.py]"]
end

subgraph group_telephony["Calls and evaluation"]
  node_telephony["Phone transports<br/>[twilio.py]"]
  node_evals["Phone evaluations<br/>[evals.py]"]
  node_automation["Triggers and automation<br/>[automation.py]"]
  node_phone_bridge["Phone Bridge<br/>[gv-page.js]"]
end

subgraph group_integrations["Integrations and data"]
  node_tools["Agent tools<br/>[tools.py]"]
  node_connectors["Connectors<br/>[connectors.py]"]
  node_knowledge[("Knowledge store<br/>[library.py]")]
end

subgraph group_interfaces["User interfaces"]
  node_builder["Visual builder"]
  node_integrations_ui["Integrations settings<br/>[Integrations.tsx]"]
  node_ui["Web application<br/>[App.tsx]"]
end

node_engineer(("Agent author"))
node_phone_network(("Phone network"))
node_model_providers(("Model providers"))

node_engineer -->|"authors"| node_agent_files
node_engineer -->|"runs commands"| node_vk_cli
node_vk_cli -->|"reads and writes"| node_agent_files
node_vk_cli -->|"runs checks"| node_lint
node_vk_cli -->|"runs tests"| node_scenario
node_vk_cli -->|"imports agents"| node_importers
node_vk_cli -->|"exports agents"| node_exporters
node_importers -->|"produces agent"| node_agent_files
node_exporters -->|"reads agent"| node_agent_files
node_vk_cli -->|"tests against"| node_engine_api
node_engine_api -->|"loads agents"| node_agent_graph
node_engine_api -->|"starts sessions"| node_session
node_session -->|"delegates turns"| node_flow
node_session -->|"uses graph"| node_agent_graph
node_session -->|"uses services"| node_model_speech
node_flow -.->|"invokes tools"| node_tools
node_engine_api -.->|"serves phone calls"| node_telephony
node_model_speech -->|"connects models"| node_model_providers
node_engine_api -.->|"supports evaluations"| node_evals
node_evals -->|"places eval calls"| node_phone_network
node_phone_bridge -->|"bridges call audio"| node_evals
node_engine_api -->|"runs triggers"| node_automation
node_automation -->|"checks status"| node_connectors
node_tools -.->|"uses connectors"| node_connectors
node_engine_api -->|"serves data collections"| node_knowledge
node_ui -.->|"uses API"| node_engine_api
node_builder -.->|"edits agents"| node_engine_api
node_integrations_ui -.->|"configures services"| node_engine_api
node_phone_network -.->|"carries calls"| node_telephony

click node_agent_files "https://github.com/c4rohan/lampline/blob/prod/cli/src/vk/agentfs.py"
click node_vk_cli "https://github.com/c4rohan/lampline/blob/prod/cli/src/vk/cli.py"
click node_lint "https://github.com/c4rohan/lampline/blob/prod/cli/src/vk/lint.py"
click node_scenario "https://github.com/c4rohan/lampline/blob/prod/cli/src/vk/scenario.py"
click node_importers "https://github.com/c4rohan/lampline/tree/prod/cli/src/vk/importers"
click node_exporters "https://github.com/c4rohan/lampline/tree/prod/cli/src/vk/exporters"
click node_builder "https://github.com/c4rohan/lampline/tree/prod/engine/ui/src/builder"
click node_engine_api "https://github.com/c4rohan/lampline/blob/prod/engine/src/vpengine/server.py"
click node_agent_graph "https://github.com/c4rohan/lampline/blob/prod/engine/src/vpengine/graph.py"
click node_session "https://github.com/c4rohan/lampline/blob/prod/engine/src/vpengine/session.py"
click node_flow "https://github.com/c4rohan/lampline/blob/prod/engine/src/vpengine/flow.py"
click node_model_speech "https://github.com/c4rohan/lampline/blob/prod/engine/src/vpengine/services.py"
click node_tools "https://github.com/c4rohan/lampline/blob/prod/engine/src/vpengine/tools.py"
click node_connectors "https://github.com/c4rohan/lampline/blob/prod/engine/src/vpengine/connectors.py"
click node_knowledge "https://github.com/c4rohan/lampline/blob/prod/engine/src/vpengine/library.py"
click node_integrations_ui "https://github.com/c4rohan/lampline/blob/prod/engine/ui/src/pages/Integrations.tsx"
click node_telephony "https://github.com/c4rohan/lampline/blob/prod/engine/src/vpengine/twilio.py"
click node_evals "https://github.com/c4rohan/lampline/blob/prod/engine/src/vpengine/evals.py"
click node_automation "https://github.com/c4rohan/lampline/blob/prod/engine/src/vpengine/automation.py"
click node_ui "https://github.com/c4rohan/lampline/blob/prod/engine/ui/src/App.tsx"
click node_phone_bridge "https://github.com/c4rohan/lampline/blob/prod/extension/gv-page.js"

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_agent_files,node_vk_cli,node_lint,node_scenario,node_importers,node_exporters toneBlue
class node_engine_api,node_agent_graph,node_session,node_flow,node_model_speech toneAmber
class node_telephony,node_evals,node_automation,node_phone_bridge toneMint
class node_tools,node_connectors,node_knowledge toneRose
class node_builder,node_integrations_ui,node_ui,node_engineer,node_phone_network,node_model_providers toneIndigo
```

## Components

### Agent authoring

- [Agent files](https://github.com/c4rohan/lampline/blob/prod/cli/src/vk/agentfs.py): `cli/src/vk/agentfs.py`
- [vk CLI](https://github.com/c4rohan/lampline/blob/prod/cli/src/vk/cli.py): `cli/src/vk/cli.py`
- [Agent lint](https://github.com/c4rohan/lampline/blob/prod/cli/src/vk/lint.py): `cli/src/vk/lint.py`
- [Scenario tests](https://github.com/c4rohan/lampline/blob/prod/cli/src/vk/scenario.py): `cli/src/vk/scenario.py`
- [Google importers](https://github.com/c4rohan/lampline/tree/prod/cli/src/vk/importers): `cli/src/vk/importers`
- [Google exporters](https://github.com/c4rohan/lampline/tree/prod/cli/src/vk/exporters): `cli/src/vk/exporters`

### Conversation engine

- [Engine API](https://github.com/c4rohan/lampline/blob/prod/engine/src/vpengine/server.py): `engine/src/vpengine/server.py`
- [Agent graph](https://github.com/c4rohan/lampline/blob/prod/engine/src/vpengine/graph.py): `engine/src/vpengine/graph.py`
- [Conversation session](https://github.com/c4rohan/lampline/blob/prod/engine/src/vpengine/session.py): `engine/src/vpengine/session.py`
- [Flow controller](https://github.com/c4rohan/lampline/blob/prod/engine/src/vpengine/flow.py): `engine/src/vpengine/flow.py`
- [Model and speech](https://github.com/c4rohan/lampline/blob/prod/engine/src/vpengine/services.py): `engine/src/vpengine/services.py`

### Calls and evaluation

- [Phone transports](https://github.com/c4rohan/lampline/blob/prod/engine/src/vpengine/twilio.py): `engine/src/vpengine/twilio.py`
- [Phone evaluations](https://github.com/c4rohan/lampline/blob/prod/engine/src/vpengine/evals.py): `engine/src/vpengine/evals.py`
- [Triggers and automation](https://github.com/c4rohan/lampline/blob/prod/engine/src/vpengine/automation.py): `engine/src/vpengine/automation.py`
- [Phone Bridge](https://github.com/c4rohan/lampline/blob/prod/extension/gv-page.js): `extension/gv-page.js`

### Integrations and data

- [Agent tools](https://github.com/c4rohan/lampline/blob/prod/engine/src/vpengine/tools.py): `engine/src/vpengine/tools.py`
- [Connectors](https://github.com/c4rohan/lampline/blob/prod/engine/src/vpengine/connectors.py): `engine/src/vpengine/connectors.py`
- [Knowledge store](https://github.com/c4rohan/lampline/blob/prod/engine/src/vpengine/library.py): `engine/src/vpengine/library.py`

### User interfaces

- [Visual builder](https://github.com/c4rohan/lampline/tree/prod/engine/ui/src/builder): `engine/ui/src/builder`
- [Integrations settings](https://github.com/c4rohan/lampline/blob/prod/engine/ui/src/pages/Integrations.tsx): `engine/ui/src/pages/Integrations.tsx`
- [Web application](https://github.com/c4rohan/lampline/blob/prod/engine/ui/src/App.tsx): `engine/ui/src/App.tsx`

### Other components

- **Agent author**
- **Phone network**
- **Model providers**

## Connections

- Agent author → Agent files: authors (evidence: `README.md`)
- Agent author → vk CLI: runs commands (evidence: `README.md`)
- vk CLI → Agent files: reads and writes (evidence: `cli/src/vk/cli.py`)
- vk CLI → Agent lint: runs checks (evidence: `cli/src/vk/cli.py`)
- vk CLI → Scenario tests: runs tests (evidence: `cli/src/vk/cli.py`)
- vk CLI → Google importers: imports agents (evidence: `cli/src/vk/cli.py`)
- vk CLI → Google exporters: exports agents (evidence: `cli/src/vk/cli.py`)
- Google importers → Agent files: produces agent (evidence: `cli/src/vk/importers/common.py`)
- Google exporters → Agent files: reads agent (evidence: `cli/src/vk/exporters/common.py`)
- vk CLI → Engine API: tests against
- Engine API → Agent graph: loads agents (evidence: `engine/src/vpengine/server.py`)
- Engine API → Conversation session: starts sessions (evidence: `engine/src/vpengine/server.py`)
- Conversation session → Flow controller: delegates turns (evidence: `engine/src/vpengine/session.py`)
- Conversation session → Agent graph: uses graph (evidence: `engine/src/vpengine/session.py`)
- Conversation session → Model and speech: uses services (evidence: `engine/src/vpengine/session.py`)
- Flow controller → Agent tools: invokes tools
- Engine API → Phone transports: serves phone calls (evidence: `engine/src/vpengine/server.py`)
- Model and speech → Model providers: connects models (evidence: `README.md`)
- Engine API → Phone evaluations: supports evaluations (evidence: `engine/src/vpengine/server.py`)
- Phone evaluations → Phone network: places eval calls (evidence: `README.md`)
- Phone Bridge → Phone evaluations: bridges call audio (evidence: `README.md`)
- Engine API → Triggers and automation: runs triggers (evidence: `engine/src/vpengine/server.py`)
- Triggers and automation → Connectors: checks status (evidence: `engine/src/vpengine/automation.py`)
- Agent tools → Connectors: uses connectors
- Engine API → Knowledge store: serves data collections (evidence: `engine/src/vpengine/server.py`)
- Web application → Engine API: uses API
- Visual builder → Engine API: edits agents
- Integrations settings → Engine API: configures services
- Phone network → Phone transports: carries calls
