# pedronauck/docz architecture

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

- Interactive diagram: https://gitdiagram.com/pedronauck/docz
- Repository: https://github.com/pedronauck/docz

## Overview

Docz turns project MDX and component source into an interactive Gatsby documentation site. Authors configure and write MDX, then run the CLI for live development or a production build; Gatsby discovers documentation and generates pages, while the Docz theme renders navigation, component props, and live playgrounds. The graph includes the documented static-site output and the sampled configuration, state, and rendering layers. Some ingestion and build internals are unsampled, so those links are shown only where the README or source index supports them.

Main entry points: [`core/docz-core/src/cli.ts`](https://github.com/pedronauck/docz/blob/main/core/docz-core/src/cli.ts) (Docz CLI), [`core/docz/src/state.tsx`](https://github.com/pedronauck/docz/blob/main/core/docz/src/state.tsx) (Documentation state), [`core/gatsby-theme-docz/gatsby-node.js`](https://github.com/pedronauck/docz/blob/main/core/gatsby-theme-docz/gatsby-node.js) (Gatsby theme integration), [`core/docz-core/src/config/argv.ts`](https://github.com/pedronauck/docz/blob/main/core/docz-core/src/config/argv.ts) (Arguments and config)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_authoring["Authoring and configuration"]
  node_argv["Arguments and config<br/>[argv.ts]"]
  node_docz_config["Docz config<br/>[docz.ts]"]
  node_plugins["Plugin system<br/>[Plugin.ts]"]
  node_mdx["MDX documents"]
end

subgraph group_generation["Site generation"]
  node_gatsby_theme["Gatsby theme integration<br/>[gatsby-node.js]"]
  node_source_nodes["Document discovery<br/>[sourceNodes.js]"]
  node_page_creation["Page creation"]
  node_remark["Markdown transforms<br/>[index.ts]"]
  node_rehype["HTML transforms<br/>[index.ts]"]
  node_docgen["Component prop parsing"]
end

subgraph group_runtime["Documentation runtime"]
  node_state["Documentation state<br/>[state.tsx]"]
  node_menus["Menu construction<br/>[useMenus.ts]"]
  node_components["Theme components<br/>[useComponents.tsx]"]
  node_props_hook["Props lookup"]
  node_playground["Live playground<br/>[index.js]"]
  node_props_view["Props display<br/>[index.js]"]
end

subgraph group_execution["Development and output"]
  node_cli["Docz CLI<br/>[cli.ts]"]
  node_dev_machine["Development machine<br/>[index.ts]"]
  node_dev_server["Development server<br/>[server.ts]"]
  node_build["Production build<br/>[build.ts]"]
  node_static_site["Static site output"]
end

node_author(("Documentation author"))
node_gatsby["Gatsby runtime"]
node_browser(("Site visitor"))

node_author -->|"writes MDX"| node_mdx
node_author -->|"runs commands"| node_cli
node_cli -.->|"sets options"| node_argv
node_argv -->|"loads defaults"| node_docz_config
node_docz_config -->|"configures plugins"| node_plugins
node_gatsby_theme -->|"registers"| node_source_nodes
node_gatsby_theme -->|"registers"| node_page_creation
node_source_nodes -.->|"creates content nodes"| node_gatsby
node_page_creation -.->|"creates pages"| node_gatsby
node_gatsby -.->|"transforms Markdown"| node_remark
node_gatsby -.->|"transforms markup"| node_rehype
node_gatsby -.->|"extracts component props"| node_docgen
node_gatsby -.->|"provides documentation data"| node_state
node_state -->|"supplies entries"| node_menus
node_state -->|"supplies props"| node_props_hook
node_props_hook -->|"uses components"| node_components
node_playground -->|"renders themed components"| node_components
node_props_view -.->|"queries props"| node_state
node_cli -.->|"starts development"| node_dev_server
node_dev_server -->|"interprets machine"| node_dev_machine
node_cli -.->|"builds site"| node_build
node_build -->|"generates assets"| node_static_site
node_static_site -->|"serves documentation"| node_browser
node_gatsby -.->|"renders theme"| node_playground
node_gatsby -.->|"renders theme"| node_props_view

click node_cli "https://github.com/pedronauck/docz/blob/main/core/docz-core/src/cli.ts"
click node_argv "https://github.com/pedronauck/docz/blob/main/core/docz-core/src/config/argv.ts"
click node_docz_config "https://github.com/pedronauck/docz/blob/main/core/docz-core/src/config/docz.ts"
click node_plugins "https://github.com/pedronauck/docz/blob/main/core/docz-core/src/lib/Plugin.ts"
click node_gatsby_theme "https://github.com/pedronauck/docz/blob/main/core/gatsby-theme-docz/gatsby-node.js"
click node_source_nodes "https://github.com/pedronauck/docz/blob/main/core/gatsby-theme-docz/lib/sourceNodes.js"
click node_page_creation "https://github.com/pedronauck/docz/blob/main/core/gatsby-theme-docz/lib/createPagesStatefully.js"
click node_remark "https://github.com/pedronauck/docz/blob/main/core/remark-docz/src/index.ts"
click node_rehype "https://github.com/pedronauck/docz/blob/main/core/rehype-docz/src/index.ts"
click node_docgen "https://github.com/pedronauck/docz/blob/main/core/docz-core/src/utils/docgen/externalProptypesHandler.ts"
click node_state "https://github.com/pedronauck/docz/blob/main/core/docz/src/state.tsx"
click node_menus "https://github.com/pedronauck/docz/blob/main/core/docz/src/hooks/useMenus.ts"
click node_components "https://github.com/pedronauck/docz/blob/main/core/docz/src/hooks/useComponents.tsx"
click node_props_hook "https://github.com/pedronauck/docz/blob/main/core/docz/src/hooks/useComponentProps.ts"
click node_playground "https://github.com/pedronauck/docz/blob/main/core/gatsby-theme-docz/src/components/Playground/index.js"
click node_props_view "https://github.com/pedronauck/docz/blob/main/core/gatsby-theme-docz/src/components/Props/index.js"
click node_dev_machine "https://github.com/pedronauck/docz/blob/main/core/docz-core/src/bundler/machine/index.ts"
click node_dev_server "https://github.com/pedronauck/docz/blob/main/core/docz-core/src/bundler/server.ts"
click node_build "https://github.com/pedronauck/docz/blob/main/core/docz-core/src/bundler/build.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_argv,node_docz_config,node_plugins,node_mdx toneBlue
class node_gatsby_theme,node_source_nodes,node_page_creation,node_remark,node_rehype,node_docgen toneAmber
class node_state,node_menus,node_components,node_props_hook,node_playground,node_props_view toneMint
class node_cli,node_dev_machine,node_dev_server,node_build,node_static_site toneRose
class node_author,node_gatsby,node_browser toneIndigo
```

## Components

### Authoring and configuration

- [Arguments and config](https://github.com/pedronauck/docz/blob/main/core/docz-core/src/config/argv.ts): `core/docz-core/src/config/argv.ts`
- [Docz config](https://github.com/pedronauck/docz/blob/main/core/docz-core/src/config/docz.ts): `core/docz-core/src/config/docz.ts`
- [Plugin system](https://github.com/pedronauck/docz/blob/main/core/docz-core/src/lib/Plugin.ts): `core/docz-core/src/lib/Plugin.ts`
- **MDX documents**

### Site generation

- [Gatsby theme integration](https://github.com/pedronauck/docz/blob/main/core/gatsby-theme-docz/gatsby-node.js): `core/gatsby-theme-docz/gatsby-node.js`
- [Document discovery](https://github.com/pedronauck/docz/blob/main/core/gatsby-theme-docz/lib/sourceNodes.js): `core/gatsby-theme-docz/lib/sourceNodes.js`
- [Page creation](https://github.com/pedronauck/docz/blob/main/core/gatsby-theme-docz/lib/createPagesStatefully.js): `core/gatsby-theme-docz/lib/createPagesStatefully.js`
- [Markdown transforms](https://github.com/pedronauck/docz/blob/main/core/remark-docz/src/index.ts): `core/remark-docz/src/index.ts`
- [HTML transforms](https://github.com/pedronauck/docz/blob/main/core/rehype-docz/src/index.ts): `core/rehype-docz/src/index.ts`
- [Component prop parsing](https://github.com/pedronauck/docz/blob/main/core/docz-core/src/utils/docgen/externalProptypesHandler.ts): `core/docz-core/src/utils/docgen/externalProptypesHandler.ts`

### Documentation runtime

- [Documentation state](https://github.com/pedronauck/docz/blob/main/core/docz/src/state.tsx): `core/docz/src/state.tsx`
- [Menu construction](https://github.com/pedronauck/docz/blob/main/core/docz/src/hooks/useMenus.ts): `core/docz/src/hooks/useMenus.ts`
- [Theme components](https://github.com/pedronauck/docz/blob/main/core/docz/src/hooks/useComponents.tsx): `core/docz/src/hooks/useComponents.tsx`
- [Props lookup](https://github.com/pedronauck/docz/blob/main/core/docz/src/hooks/useComponentProps.ts): `core/docz/src/hooks/useComponentProps.ts`
- [Live playground](https://github.com/pedronauck/docz/blob/main/core/gatsby-theme-docz/src/components/Playground/index.js): `core/gatsby-theme-docz/src/components/Playground/index.js`
- [Props display](https://github.com/pedronauck/docz/blob/main/core/gatsby-theme-docz/src/components/Props/index.js): `core/gatsby-theme-docz/src/components/Props/index.js`

### Development and output

- [Docz CLI](https://github.com/pedronauck/docz/blob/main/core/docz-core/src/cli.ts): `core/docz-core/src/cli.ts`
- [Development machine](https://github.com/pedronauck/docz/blob/main/core/docz-core/src/bundler/machine/index.ts): `core/docz-core/src/bundler/machine/index.ts`
- [Development server](https://github.com/pedronauck/docz/blob/main/core/docz-core/src/bundler/server.ts): `core/docz-core/src/bundler/server.ts`
- [Production build](https://github.com/pedronauck/docz/blob/main/core/docz-core/src/bundler/build.ts): `core/docz-core/src/bundler/build.ts`
- **Static site output**

### Other components

- **Documentation author**
- **Gatsby runtime**
- **Site visitor**

## Connections

- Documentation author → MDX documents: writes MDX (evidence: `README.md`)
- Documentation author → Docz CLI: runs commands (evidence: `README.md`)
- Docz CLI → Arguments and config: sets options
- Arguments and config → Docz config: loads defaults (evidence: `core/docz-core/src/config/argv.ts`)
- Docz config → Plugin system: configures plugins (evidence: `core/docz-core/src/config/docz.ts`)
- Gatsby theme integration → Document discovery: registers (evidence: `core/gatsby-theme-docz/gatsby-node.js`)
- Gatsby theme integration → Page creation: registers (evidence: `core/gatsby-theme-docz/gatsby-node.js`)
- Document discovery → Gatsby runtime: creates content nodes
- Page creation → Gatsby runtime: creates pages
- Gatsby runtime → Markdown transforms: transforms Markdown (evidence: `README.md`)
- Gatsby runtime → HTML transforms: transforms markup (evidence: `README.md`)
- Gatsby runtime → Component prop parsing: extracts component props (evidence: `README.md`)
- Gatsby runtime → Documentation state: provides documentation data (evidence: `README.md`)
- Documentation state → Menu construction: supplies entries (evidence: `core/docz/src/hooks/useMenus.ts`)
- Documentation state → Props lookup: supplies props (evidence: `core/docz/src/hooks/useComponentProps.ts`)
- Props lookup → Theme components: uses components (evidence: `core/docz/src/hooks/useComponentProps.ts`)
- Live playground → Theme components: renders themed components (evidence: `core/gatsby-theme-docz/src/components/Playground/index.js`)
- Props display → Documentation state: queries props
- Docz CLI → Development server: starts development
- Development server → Development machine: interprets machine (evidence: `core/docz-core/src/bundler/server.ts`)
- Docz CLI → Production build: builds site (evidence: `README.md`)
- Production build → Static site output: generates assets (evidence: `README.md`)
- Static site output → Site visitor: serves documentation (evidence: `README.md`)
- Gatsby runtime → Live playground: renders theme (evidence: `README.md`)
- Gatsby runtime → Props display: renders theme (evidence: `README.md`)
