g-cqd/apple-docs

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.