> ## Documentation Index
> Fetch the complete documentation index at: https://lab.pollack.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Architecture

> Three modules, two protocols, zero API keys

## Module Structure

```
bud/
├── bud-core          Pure Java library (zero Spring dependencies)
├── bud-mcp-server    Spring Boot app with @McpTool annotations
└── bud-acp-server    ACP agent — LLM classification + orchestration
```

### bud-core

The foundation. Reference project extraction, POM mutation (via `maven-model`), JavaParser-based refactoring, project analysis, intent classification, and execution planning. **Zero Spring framework dependencies** — enforced by ArchUnit rules.

Key classes:

* `TemplateExtractor` — Extracts reference projects from classpath using JDK ClassLoader + manifest files
* `PomMutator` — Read/write Maven POM files (add/remove dependencies, set versions, add plugins)
* `JavaParserRefactor` — AST-based package rename for extracted projects
* `RecipeCatalog` — Composable recipes (actuator, security, CI, native image, etc.)
* `StartersCatalog` — Searchable index of Spring Boot starters
* `BootProjectAnalyzer` — Analyze existing projects for dependencies, structure, test strategy
* `BudWorkflow` — Full pipeline orchestrator: normalize → classify → resolve → plan → execute → recipes → explain
* `ExecutionPlanner` — Routes resolved intents to CACHE, INITIALIZR, or EXPAND tiers
* `TemplateSemanticCache` — Subset-matching cache: intent capabilities ⊆ reference project capabilities

### bud-mcp-server

Spring Boot 4.1.0-M2 application that wraps bud-core with 23 `@McpTool`-annotated methods. Communicates via stdio JSON-RPC (MCP protocol). This is the tool layer — it has no AI, no LLM calls, no opinions about what to do. It just exposes deterministic operations.

### bud-acp-server

The product. An ACP agent with two LLM roles:

* **Classifier** (Sonnet via your approved CLI, \~\$0.01/call) — Analyzes prompts via structured output JSON schema. Extracts capabilities, domain entities, best-fit reference project, and overlay level.
* **Expander** (Sonnet via your approved CLI, \~\$0.19/call) — Generates domain-specific code for EXPAND-tier requests. Only invoked for business domain prompts.

## Three-Tier Routing

When Bud receives a prompt, it classifies the intent and routes to one of three execution tiers:

```
"create a greeting api"           → CACHE (spring-boot-rest reference project)
"spring boot app with Gradle"     → INITIALIZR (start.spring.io)
"build a customer management app" → EXPAND (reference project + AI domain code gen)
```

| Tier           | When                                       | Speed | LLM Cost                  |
| -------------- | ------------------------------------------ | ----- | ------------------------- |
| **CACHE**      | Prompt matches one of 9 reference projects | \~1s  | Classification only       |
| **INITIALIZR** | Boot 3.x, Gradle, or no reference match    | \~3s  | Classification only       |
| **EXPAND**     | Business domain entity detected            | \~30s | Classification + code gen |

The execution planner applies a 6-rule cascade to determine the tier. Rules are ordered so that domain prompts with entities (customer, order, inventory) always route to EXPAND, even if a reference project partially matches.

## Protocol Stack

```
┌─────────────────────────────────────┐
│  JetBrains IDE (AI Chat)            │
│  ← ACP protocol (stdio NDJSON)   → │
├─────────────────────────────────────┤
│  BudAgent (@AcpAgent)               │
│  ← BudWorkflow pipeline →          │
├─────────────────────────────────────┤
│  LlmIntentClassifier (Sonnet)       │
│  ← AgentClient SDK →               │
├─────────────────────────────────────┤
│  Your Approved CLI (Expander)       │
│  ← MCP protocol (stdio JSON-RPC) → │
├─────────────────────────────────────┤
│  Bud MCP Server (23 tools)          │
│  ← Java method calls →              │
├─────────────────────────────────────┤
│  bud-core (pure Java)               │
└─────────────────────────────────────┘
```

Two protocol boundaries, both stdio-based:

1. **ACP** — IDE ↔ BudAgent (session management, prompt/response)
2. **MCP** — Claude Code ↔ Bud MCP Server (tool discovery, tool invocation)

## Enterprise Model

* **No API key** — Bud delegates all LLM calls to your enterprise-approved agentic CLI (Claude Code, Gemini CLI, Codex, etc.)
* **No billing exposure** — the CLI handles authentication and billing
* **No compliance review** — your IT department already approved the CLI
* **Swap providers freely** — change your CLI, Bud keeps working. No vendor lock-in on the AI side.
* **Deterministic tools** — the 23 MCP tools don't call any LLM; scaffolding is pure code operations

The LLM (running on your approved CLI) is involved in two places: **intent classification** (understanding what you asked for) and **code expansion** (generating domain-specific code for business apps). The reference project scaffolding itself is deterministic.

## Key Dependencies

| Dependency                     | Purpose                      | Module         |
| ------------------------------ | ---------------------------- | -------------- |
| `javaparser-core` 3.28.0       | AST-based package rename     | bud-core       |
| `maven-model` 3.9.6            | POM read/write               | bud-core       |
| `spring-ai-starter-mcp-server` | `@McpTool` + stdio transport | bud-mcp-server |
| `acp-agent-support`            | `@AcpAgent` + ACP runtime    | bud-acp-server |
| `agent-client-core`            | Portable CLI abstraction     | bud-acp-server |
| `agent-claude`                 | Claude Code CLI provider     | bud-acp-server |