# biohazardious/emberline architecture

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

- Interactive diagram: https://gitdiagram.com/biohazardious/emberline
- Repository: https://github.com/biohazardious/emberline

## Overview

Emberline is a self-hosted browser workbench for running real AI coding-agent CLIs against project tickets. The main journey is board ticket → queued run on an isolated worktree → persistent agent terminal → review and approval → merge and optional forge push. It also offers project setup and previews, repository and issue workflows, usage-aware scheduling, notifications, and operational health/backup features. The README documents product-level flows; source-index references and excerpts support selected internal connections, while unsampled implementation details are not inferred.

Main entry points: [`apps/core/src/server.ts`](https://github.com/biohazardious/emberline/blob/main/apps/core/src/server.ts) (Core HTTP server), [`apps/core/src/runs/service.ts`](https://github.com/biohazardious/emberline/blob/main/apps/core/src/runs/service.ts) (Run lifecycle), [`apps/core/src/ptyd-bridge.ts`](https://github.com/biohazardious/emberline/blob/main/apps/core/src/ptyd-bridge.ts) (PTY bridge), [`apps/core/src/tickets/service.ts`](https://github.com/biohazardious/emberline/blob/main/apps/core/src/tickets/service.ts) (Ticket workflow)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Browser Workbench"]
  node_web["Workbench UI<br/>[App.tsx]"]
  node_api["Web API client<br/>[api.ts]"]
  node_reviewui["Review controls"]
end

subgraph group_runtime["Core Runtime"]
  node_core["Core HTTP server<br/>[server.ts]"]
  node_config["Runtime configuration<br/>[config.ts]"]
  node_db[("SQLite state<br/>[schema.ts]")]
  node_settings["Project settings"]
  node_tickets["Ticket workflow<br/>[service.ts]"]
  node_runs["Run lifecycle<br/>[service.ts]"]
  node_scheduler["Usage scheduler<br/>[service.ts]"]
end

subgraph group_agents["Agent Execution"]
  node_commands["Command execution<br/>[command-exec.ts]"]
  node_bridge["PTY bridge<br/>[ptyd-bridge.ts]"]
  node_ptyd["Persistent terminals<br/>[server.ts]"]
  node_adapters["Agent adapters<br/>[provider.ts]"]
end

subgraph group_projects["Projects and Git"]
  node_factory["Factory planning<br/>[roadmap.ts]"]
  node_repository["Repository service<br/>[service.ts]"]
  node_gitgateway["Git gateway<br/>[gateway.ts]"]
end

subgraph group_integrations["External Services"]
  node_forge["Forge integration<br/>[service.ts]"]
  node_docker["Docker engine<br/>[engine.ts]"]
  node_provider(("Agent providers"))
  node_forgehost(("Git forge"))
end

node_user(("User"))

node_user -->|"uses"| node_web
node_web -->|"requests through"| node_api
node_api -->|"sends HTTP"| node_core
node_core -.->|"serves ticket routes"| node_tickets
node_core -.->|"serves run routes"| node_runs
node_core -->|"starts scheduler"| node_scheduler
node_core -->|"uses state"| node_db
node_core -->|"uses settings"| node_config
node_tickets -->|"persists tickets"| node_db
node_tickets -.->|"starts ticket runs"| node_runs
node_scheduler -->|"dispatches runs"| node_runs
node_scheduler -->|"checks terminal capacity"| node_bridge
node_runs -.->|"controls sessions"| node_bridge
node_bridge -->|"connects to daemon"| node_ptyd
node_commands -->|"executes via"| node_bridge
node_ptyd -->|"runs CLI sessions"| node_provider
node_adapters -.->|"adapts provider CLIs"| node_provider
node_reviewui -->|"loads and submits comments"| node_api
node_user -->|"reviews changes"| node_reviewui
node_runs -.->|"merges approved work"| node_repository
node_repository -->|"uses Git access"| node_gitgateway
node_gitgateway -->|"proxies Git operations"| node_forgehost
node_forge -->|"syncs issues and releases"| node_forgehost
node_factory -->|"reads factory settings"| node_settings
node_user -->|"sets up projects"| node_factory
node_runs -.->|"uses container previews"| node_docker
node_core -->|"registers forge services"| node_forge

click node_web "https://github.com/biohazardious/emberline/blob/main/apps/web/src/App.tsx"
click node_api "https://github.com/biohazardious/emberline/blob/main/apps/web/src/api.ts"
click node_reviewui "https://github.com/biohazardious/emberline/blob/main/apps/web/src/components/review/useReviewCommentsController.ts"
click node_core "https://github.com/biohazardious/emberline/blob/main/apps/core/src/server.ts"
click node_config "https://github.com/biohazardious/emberline/blob/main/apps/core/src/config.ts"
click node_db "https://github.com/biohazardious/emberline/blob/main/apps/core/src/db/schema.ts"
click node_settings "https://github.com/biohazardious/emberline/blob/main/apps/core/src/db/project-settings.ts"
click node_tickets "https://github.com/biohazardious/emberline/blob/main/apps/core/src/tickets/service.ts"
click node_runs "https://github.com/biohazardious/emberline/blob/main/apps/core/src/runs/service.ts"
click node_scheduler "https://github.com/biohazardious/emberline/blob/main/apps/core/src/scheduler/service.ts"
click node_commands "https://github.com/biohazardious/emberline/blob/main/apps/core/src/command-exec.ts"
click node_bridge "https://github.com/biohazardious/emberline/blob/main/apps/core/src/ptyd-bridge.ts"
click node_ptyd "https://github.com/biohazardious/emberline/blob/main/apps/ptyd/src/server.ts"
click node_adapters "https://github.com/biohazardious/emberline/blob/main/packages/adapter-sdk/src/provider.ts"
click node_factory "https://github.com/biohazardious/emberline/blob/main/apps/core/src/factory/roadmap.ts"
click node_repository "https://github.com/biohazardious/emberline/blob/main/apps/core/src/repository/service.ts"
click node_gitgateway "https://github.com/biohazardious/emberline/blob/main/apps/core/src/git-gateway/gateway.ts"
click node_forge "https://github.com/biohazardious/emberline/blob/main/apps/core/src/forge/service.ts"
click node_docker "https://github.com/biohazardious/emberline/blob/main/apps/core/src/docker/engine.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_web,node_api,node_reviewui,node_user toneBlue
class node_core,node_config,node_db,node_settings,node_tickets,node_runs,node_scheduler toneAmber
class node_commands,node_bridge,node_ptyd,node_adapters toneMint
class node_factory,node_repository,node_gitgateway toneRose
class node_forge,node_docker,node_provider,node_forgehost toneIndigo
```

## Components

### Browser Workbench

- [Workbench UI](https://github.com/biohazardious/emberline/blob/main/apps/web/src/App.tsx): `apps/web/src/App.tsx`
- [Web API client](https://github.com/biohazardious/emberline/blob/main/apps/web/src/api.ts): `apps/web/src/api.ts`
- [Review controls](https://github.com/biohazardious/emberline/blob/main/apps/web/src/components/review/useReviewCommentsController.ts): `apps/web/src/components/review/useReviewCommentsController.ts`

### Core Runtime

- [Core HTTP server](https://github.com/biohazardious/emberline/blob/main/apps/core/src/server.ts): `apps/core/src/server.ts`
- [Runtime configuration](https://github.com/biohazardious/emberline/blob/main/apps/core/src/config.ts): `apps/core/src/config.ts`
- [SQLite state](https://github.com/biohazardious/emberline/blob/main/apps/core/src/db/schema.ts): `apps/core/src/db/schema.ts`
- [Project settings](https://github.com/biohazardious/emberline/blob/main/apps/core/src/db/project-settings.ts): `apps/core/src/db/project-settings.ts`
- [Ticket workflow](https://github.com/biohazardious/emberline/blob/main/apps/core/src/tickets/service.ts): `apps/core/src/tickets/service.ts`
- [Run lifecycle](https://github.com/biohazardious/emberline/blob/main/apps/core/src/runs/service.ts): `apps/core/src/runs/service.ts`
- [Usage scheduler](https://github.com/biohazardious/emberline/blob/main/apps/core/src/scheduler/service.ts): `apps/core/src/scheduler/service.ts`

### Agent Execution

- [Command execution](https://github.com/biohazardious/emberline/blob/main/apps/core/src/command-exec.ts): `apps/core/src/command-exec.ts`
- [PTY bridge](https://github.com/biohazardious/emberline/blob/main/apps/core/src/ptyd-bridge.ts): `apps/core/src/ptyd-bridge.ts`
- [Persistent terminals](https://github.com/biohazardious/emberline/blob/main/apps/ptyd/src/server.ts): `apps/ptyd/src/server.ts`
- [Agent adapters](https://github.com/biohazardious/emberline/blob/main/packages/adapter-sdk/src/provider.ts): `packages/adapter-sdk/src/provider.ts`

### Projects and Git

- [Factory planning](https://github.com/biohazardious/emberline/blob/main/apps/core/src/factory/roadmap.ts): `apps/core/src/factory/roadmap.ts`
- [Repository service](https://github.com/biohazardious/emberline/blob/main/apps/core/src/repository/service.ts): `apps/core/src/repository/service.ts`
- [Git gateway](https://github.com/biohazardious/emberline/blob/main/apps/core/src/git-gateway/gateway.ts): `apps/core/src/git-gateway/gateway.ts`

### External Services

- [Forge integration](https://github.com/biohazardious/emberline/blob/main/apps/core/src/forge/service.ts): `apps/core/src/forge/service.ts`
- [Docker engine](https://github.com/biohazardious/emberline/blob/main/apps/core/src/docker/engine.ts): `apps/core/src/docker/engine.ts`
- **Agent providers**
- **Git forge**

### Other components

- **User**

## Connections

- User → Workbench UI: uses
- Workbench UI → Web API client: requests through
- Web API client → Core HTTP server: sends HTTP (evidence: `apps/web/src/api.ts`)
- Core HTTP server → Ticket workflow: serves ticket routes
- Core HTTP server → Run lifecycle: serves run routes
- Core HTTP server → Usage scheduler: starts scheduler (evidence: `apps/core/src/main.ts`)
- Core HTTP server → SQLite state: uses state (evidence: `apps/core/src/server.ts`)
- Core HTTP server → Runtime configuration: uses settings (evidence: `apps/core/src/main.ts`)
- Ticket workflow → SQLite state: persists tickets (evidence: `apps/core/src/tickets/service.ts`)
- Ticket workflow → Run lifecycle: starts ticket runs (evidence: `apps/core/src/tickets/service.ts`)
- Usage scheduler → Run lifecycle: dispatches runs (evidence: `apps/core/src/scheduler/service.ts`)
- Usage scheduler → PTY bridge: checks terminal capacity (evidence: `apps/core/src/scheduler/service.ts`)
- Run lifecycle → PTY bridge: controls sessions
- PTY bridge → Persistent terminals: connects to daemon (evidence: `apps/core/src/ptyd-bridge.ts`)
- Command execution → PTY bridge: executes via (evidence: `apps/core/src/command-exec.ts`)
- Persistent terminals → Agent providers: runs CLI sessions
- Agent adapters → Agent providers: adapts provider CLIs
- Review controls → Web API client: loads and submits comments (evidence: `apps/web/src/components/review/useReviewCommentsController.ts`)
- User → Review controls: reviews changes
- Run lifecycle → Repository service: merges approved work
- Repository service → Git gateway: uses Git access (evidence: `apps/core/src/repository/service.ts`)
- Git gateway → Git forge: proxies Git operations (evidence: `apps/core/src/git-gateway/gateway.ts`)
- Forge integration → Git forge: syncs issues and releases
- Factory planning → Project settings: reads factory settings
- User → Factory planning: sets up projects
- Run lifecycle → Docker engine: uses container previews
- Core HTTP server → Forge integration: registers forge services (evidence: `apps/core/src/server.ts`)
