Crush Architecture Overview: A Four-Layer Design for an AI Coding Agent

Forum topic · 小凯 · 2026-02-14

Summary

Chapter 11 of the 'Crush from Beginner to Master' series examines the overall architecture of Crush, an AI-powered coding assistant built in Go. The system follows a classic four-layer architecture: Presentation Layer (TUI Model, dialogs, chat view using Bubble Tea), Application Layer (App with dependency injection, Coordinator agent, Session Service), Domain Layer (Agent core, 20+ tools, message system), and Infrastructure Layer (config, SQLite database, LSP and MCP integrations). The article details module dependency relationships, tracing how the cmd entry point flows through app to config, agent, and session subsystems, and down to db, pubsub, csync, and oauth. A step-by-step request processing flow illustrates how user input becomes an LLM call, tool execution, and persisted message. The core tech stack is listed, including Go 1.25+, the fantasy AI framework, catwalk for model abstraction, Bubble Tea for TUI, Lipgloss for styling, modernc SQLite, powernap with jsonrpc2 for LSP, and the official MCP Go SDK.

Architecture Overview

Crush follows a classic layered architecture, organized top-down into four distinct layers:

Presentation Layer — TUI Model (Bubble Tea), Dialogs, Chat View
Application Layer — App (dependency injection), Coordinator (Agent), Session Service
Domain Layer — Agent (AI core), Tools (20+ tools), Message (messaging system)
Infrastructure Layer — Config, Database (SQLite), LSP/MCP (external integrations)

Module Dependencies

The dependency graph starts at the cmd entry point and flows into app. From there it branches into three top-level subsystems:

config (configuration management)
agent (AI core), which depends on lsp, tools, and message
session (session management), which depends on permission

The message subsystem further branches into db, pubsub, csync, and oauth.

Request Processing Flow

1. User input 2. TUI Model (Bubble Tea) — receives input and validates format 3. App.Run() — creates or retrieves a session and routes to the Coordinator 4. Coordinator.Run() — builds the prompt, selects a model, and adds context 5. SessionAgent.Run() — calls the LLM API, parses the response, and handles tool calls 6. Tool Execution — performs permission checks, runs the tool, and returns results 7. Message Service (persistence) — saves messages and tool calls 8. TUI Update — renders messages and tool results 9. Response returned to the user

Core Technology Stack

Language — Go 1.25+ (performance, concurrency, native support)
AI framework — fantasy (the official Charm AI framework)
Model management — catwalk (multi-model abstraction layer)
TUI framework — Bubble Tea (the official Charm TUI framework)
Terminal styling — Lipgloss (the official Charm styling library)
Database — SQLite via the pure-Go modernc driver (embedded, no dependencies)
LSP — powernap + jsonrpc2 (lightweight LSP client)
MCP — go-sdk (the official Model Context Protocol SDK)

---

*This article is Chapter 11 of the 'Crush from Beginner to Master' series.*