Skip to main content

Architecture Overview

Goblin is a multi-agent orchestration system that automates software development through Linear integration.

System Architecture​

┌──────────────────────────────────────────────────────────────────┐
│                        EXTERNAL SERVICES                          │
├──────────┬──────────┬──────────┬──────────────────────────────────┤
│  Linear  │  GitHub  │  Slack   │           AWS EC2                │
└────┬─────┴────┬─────┴────┬─────┴──────────────┬───────────────────┘
     │          │          │                    │
     ▼          ▼          ▼                    ▼
┌──────────────────────────────────────────────────────────────────┐
│                         CLI COMMANDS                              │
│  goblin run | sync | pipeline | agent | coordinator | status     │
└──────────────────────────────────────────────────────────────────┘
     │
     ▼
┌──────────────────────────────────────────────────────────────────┐
│                        CORE SERVICES                              │
├─────────────────┬─────────────────┬──────────────────────────────┤
│  MayorDaemon    │  PipelineRunner │  Dashboard (FastAPI)         │
│  - Orchestrates │  - Watches      │  - WebSocket updates         │
│  - Monitors     │    signals      │  - Real-time monitoring      │
│    Linear       │  - Spawns       │                              │
│                 │    agents       │                              │
├─────────────────┼─────────────────┼──────────────────────────────┤
│  Coordinator    │  Heartbeat      │  Notifications               │
│  - Unified      │  - Detects      │  - Slack                     │
│    worker       │    crashes      │  - Linear comments           │
│    interface    │  - Stalls       │  - Desktop                   │
├─────────────────┴─────────────────┴──────────────────────────────┤
│  Static Analysis (Ruff + mypy)  │  Preview Manager              │
└──────────────────────────────────────────────────────────────────┘
     │
     ▼
┌──────────────────────────────────────────────────────────────────┐
│                       AGENT PIPELINE                              │
│                                                                   │
│   [SCOPER] ──▶ [BUILDER] ──▶ [REVIEWER] ──▶ [TESTER] ──▶ [DONE] │
│                    ▲              │              │                │
│                    └──────────────┴──────────────┘                │
│                         (feedback loops)                          │
└──────────────────────────────────────────────────────────────────┘
     │
     ▼
┌──────────────────────────────────────────────────────────────────┐
│                          STORAGE                                  │
├─────────────────────────────────┬────────────────────────────────┤
│         SQLite (goblin.db)      │       Git Worktrees            │
│  - pipelines                    │  - Isolated per issue          │
│  - agents                       │  - Parallel work               │
│  - projects                     │  - Clean diffs                 │
│  - preview_environments         │                                │
└─────────────────────────────────┴────────────────────────────────┘

Directory Structure​

goblin/
├── cli/                      # CLI commands (Typer)
│   ├── main.py               # Entry point, registers commands
│   └── commands/             # Command modules
│       ├── run.py
│       ├── sync.py
│       ├── pipeline.py
│       └── ...
├── core/                     # Business logic
│   ├── pipeline/             # Pipeline package
│   │   ├── models.py         # Pipeline, PipelineStage
│   │   └── __init__.py       # Re-exports
│   ├── _pipeline_impl.py     # PipelineManager
│   ├── worktree.py           # Git worktree isolation
│   ├── agent.py              # Agent lifecycle
│   ├── coordinator.py        # Worker coordination
│   ├── specialist.py         # Specialist agents
│   ├── scope.py              # ScopeResult schema
│   ├── static_analysis.py    # Ruff + mypy
│   └── notes.py              # GOBLIN_NOTES.md
├── services/
│   ├── pipeline_runner.py    # Signal watcher
│   ├── daemon.py             # MayorDaemon
│   ├── dashboard.py          # FastAPI + WebSocket
│   └── linear_notifications.py
├── integrations/
│   └── linear.py             # Linear GraphQL client
├── cloud/
│   ├── ec2.py                # EC2 provider
│   ├── digitalocean.py       # DO provider
│   └── preview.py            # Preview manager
└── storage/
    ├── db.py                 # SQLite wrapper
    ├── schema.sql            # Database schema
    └── git.py                # Git operations

Key Components​

MayorDaemon​

The background orchestrator that:

  • Polls Linear for assigned issues
  • Starts pipelines automatically
  • Monitors agent health
  • Handles restarts and recovery

PipelineRunner​

Watches for signal files and manages stage transitions:

  • .goblin/scope-complete → Start BUILD
  • .goblin/build-complete → Start REVIEW
  • .goblin/review-approved → Start TEST
  • .goblin/review-changes-requested → Back to BUILD
  • .goblin/test-passed → DONE
  • .goblin/test-failed → Back to REVIEW

Coordinator​

Provides a unified interface for managing workers:

  • Agent spawning and termination
  • Status aggregation across projects
  • Load balancing
  • Health monitoring

Dashboard​

Real-time monitoring via FastAPI + WebSocket:

  • Pipeline status visualization
  • Agent activity logs
  • Preview environment links
  • Linear issue sync status

Data Flow​

  1. Issue Detection: MayorDaemon polls Linear, finds assigned issue
  2. Pipeline Creation: Creates pipeline record, initializes worktree
  3. Agent Spawning: Spawns Claude Code agent in tmux session
  4. Stage Execution: Agent works, signals completion via file
  5. Transition: PipelineRunner detects signal, spawns next agent
  6. Notification: Updates posted to Linear, Slack
  7. Completion: PR created, issue reassigned

Next Steps​