# g-cqd/apple-docs architecture

> Architecture diagram of the GitHub repository g-cqd/apple-docs, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/g-cqd/apple-docs
- Repository: https://github.com/g-cqd/apple-docs

## Overview

#### Purpose and entry points
`apple-docs` is a Bun-based, offline Apple-documentation corpus system: it installs or builds a local indexed corpus, then exposes it through CLI, MCP, and web/static-site interfaces. Process entry points are `cli.js` (user CLI) and `index.js` (library/export surface); command parsing and dispatch live in `src/cli/parser.js` and `src/commands/index.js`.

#### Command orchestration
Commands separate user-facing operations from domain implementations: setup/update/sync ingest data; search/lookup/browse read it; snapshot and web-deploy package or publish it. Major command modules are `src/commands/setup.js`, `src/commands/sync.js`, and `src/commands/search.js`. CLI formatters isolate terminal/JSON presentation from command logic in `src/cli/formatter.js`.

#### Source ingestion and corpus pipeline
Source adapters represent Apple DocC, guidelines, WWDC, Swift, package, and archive providers behind a registry: `src/sources/registry.js`, `src/sources/base.js`, `src/sources/apple-docc.js`. Sync coordinates staged discovery, download, conversion, coalescing, and persistence through `src/pipeline/discover.js`, `src/pipeline/download.js`, `src/pipeline/convert.js`, and `src/pipeline/persist.js`. This is the principal external-I/O boundary, with retry/rate-limit support in `src/lib/fetch-with-retry.js` and `src/lib/per-host-rate-limiter.js`.

#### Content normalization and rendering
Raw HTML, Markdown, DocC, and guideline material is transformed into a common document model before storage. The boundary is centered on `src/content/normalize.js`, with format-specific normalization in `src/content/normalize/docc.js` and `src/content/normalize/guidelines.js`; renderers project canonical content to HTML, Markdown, text, or snippets via `src/content/render-html.js` and `src/content/render-markdown.js`. Apple-specific extraction/normalization is contained in `src/apple/extractor.js` and `src/apple/normalizer.js`.

#### Persistent corpus and search
SQLite-oriented storage owns schema migration, profiles, document/source repositories, files, and concurrent read access: `src/storage/database.js`, `src/storage/migrations/index.js`, `src/storage/repos/documents.js`, and `src/storage/reader-pool.js`. Search combines FTS, filtering/ranking, and local semantic-vector retrieval/fusion: `src/search/fts-query-builder.js`, `src/search/semantic.js`, `src/search/fusion.js`, and `src/search/ranking.js`. Storage profiles trade disk for serving/read performance without changing corpus semantics.

#### Delivery surfaces
The MCP server provides read-only stdio and HTTP tool/resource access over the same corpus, with caching, pagination, health, and metrics boundaries in `src/mcp/server.js`, `src/mcp/http-server.js`, and `src/mcp/tools/docs.js`. The web surface can serve dynamically or build static output: `src/web/serve.js`, `src/web/route-registry.js`, and `src/web/build.js`; routes render stored documents and search artifacts rather than crawling sources.

#### Assets, snapshots, and operations
Fonts and SF Symbols are separately synchronized, transformed, stored, and rendered because they require platform/archive/PDF processing: `src/resources/apple-fonts/sync.js`, `src/resources/apple-symbols/sync.js`, and `src/resources/symbol-pdf-to-svg.js`. Snapshot setup/build provides the portable distribution boundary (`src/commands/setup.js`, `src/commands/snapshot.js`). Production operations use Caddy, Cloudflare tunnels/purge, launchd, and optional Prometheus/Grafana monitoring under `ops/caddy/Caddyfile.tpl`, `ops/cloudflared/config.yml.tpl`, and `ops/grafana/docker-compose.yml`.

