Modulo 1.5 Architecture Overview - Claude Code Deep Dive

1

🏗️ Six-Layer Architecture

O Claude Code organiza-se em seis camadas distintas:

1. Boot

main.tsx, setup.ts, entrypoints/init.ts -- startup, settings, migrations, session wiring

2. UI Shell

replLauncher.tsx, screens/REPL.tsx -- interface Ink terminal

3. State

state/AppStateStore.ts, bootstrap/state.ts -- immutable AppState e global singleton

4. Query Engine

QueryEngine.ts, query.ts -- conversation lifecycle e API streaming

5. Tools

tools.ts, Tool.ts -- capability registry incluindo Bash, file I/O, agents, MCP

6. Services

API client, MCP connections, context compaction

2

🔀 Data Flow: Prompt to Response

A sequencia completa do input do usuario ate a resposta da API:

1

User enters prompt in REPL

2

processUserInput() handles slash commands

3

System prompt assembled from multiple sources

4

Transcript written to disk BEFORE API call

5

Query loop streams text and tool calls

6

Tools execute with permission checks

7

Response flows back through UI components

8

Session stored as JSONL

💡 Decisao Critica de Design

"The transcript is written before the API call, not after. This is intentional: if the process is killed mid-request, the session is still resumable."

3

🛡️ Permission Architecture

A funcao canUseTool() serve como o unico choke point arquitetural para decisoes de permissao:

default

Pergunta ao usuario para tools fora da allow-list

auto

Permite automaticamente tools safe

bypass

Permite tudo sem perguntar

4

📦 Two-Layer State Model

Layer 1 -- Global Singleton

bootstrap/state.ts

Constantes de process-lifetime: sessionId, cwd, projectRoot, totalCostUSD, token budget counters. Explicitamente nao e React state.

Layer 2 -- React State

state/AppStateStore.ts

DeepImmutable<AppState> contendo messages, MCP clients, permission context, tasks, agents, file history. Atualizado imutavelmente via setAppState().

5

🔄 Session Management & MCP

Session Storage

Sessoes armazenadas como JSONL em ~/.claude/projects/<cwd-hash>/<session-id>.jsonl:

Fire-and-forget transcript writes com 100ms lazy flush
User messages awaited antes da API call
Assistant messages fire-and-forget para preservar streaming
Sessoes resumiveis via loadTranscriptFromFile()

MCP Integration

MCP servers conectam como objetos MCPServerConnection:

Inicializados antes da primeira query
Passados em cada ToolUseContext
Tools, commands, resources adicionados dinamicamente via getMcpToolsCommandsAndResources()
Separados do base tool registry mas integrados na montagem da tool list

6

🧬 Agent Swarms & Hook System

Agent Swarms

O AgentTool permite execucao recursiva:

Cada sub-agente spawna propria instancia de QueryEngine
Tool set restrito do parent
Em swarm mode (ENABLE_AGENT_SWARMS=true), agentes comunicam via UDS messaging
TeamCreateTool para registro de agentes
SendMessageTool para comunicacao inbox

Hook System

Hooks de lifecycle configurados em settings.json:

PreToolUse
PostToolUse
PreCompact
PostCompact
Stop
Notification
FileChanged
SessionStart

⚠️ Security Invariant

Hooks sao snapshotted uma vez no startup via captureHooksConfigSnapshot(). O invariante de seguranca previne injecao mid-session de hooks maliciosos.

7

💎 Key Design Patterns & Critical Invariants

6 Design Patterns

1. Async Generator Threading

Dados fluem como generator yields da API pela UI. yield* compoe toda a stack e backpressure flui naturalmente.

2. Dead Code Elimination

Flags feature() sao avaliados em bundle time pelo Bun, eliminando codigo inatingivel de builds externos e prevenindo vazamento de strings.

3. Cache-Warming for Latency

Caminhos criticos sao pre-aquecidos em paralelo durante o setup: TCP warm-up, keychain reads, MDM policy reads.

4. Immutable AppState + Mutable bootstrap/state

React state imutavel via DeepImmutable; constantes de sessao em module singleton plain.

5. isBareMode() Fast Path

Um unico flag pula React, Ink, UDS, plugins para execucao headless.

6. Parallel Subprocess Investment

Subprocessos disparam cedo e rodam durante avaliacao JavaScript.

Critical Invariants

1. Hooks captured after setCwd() but before any query (security)

2. Transcript written before API call (crash resilience)

3. Tool list stable per build (prompt cache key)

4. Feature gates eliminated at bundle time (deterministic tools)

5. AppState immutable (React change detection)

6. QueryEngine owns full conversation lifecycle

Interactive vs Headless Modes

✅ Interactive (default)

Full Ink/React rendering
Trust dialog on first launch
Session transcript awaited
Deferred prefetches after first render

⚡ Headless (`-p`/`--print`)

Stdout text only
Implicit trust
Fire-and-forget transcript
React never imported

📋 Resumo do Modulo

✅ 6 camadas (Boot, UI Shell, State, Query Engine, Tools, Services) formam o mapa mental completo da arquitetura

✅ Transcript-first reliability: mensagem persistida antes da API call garante crash resilience

✅ canUseTool() e o unico choke point de seguranca com 3 modos (default, auto, bypass)

✅ Two-layer state: bootstrap/state.ts (global singleton) + AppStateStore.ts (immutable React state)

✅ Agent swarms via AgentTool com QueryEngine recursivo e comunicacao UDS

✅ 6 design patterns criticos: generators all the way down, dead code elimination, cache-warming, immutable state, bare mode fast path, parallel subprocesses