ARCHITECTURE_DIAGRAMS (Canonical)

Executive summary

This page contains the project’s canonical Mermaid diagram set (system architecture, run lifecycle, RAG flows, Git/snapshots, security boundaries, F1 selection editor, docs/HTML export). Every other spec page should reference these diagrams rather than maintaining its own copies.

What this page controls

• The authoritative Mermaid diagram text for the whole spec pack.

• Diagram IDs (stable anchors) so the /docs mirror and HTML export can deep-link reliably.

Who should read this

• Product architect, backend architect, DevOps architect, iOS lead, security lead, docs lead.

Source of Truth status

• Authority: Architecture

• Status: Approved

• Primary sync targets: docs/ARCHITECTURE_DIAGRAMS.md

Dependencies / related specs

• Master hub (SoT rules): 🛠️AI-Coding-Agent-Workspace-Spec-Pack

• B0 infrastructure: 🖥️B0-Production-Infrastructure

• B1 core app: 🧱B1-Laravel-Web-Core

• RAG system: 🧠04-RAG-System

• Providers: 🤖05-Agent-Providers

• Claude Code bundle: 📁C2-Claude-Code-Bundle

• F1 selection editor: ✨F1-AI-Selection-Editor

Diagram set

D-01 · High-level system architecture

flowchart LR
	Web(["Web operator<br>Filament + Livewire"]) -->|HTTPS + Reverb WS| API["Laravel API + Control Center"]
	IOS(["iPhone operator<br>SwiftUI"]) -->|HTTPS + SSE| API
	API --> ORCH["AgentRunOrchestrator"]
	ORCH --> PROV{"Provider"}
	PROV -->|OpenAI API| OAI["OpenAI"]
	PROV -->|Claude API| CLA["Anthropic"]
	PROV -->|Claude Code adapter| CC["Claude Code CLI"]
	ORCH --> RAG["RagContextService"]
	ORCH --> WS["WorkspaceService<br>(isolated repo)"]
	ORCH --> GIT["GitService"]
	ORCH --> SNAP["SnapshotService"]
	ORCH --> DOCS["DocumentationAutoUpdateService"]
	ORCH --> EVT["ConsoleEventService<br>(agent_events)"]
	EVT -->|SSE / WebSocket| API
	WS --> FS[("Project workspace<br>on disk")]
	RAG --> SQL[("MySQL/MariaDB<br>rag_chunks")]

D-02 · Agent run lifecycle

stateDiagram-v2
	[*] --> draft
	draft --> queued: start()
	queued --> running: worker picked up
	running --> waiting_for_user: agent needs input
	waiting_for_user --> running: user responds
	running --> paused: user pause()
	paused --> running: resume()
	running --> completed: final_summary
	running --> failed: fatal error
	running --> cancelled: user cancel()
	completed --> [*]
	failed --> [*]
	cancelled --> [*]

D-03 · RAG indexing pipeline

flowchart LR
	A["changed file"] --> B["Detect source_type"]
	B --> C["Chunker emits chunks"]
	C --> D["Normalize + content_hash"]
	D --> E{"hash exists?"}
	E -- yes --> X["skip"]
	E -- no --> F["Embeddings provider"]
	F --> G["Upsert rag_chunks"]
	G --> H["emit rag_chunk_indexed event"]

D-04 · RAG retrieval flow (agent prompt assembly)

flowchart TD
	Q["User prompt"] --> R["rag_search(query)"]
	R --> S["TopK chunks + scores"]
	S --> P["Prompt builder<br>(system + constraints + context)"]
	P --> M["Provider model call"]
	M --> T["Tool calls"]
	T -->|results| M
	M --> F["finish(summary)"]

D-05 · Command execution safety (allowlist + snapshots)

flowchart TD
	C["Provider requests run_command"] --> A["CommandPolicyService"]
	A -->|blocked| B["Return structured error<br>emit command_failed"]
	A -->|allowed| S{"destructive?"}
	S -- yes --> P["SnapshotService::pre_command"]
	S -- no --> E["Execute"]
	P --> E["CommandExecutionService::run"]
	E --> L["Persist stdout/stderr + exit_code"]
	L --> EV["Emit command_completed"]

D-06 · Git + branch-per-run + snapshots