Main entry points: [`src/storage/database.js`](https://github.com/g-cqd/apple-docs/blob/main/src/storage/database.js) (SQLite corpus), [`src/pipeline/discover.js`](https://github.com/g-cqd/apple-docs/blob/main/src/pipeline/discover.js) (Sync pipeline), [`src/search/semantic.js`](https://github.com/g-cqd/apple-docs/blob/main/src/search/semantic.js) (Search engine), [`src/content/normalize.js`](https://github.com/g-cqd/apple-docs/blob/main/src/content/normalize.js) (Content normalization)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry & Commands"]
  node_cli["CLI entry point<br/>Bun CLI<br/>[cli.js]"]
  node_library["Library exports<br/>module surface<br/>[index.js]"]
  node_parser["Command parser<br/>CLI parsing<br/>[parser.js]"]
  node_commands["Command dispatcher<br/>command orchestration"]
  node_formatters["CLI formatters<br/>presentation<br/>[formatter.js]"]
end

subgraph group_ingest["Ingestion Pipeline"]
  node_sources{{"Source adapters<br/>provider registry<br/>[registry.js]"}}
  node_sync["Sync pipeline<br/>staged ingestion<br/>[discover.js]"]
  node_fetching{{"Resilient fetch<br/>external I/O"}}
  node_normalization["Content normalization<br/>canonical document model<br/>[normalize.js]"]
  node_apple["Apple extraction<br/>Apple content processing<br/>[extractor.js]"]
  node_resources["Fonts &amp; symbols sync<br/>asset pipeline<br/>[sync.js]"]
end

subgraph group_corpus["Corpus &amp; Search"]
  node_storage[("SQLite corpus<br/>persistent corpus<br/>[database.js]")]
  node_search["Search engine<br/>FTS and semantic retrieval<br/>[semantic.js]"]
  node_rendering["Content renderers<br/>HTML and Markdown projection<br/>[render-html.js]"]
end

subgraph group_delivery["Delivery Surfaces"]
  node_mcp["MCP server<br/>tool and resource API<br/>[server.js]"]
  node_web["Web serving<br/>dynamic web surface<br/>[serve.js]"]
  node_staticbuild["Static-site build<br/>static output<br/>[build.js]"]
end

subgraph group_operations["Distribution &amp; Operations"]
  node_snapshot["Snapshot distribution<br/>portable corpus package<br/>[snapshot.js]"]
  node_setup["Setup command<br/>corpus installation<br/>[setup.js]"]
  node_ops{{"Production operations<br/>deployment infrastructure<br/>[Caddyfile.tpl]"}}
end

node_cli -->|"parses"| node_parser
node_parser -->|"dispatches"| node_commands
node_commands -->|"formats results"| node_formatters
node_commands -->|"runs"| node_setup
node_commands -->|"runs"| node_sync
node_commands -->|"queries"| node_search
node_commands -->|"packages"| node_snapshot
node_setup -->|"builds corpus"| node_sync
node_sync -->|"discovers from"| node_sources
node_sync -->|"downloads through"| node_fetching
node_sync -->|"converts to"| node_normalization
node_normalization -->|"uses"| node_apple
node_normalization -->|"persists documents"| node_storage
node_resources -->|"stores assets"| node_storage
node_storage -->|"supplies corpus"| node_search
node_storage -->|"supplies documents"| node_rendering
node_search -->|"returns results"| node_formatters
node_mcp -->|"reads"| node_storage
node_mcp -->|"searches"| node_search
node_web -->|"renders"| node_rendering
node_web -->|"serves search"| node_search
node_staticbuild -->|"generates from"| node_rendering
node_snapshot -->|"packages"| node_storage
node_ops -->|"deploys"| node_web

click node_cli "https://github.com/g-cqd/apple-docs/blob/main/cli.js"
click node_library "https://github.com/g-cqd/apple-docs/blob/main/index.js"
click node_parser "https://github.com/g-cqd/apple-docs/blob/main/src/cli/parser.js"
click node_formatters "https://github.com/g-cqd/apple-docs/blob/main/src/cli/formatter.js"
click node_sources "https://github.com/g-cqd/apple-docs/blob/main/src/sources/registry.js"
click node_sync "https://github.com/g-cqd/apple-docs/blob/main/src/pipeline/discover.js"
click node_fetching "https://github.com/g-cqd/apple-docs/blob/main/src/lib/fetch-with-retry.js"
click node_normalization "https://github.com/g-cqd/apple-docs/blob/main/src/content/normalize.js"
click node_apple "https://github.com/g-cqd/apple-docs/blob/main/src/apple/extractor.js"
click node_resources "https://github.com/g-cqd/apple-docs/blob/main/src/resources/apple-fonts/sync.js"
click node_storage "https://github.com/g-cqd/apple-docs/blob/main/src/storage/database.js"
click node_search "https://github.com/g-cqd/apple-docs/blob/main/src/search/semantic.js"
click node_rendering "https://github.com/g-cqd/apple-docs/blob/main/src/content/render-html.js"
click node_mcp "https://github.com/g-cqd/apple-docs/blob/main/src/mcp/server.js"
click node_web "https://github.com/g-cqd/apple-docs/blob/main/src/web/serve.js"
click node_staticbuild "https://github.com/g-cqd/apple-docs/blob/main/src/web/build.js"
click node_snapshot "https://github.com/g-cqd/apple-docs/blob/main/src/commands/snapshot.js"
click node_setup "https://github.com/g-cqd/apple-docs/blob/main/src/commands/setup.js"
click node_ops "https://github.com/g-cqd/apple-docs/blob/main/ops/caddy/Caddyfile.tpl"

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_library,node_parser,node_commands,node_formatters toneBlue
class node_sources,node_sync,node_fetching,node_normalization,node_apple,node_resources toneAmber
class node_storage,node_search,node_rendering toneMint
class node_mcp,node_web,node_staticbuild toneRose
class node_snapshot,node_setup,node_ops toneIndigo
```

## Components

### Entry & Commands

- [CLI entry point](https://github.com/g-cqd/apple-docs/blob/main/cli.js): Bun CLI · `cli.js`
- [Library exports](https://github.com/g-cqd/apple-docs/blob/main/index.js): module surface · `index.js`
- [Command parser](https://github.com/g-cqd/apple-docs/blob/main/src/cli/parser.js): CLI parsing · `src/cli/parser.js`
- **Command dispatcher**: command orchestration · Routes setup, sync, search, snapshot, and deployment operations.
- [CLI formatters](https://github.com/g-cqd/apple-docs/blob/main/src/cli/formatter.js): presentation · `src/cli/formatter.js`

### Ingestion Pipeline

- [Source adapters](https://github.com/g-cqd/apple-docs/blob/main/src/sources/registry.js): provider registry · Unifies Apple DocC and other documentation providers. · `src/sources/registry.js`
- [Sync pipeline](https://github.com/g-cqd/apple-docs/blob/main/src/pipeline/discover.js): staged ingestion · Discovers, downloads, converts, coalesces, and persists source material. · `src/pipeline/discover.js`
- [Resilient fetch](https://github.com/g-cqd/apple-docs/blob/main/src/lib/fetch-with-retry.js): external I/O · Applies retries and per-host rate limits. · `src/lib/fetch-with-retry.js`
- [Content normalization](https://github.com/g-cqd/apple-docs/blob/main/src/content/normalize.js): canonical document model · Normalizes DocC, guideline, HTML, and Markdown content. · `src/content/normalize.js`
- [Apple extraction](https://github.com/g-cqd/apple-docs/blob/main/src/apple/extractor.js): Apple content processing · `src/apple/extractor.js`
- [Fonts & symbols sync](https://github.com/g-cqd/apple-docs/blob/main/src/resources/apple-fonts/sync.js): asset pipeline · Processes platform archives and symbol PDFs separately from documents. · `src/resources/apple-fonts/sync.js`

### Corpus & Search

- [SQLite corpus](https://github.com/g-cqd/apple-docs/blob/main/src/storage/database.js): persistent corpus · Owns migrations, profiles, repositories, files, and concurrent readers. · `src/storage/database.js`
- [Search engine](https://github.com/g-cqd/apple-docs/blob/main/src/search/semantic.js): FTS and semantic retrieval · Combines FTS, vector retrieval, fusion, filtering, and ranking. · `src/search/semantic.js`
- [Content renderers](https://github.com/g-cqd/apple-docs/blob/main/src/content/render-html.js): HTML and Markdown projection · `src/content/render-html.js`

### Delivery Surfaces

- [MCP server](https://github.com/g-cqd/apple-docs/blob/main/src/mcp/server.js): tool and resource API · Read-only stdio and HTTP access with caching and pagination. · `src/mcp/server.js`
- [Web serving](https://github.com/g-cqd/apple-docs/blob/main/src/web/serve.js): dynamic web surface · Routes render stored documents and search artifacts. · `src/web/serve.js`
- [Static-site build](https://github.com/g-cqd/apple-docs/blob/main/src/web/build.js): static output · `src/web/build.js`

### Distribution & Operations

- [Snapshot distribution](https://github.com/g-cqd/apple-docs/blob/main/src/commands/snapshot.js): portable corpus package · `src/commands/snapshot.js`
- [Setup command](https://github.com/g-cqd/apple-docs/blob/main/src/commands/setup.js): corpus installation · Installs or builds a local indexed corpus. · `src/commands/setup.js`
- [Production operations](https://github.com/g-cqd/apple-docs/blob/main/ops/caddy/Caddyfile.tpl): deployment infrastructure · Caddy, Cloudflare tunnels, launchd, and optional Grafana monitoring. · `ops/caddy/Caddyfile.tpl`

## Connections

- CLI entry point → Command parser: parses
- Command parser → Command dispatcher: dispatches
- Command dispatcher → CLI formatters: formats results
- Command dispatcher → Setup command: runs
- Command dispatcher → Sync pipeline: runs
- Command dispatcher → Search engine: queries
- Command dispatcher → Snapshot distribution: packages
- Setup command → Sync pipeline: builds corpus
- Sync pipeline → Source adapters: discovers from
- Sync pipeline → Resilient fetch: downloads through
- Sync pipeline → Content normalization: converts to
- Content normalization → Apple extraction: uses
- Content normalization → SQLite corpus: persists documents
- Fonts & symbols sync → SQLite corpus: stores assets
- SQLite corpus → Search engine: supplies corpus
- SQLite corpus → Content renderers: supplies documents
- Search engine → CLI formatters: returns results
- MCP server → SQLite corpus: reads
- MCP server → Search engine: searches
- Web serving → Content renderers: renders
- Web serving → Search engine: serves search
- Static-site build → Content renderers: generates from
- Snapshot distribution → SQLite corpus: packages
- Production operations → Web serving: deploys