# lucianoguido/symphony-prelude architecture

> Architecture diagram of the GitHub repository lucianoguido/symphony-prelude, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/lucianoguido/symphony-prelude
- Repository: https://github.com/lucianoguido/symphony-prelude

## Overview

Prelude is a terminal CLI for auditing a website’s AI-readiness and tracing sources surfaced by OpenAI web search. The audit flow fetches a page, runs structural and crawler checks, scores the results, and formats a diagnosis; trace collects search actions, sources, and citations, with an optional audit of discovered URLs. The graph preserves both workflows and their main output layers. Relationships are supported by the README or SOURCE INDEX references; unsampled trace internals are not expanded beyond documented behavior.

Main entry points: [`src/commands/audit.ts`](https://github.com/lucianoguido/symphony-prelude/blob/main/src/commands/audit.ts) (Audit orchestrator), [`src/cli.ts`](https://github.com/lucianoguido/symphony-prelude/blob/main/src/cli.ts) (Command dispatcher), [`src/commands/trace.ts`](https://github.com/lucianoguido/symphony-prelude/blob/main/src/commands/trace.ts) (Trace orchestrator), [`src/analyzers/fetcher.ts`](https://github.com/lucianoguido/symphony-prelude/blob/main/src/analyzers/fetcher.ts) (Page fetch and parse)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["CLI entry"]
  node_cli["Command dispatcher<br/>[cli.ts]"]
end

subgraph group_audit["Readiness audit"]
  node_audit_command["Audit orchestrator<br/>[audit.ts]"]
  node_page_fetch["Page fetch and parse<br/>[fetcher.ts]"]
  node_headings["Heading analysis<br/>[headings.ts]"]
  node_metadata["Metadata analysis<br/>[meta.ts]"]
  node_schema["Schema analysis<br/>[schema.ts]"]
  node_chunking["Content chunking<br/>[chunking.ts]"]
  node_signals["Trust signals<br/>[signals.ts]"]
  node_robots["Crawler access<br/>[robots.ts]"]
  node_scoring["AEO scoring<br/>[aeo-score.ts]"]
end

subgraph group_trace["Search trace"]
  node_trace_command["Trace orchestrator<br/>[trace.ts]"]
  node_trace_report["Trace insights<br/>[trace-report.ts]"]
end

subgraph group_output["Output formatting"]
  node_audit_output["Audit formatters"]
  node_trace_output["Trace formatters<br/>[trace-terminal.ts]"]
end

node_user(("CLI user"))
node_openai["OpenAI Responses API"]
node_websites["Audited websites"]

node_user -->|"runs commands"| node_cli
node_cli -->|"dispatches audit"| node_audit_command
node_cli -->|"dispatches trace"| node_trace_command
node_audit_command -->|"fetches page"| node_page_fetch
node_page_fetch -->|"requests HTML"| node_websites
node_audit_command -->|"analyzes headings"| node_headings
node_audit_command -->|"analyzes metadata"| node_metadata
node_audit_command -->|"analyzes schema"| node_schema
node_audit_command -->|"analyzes content"| node_chunking
node_audit_command -->|"checks signals"| node_signals
node_audit_command -->|"checks crawler rules"| node_robots
node_audit_command -->|"computes score"| node_scoring
node_cli -->|"formats audit"| node_audit_output
node_cli -->|"formats trace"| node_trace_output
node_trace_command -->|"calls Responses API"| node_openai
node_trace_command -->|"optionally audits results"| node_audit_command
node_trace_output -->|"derives insights"| node_trace_report

click node_cli "https://github.com/lucianoguido/symphony-prelude/blob/main/src/cli.ts"
click node_audit_command "https://github.com/lucianoguido/symphony-prelude/blob/main/src/commands/audit.ts"
click node_page_fetch "https://github.com/lucianoguido/symphony-prelude/blob/main/src/analyzers/fetcher.ts"
click node_headings "https://github.com/lucianoguido/symphony-prelude/blob/main/src/analyzers/headings.ts"
click node_metadata "https://github.com/lucianoguido/symphony-prelude/blob/main/src/analyzers/meta.ts"
click node_schema "https://github.com/lucianoguido/symphony-prelude/blob/main/src/analyzers/schema.ts"
click node_chunking "https://github.com/lucianoguido/symphony-prelude/blob/main/src/analyzers/chunking.ts"
click node_signals "https://github.com/lucianoguido/symphony-prelude/blob/main/src/analyzers/signals.ts"
click node_robots "https://github.com/lucianoguido/symphony-prelude/blob/main/src/analyzers/robots.ts"
click node_scoring "https://github.com/lucianoguido/symphony-prelude/blob/main/src/scoring/aeo-score.ts"
click node_trace_command "https://github.com/lucianoguido/symphony-prelude/blob/main/src/commands/trace.ts"
click node_trace_report "https://github.com/lucianoguido/symphony-prelude/blob/main/src/formatters/trace-report.ts"
click node_audit_output "https://github.com/lucianoguido/symphony-prelude/tree/main/src/formatters"
click node_trace_output "https://github.com/lucianoguido/symphony-prelude/blob/main/src/formatters/trace-terminal.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_user toneBlue
class node_audit_command,node_page_fetch,node_headings,node_metadata,node_schema,node_chunking,node_signals,node_robots,node_scoring toneAmber
class node_trace_command,node_trace_report,node_openai toneMint
class node_audit_output,node_trace_output toneRose
class node_websites toneIndigo
```

## Components

### CLI entry

- [Command dispatcher](https://github.com/lucianoguido/symphony-prelude/blob/main/src/cli.ts): `src/cli.ts`

### Readiness audit

- [Audit orchestrator](https://github.com/lucianoguido/symphony-prelude/blob/main/src/commands/audit.ts): `src/commands/audit.ts`
- [Page fetch and parse](https://github.com/lucianoguido/symphony-prelude/blob/main/src/analyzers/fetcher.ts): `src/analyzers/fetcher.ts`
- [Heading analysis](https://github.com/lucianoguido/symphony-prelude/blob/main/src/analyzers/headings.ts): `src/analyzers/headings.ts`
- [Metadata analysis](https://github.com/lucianoguido/symphony-prelude/blob/main/src/analyzers/meta.ts): `src/analyzers/meta.ts`
- [Schema analysis](https://github.com/lucianoguido/symphony-prelude/blob/main/src/analyzers/schema.ts): `src/analyzers/schema.ts`
- [Content chunking](https://github.com/lucianoguido/symphony-prelude/blob/main/src/analyzers/chunking.ts): `src/analyzers/chunking.ts`
- [Trust signals](https://github.com/lucianoguido/symphony-prelude/blob/main/src/analyzers/signals.ts): `src/analyzers/signals.ts`
- [Crawler access](https://github.com/lucianoguido/symphony-prelude/blob/main/src/analyzers/robots.ts): `src/analyzers/robots.ts`
- [AEO scoring](https://github.com/lucianoguido/symphony-prelude/blob/main/src/scoring/aeo-score.ts): `src/scoring/aeo-score.ts`

### Search trace

- [Trace orchestrator](https://github.com/lucianoguido/symphony-prelude/blob/main/src/commands/trace.ts): `src/commands/trace.ts`
- [Trace insights](https://github.com/lucianoguido/symphony-prelude/blob/main/src/formatters/trace-report.ts): `src/formatters/trace-report.ts`

### Output formatting

- [Audit formatters](https://github.com/lucianoguido/symphony-prelude/tree/main/src/formatters): `src/formatters`
- [Trace formatters](https://github.com/lucianoguido/symphony-prelude/blob/main/src/formatters/trace-terminal.ts): `src/formatters/trace-terminal.ts`

### Other components

- **CLI user**
- **OpenAI Responses API**
- **Audited websites**

## Connections

- CLI user → Command dispatcher: runs commands (evidence: `README.md`)
- Command dispatcher → Audit orchestrator: dispatches audit (evidence: `src/cli.ts`)
- Command dispatcher → Trace orchestrator: dispatches trace (evidence: `src/cli.ts`)
- Audit orchestrator → Page fetch and parse: fetches page (evidence: `src/commands/audit.ts`)
- Page fetch and parse → Audited websites: requests HTML (evidence: `src/analyzers/fetcher.ts`)
- Audit orchestrator → Heading analysis: analyzes headings (evidence: `src/commands/audit.ts`)
- Audit orchestrator → Metadata analysis: analyzes metadata (evidence: `src/commands/audit.ts`)
- Audit orchestrator → Schema analysis: analyzes schema (evidence: `src/commands/audit.ts`)
- Audit orchestrator → Content chunking: analyzes content (evidence: `src/commands/audit.ts`)
- Audit orchestrator → Trust signals: checks signals (evidence: `src/commands/audit.ts`)
- Audit orchestrator → Crawler access: checks crawler rules (evidence: `src/commands/audit.ts`)
- Audit orchestrator → AEO scoring: computes score (evidence: `src/commands/audit.ts`)
- Command dispatcher → Audit formatters: formats audit (evidence: `src/cli.ts`)
- Command dispatcher → Trace formatters: formats trace (evidence: `src/cli.ts`)
- Trace orchestrator → OpenAI Responses API: calls Responses API (evidence: `src/commands/trace.ts`)
- Trace orchestrator → Audit orchestrator: optionally audits results (evidence: `src/commands/trace.ts`)
- Trace formatters → Trace insights: derives insights (evidence: `src/formatters/trace-terminal.ts`)