flowchart LR
	Start["Run starts"] --> Lock["Acquire workspace lock"]
	Lock --> PreRun["Snapshot pre_run"]
	PreRun --> Branch["Create branch agent/run-{id}-{slug}"]
	Branch --> Work["Edits + commands"]
	Work --> Review["Human review"]
	Review -->|approve| Commit["Optional commit"]
	Commit -->|human only| Push["Optional push"]
	Review -->|reject| Restore["Restore snapshot"]

D-07 · Auto documentation update pipeline

flowchart TD
	Done["Run completed"] --> Scan["Docs analyzers<br>(routes, schema, services)"]
	Scan --> Gen["Generate docs/*"]
	Gen --> Markers["Replace AUTO-GENERATED blocks only"]
	Markers --> Diff["Persist documentation_updates diff"]
	Diff --> Event["Emit docs_updated event"]

D-08 · Server params resolution (runtime overrides)

flowchart LR
	Code["config/agent_workspace.php"] --> Svc["ServerParamService"]
	Svc --> DB[("server_params")]
	DB --> Cache[("Redis cache")]
	Cache --> Runtime["Resolved settings"]
	Runtime --> Consumers["Agents / RAG / Git / Docs / F1"]

D-09 · Provider abstraction (normalized events)

flowchart TD
	ORCH["AgentRunOrchestrator"] --> PR{"AgentProviderInterface"}
	PR --> OAI["OpenAIAgentService"]
	PR --> CLA["ClaudeAgentService"]
	PR --> CC["ClaudeCodeAgentService"]
	OAI --> EV["ProviderEvent(kind,payload)"]
	CLA --> EV
	CC --> EV
	EV --> LOG["ConsoleEventService<br>agent_events"]

D-10 · F1 selection editor flow

flowchart LR
	Sel["User selects text"] --> JS["Global selection layer"]
	JS --> Action["Pick action"]
	Action --> API["POST /api/ai/text/transform (SSE)"]
	API --> Svc["AiTextTransformService"]
	Svc --> Prov["OpenAI / Anthropic"]
	Svc --> Log[("ai_text_transformations")]
	Svc --> UI["Streaming preview"]
	UI --> Apply["Replace / Insert / Copy / Discard"]
	Apply --> Host["Host editor save path"]

D-11 · Security trust boundaries

flowchart LR
	User(["User / iPhone / Web"]) -->|HTTPS| App["Laravel API"]
	App -->|internal only| Git["git binary"]
	App -->|internal only| Shell["allowlisted shell"]
	App -->|outbound| Providers["OpenAI / Anthropic"]
	App --> DB[("MySQL/MariaDB")]
	App --> Redis[("Redis")]
	App --> Storage[("Snapshots (S3/local)")]

D-12 · HTML export + filename sanitation flow

flowchart TD
	N["Notion Markdown mirror"] --> P["Parse + normalize blocks"]
	P --> S["Stable slug + filename sanitizer"]
	S --> H["Render HTML"]
	H --> M{"Mermaid mode"}
	M -->|svg| SVG["Compile mermaid → svg"]
	M -->|runtime| RT["Emit mermaid blocks + mermaid.min.js"]
	SVG --> OUT["Write html/*.html + docs.css"]
	RT --> OUT
	OUT --> RPT["export_report.json<br>(broken links/diagrams)"]

Implementation notes

• Keep diagram IDs stable (D-01..D-12). Other pages should link to these headings, not copy the code.

• When mirroring to repo, this becomes docs/ARCHITECTURE_DIAGRAMS.md and other docs should reference it.

Validation checklist

• Every Mermaid block renders in Notion.

• No diagram duplicates exist elsewhere in the pack (link instead).

• Exporter can deep-link to #d-xx-... anchors reliably.

Risks / gotchas

• Mermaid drift: duplicated diagrams diverge over time (this page prevents that).

• Broken Mermaid syntax breaks HTML export; exporter must lint diagrams.

Done means

• All “architecture-tier” specs link here and remove inline diagrams, except where a small local diagram is critical.

Cursor / Claude Code instructions

• Mirror path: docs/ARCHITECTURE_DIAGRAMS.md.

• Do not edit diagrams elsewhere; edit here, then regenerate mirrors.