# ember-nexus/next-doc architecture

> Architecture diagram of the GitHub repository ember-nexus/next-doc, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ember-nexus/next-doc
- Repository: https://github.com/ember-nexus/next-doc

## Overview

Next Doc is an Astro documentation site for the Ember Nexus API, with HTML and plain-Markdown documentation surfaces. The principal workflow is readers opening API or guide documentation, which is organized through shared routes/navigation and rendered with OpenAPI-derived request and response detail. Separate outputs include schema and command references, searchable graph/table examples, and an LLM-oriented Markdown index. The tree and excerpts establish some wiring, especially the llms.txt path; links for unsampled route implementations are intentionally limited.

Main entry points: [`core/src/pages`](https://github.com/ember-nexus/next-doc/tree/main/core/src/pages) (Documentation pages), [`core/src/lib/routes.ts`](https://github.com/ember-nexus/next-doc/blob/main/core/src/lib/routes.ts) (Route helpers), [`core/src/lib/llms.ts`](https://github.com/ember-nexus/next-doc/blob/main/core/src/lib/llms.ts) (Markdown navigation body), [`core/src/pages/llms.txt.ts`](https://github.com/ember-nexus/next-doc/blob/main/core/src/pages/llms.txt.ts) (llms.txt endpoint)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_content["Docs content"]
  node_docs_pages["Documentation pages"]
  node_collections[("Content collections<br/>[collections.ts]")]
  node_sidebar["Navigation builder<br/>[sidebar.ts]"]
  node_routes["Route helpers<br/>[routes.ts]"]
end

subgraph group_reference["API reference"]
  node_api_page["Endpoint reference<br/>[&#91;endpoint&#93;.md.ts]"]
  node_schema_page["Schema reference<br/>[&#91;schema&#93;.md.ts]"]
  node_command_page["Command reference<br/>[&#91;command&#93;.md.ts]"]
  node_swagger["OpenAPI extraction<br/>[SwaggerUtil.ts]"]
  node_api_cards["Request response cards<br/>[index.ts]"]
end

subgraph group_render["Rendering"]
  node_mdmx["Markdown components<br/>[index.ts]"]
  node_md_runtime["Markdown JSX runtime<br/>[jsx-runtime.ts]"]
  node_serialize["Markdown serializer<br/>[serialize.ts]"]
  node_rehype["Content augmentations<br/>[index.ts]"]
  node_expressive["Code rendering<br/>[index.ts]"]
  node_graph["Interactive graph<br/>[Graph.ts]"]
  node_json_table["JSON data table<br/>[JsonTable.ts]"]
end

subgraph group_outputs["Site outputs"]
  node_llms_route["llms.txt endpoint<br/>[llms.txt.ts]"]
  node_llms_body["Markdown navigation body<br/>[llms.ts]"]
  node_markdown_route["Page Markdown endpoint<br/>[&#91;...slug&#93;.md.ts]"]
  node_open_graph["Social preview image<br/>[&#91;...slug&#93;.png.ts]"]
end

node_reader(("Documentation reader"))

node_reader -->|"opens docs"| node_docs_pages
node_collections -->|"organizes navigation"| node_sidebar
node_routes -->|"provides paths"| node_sidebar
node_docs_pages -->|"maps page routes"| node_routes
node_api_page -->|"extracts API details"| node_swagger
node_api_page -->|"appends reference cards"| node_api_cards
node_schema_page -->|"uses schema details"| node_swagger
node_command_page -->|"uses command paths"| node_routes
node_mdmx -->|"renders Markdown JSX"| node_md_runtime
node_rehype -->|"augments content"| node_docs_pages
node_expressive -->|"renders code"| node_docs_pages
node_graph -->|"displays graph data"| node_reader
node_json_table -->|"displays JSON records"| node_reader
node_llms_route -->|"builds index body"| node_llms_body
node_llms_route -->|"serializes body"| node_serialize
node_llms_body -->|"reads navigation"| node_sidebar
node_llms_body -->|"rewrites links"| node_routes
node_markdown_route -->|"emits Markdown"| node_serialize
node_reader -->|"requests index"| node_llms_route
node_reader -->|"requests Markdown"| node_markdown_route
node_reader -.->|"requests preview"| node_open_graph

click node_docs_pages "https://github.com/ember-nexus/next-doc/tree/main/core/src/pages"
click node_collections "https://github.com/ember-nexus/next-doc/blob/main/core/src/lib/collections.ts"
click node_sidebar "https://github.com/ember-nexus/next-doc/blob/main/core/src/lib/sidebar.ts"
click node_routes "https://github.com/ember-nexus/next-doc/blob/main/core/src/lib/routes.ts"
click node_api_page "https://github.com/ember-nexus/next-doc/blob/main/core/src/pages/api/%5Bendpoint%5D.md.ts"
click node_schema_page "https://github.com/ember-nexus/next-doc/blob/main/core/src/pages/schema/%5Bschema%5D.md.ts"
click node_command_page "https://github.com/ember-nexus/next-doc/blob/main/core/src/pages/command/%5Bcommand%5D.md.ts"
click node_swagger "https://github.com/ember-nexus/next-doc/blob/main/core/src/util/SwaggerUtil.ts"
click node_api_cards "https://github.com/ember-nexus/next-doc/blob/main/core/src/mdmx/cards/index.ts"
click node_mdmx "https://github.com/ember-nexus/next-doc/blob/main/core/src/mdmx/registry/index.ts"
click node_md_runtime "https://github.com/ember-nexus/next-doc/blob/main/core/src/mdmx/jsx-runtime.ts"
click node_serialize "https://github.com/ember-nexus/next-doc/blob/main/core/src/mdmx/serialize.ts"
click node_rehype "https://github.com/ember-nexus/next-doc/blob/main/core/src/plugins/rehype/index.ts"
click node_expressive "https://github.com/ember-nexus/next-doc/blob/main/core/src/plugins/expressiveCode/index.ts"
click node_graph "https://github.com/ember-nexus/next-doc/blob/main/core/src/component/Lit/Graph/Graph.ts"
click node_json_table "https://github.com/ember-nexus/next-doc/blob/main/core/src/component/Lit/JsonTable.ts"
click node_llms_route "https://github.com/ember-nexus/next-doc/blob/main/core/src/pages/llms.txt.ts"
click node_llms_body "https://github.com/ember-nexus/next-doc/blob/main/core/src/lib/llms.ts"
click node_markdown_route "https://github.com/ember-nexus/next-doc/blob/main/core/src/pages/%5B...slug%5D.md.ts"
click node_open_graph "https://github.com/ember-nexus/next-doc/blob/main/core/src/pages/open-graph/%5B...slug%5D.png.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_docs_pages,node_collections,node_sidebar,node_routes toneBlue
class node_api_page,node_schema_page,node_command_page,node_swagger,node_api_cards toneAmber
class node_mdmx,node_md_runtime,node_serialize,node_rehype,node_expressive,node_graph,node_json_table toneMint
class node_llms_route,node_llms_body,node_markdown_route,node_open_graph toneRose
class node_reader toneIndigo
```

## Components

### Docs content

- [Documentation pages](https://github.com/ember-nexus/next-doc/tree/main/core/src/pages): `core/src/pages`
- [Content collections](https://github.com/ember-nexus/next-doc/blob/main/core/src/lib/collections.ts): `core/src/lib/collections.ts`
- [Navigation builder](https://github.com/ember-nexus/next-doc/blob/main/core/src/lib/sidebar.ts): `core/src/lib/sidebar.ts`
- [Route helpers](https://github.com/ember-nexus/next-doc/blob/main/core/src/lib/routes.ts): `core/src/lib/routes.ts`

### API reference

- [Endpoint reference](https://github.com/ember-nexus/next-doc/blob/main/core/src/pages/api/%5Bendpoint%5D.md.ts): `core/src/pages/api/[endpoint].md.ts`
- [Schema reference](https://github.com/ember-nexus/next-doc/blob/main/core/src/pages/schema/%5Bschema%5D.md.ts): `core/src/pages/schema/[schema].md.ts`
- [Command reference](https://github.com/ember-nexus/next-doc/blob/main/core/src/pages/command/%5Bcommand%5D.md.ts): `core/src/pages/command/[command].md.ts`
- [OpenAPI extraction](https://github.com/ember-nexus/next-doc/blob/main/core/src/util/SwaggerUtil.ts): `core/src/util/SwaggerUtil.ts`
- [Request response cards](https://github.com/ember-nexus/next-doc/blob/main/core/src/mdmx/cards/index.ts): `core/src/mdmx/cards/index.ts`

### Rendering

- [Markdown components](https://github.com/ember-nexus/next-doc/blob/main/core/src/mdmx/registry/index.ts): `core/src/mdmx/registry/index.ts`
- [Markdown JSX runtime](https://github.com/ember-nexus/next-doc/blob/main/core/src/mdmx/jsx-runtime.ts): `core/src/mdmx/jsx-runtime.ts`
- [Markdown serializer](https://github.com/ember-nexus/next-doc/blob/main/core/src/mdmx/serialize.ts): `core/src/mdmx/serialize.ts`
- [Content augmentations](https://github.com/ember-nexus/next-doc/blob/main/core/src/plugins/rehype/index.ts): `core/src/plugins/rehype/index.ts`
- [Code rendering](https://github.com/ember-nexus/next-doc/blob/main/core/src/plugins/expressiveCode/index.ts): `core/src/plugins/expressiveCode/index.ts`
- [Interactive graph](https://github.com/ember-nexus/next-doc/blob/main/core/src/component/Lit/Graph/Graph.ts): `core/src/component/Lit/Graph/Graph.ts`
- [JSON data table](https://github.com/ember-nexus/next-doc/blob/main/core/src/component/Lit/JsonTable.ts): `core/src/component/Lit/JsonTable.ts`

### Site outputs

- [llms.txt endpoint](https://github.com/ember-nexus/next-doc/blob/main/core/src/pages/llms.txt.ts): `core/src/pages/llms.txt.ts`
- [Markdown navigation body](https://github.com/ember-nexus/next-doc/blob/main/core/src/lib/llms.ts): `core/src/lib/llms.ts`
- [Page Markdown endpoint](https://github.com/ember-nexus/next-doc/blob/main/core/src/pages/%5B...slug%5D.md.ts): `core/src/pages/[...slug].md.ts`
- [Social preview image](https://github.com/ember-nexus/next-doc/blob/main/core/src/pages/open-graph/%5B...slug%5D.png.ts): `core/src/pages/open-graph/[...slug].png.ts`

### Other components

- **Documentation reader**

## Connections

- Documentation reader → Documentation pages: opens docs
- Content collections → Navigation builder: organizes navigation
- Route helpers → Navigation builder: provides paths
- Documentation pages → Route helpers: maps page routes
- Endpoint reference → OpenAPI extraction: extracts API details
- Endpoint reference → Request response cards: appends reference cards
- Schema reference → OpenAPI extraction: uses schema details
- Command reference → Route helpers: uses command paths
- Markdown components → Markdown JSX runtime: renders Markdown JSX
- Content augmentations → Documentation pages: augments content
- Code rendering → Documentation pages: renders code
- Interactive graph → Documentation reader: displays graph data
- JSON data table → Documentation reader: displays JSON records
- llms.txt endpoint → Markdown navigation body: builds index body
- llms.txt endpoint → Markdown serializer: serializes body
- Markdown navigation body → Navigation builder: reads navigation
- Markdown navigation body → Route helpers: rewrites links
- Page Markdown endpoint → Markdown serializer: emits Markdown
- Documentation reader → llms.txt endpoint: requests index
- Documentation reader → Page Markdown endpoint: requests Markdown
- Documentation reader → Social preview image: requests preview