# clidey/dory architecture

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

- Interactive diagram: https://gitdiagram.com/clidey/dory
- Repository: https://github.com/clidey/dory

## Overview

##### Project Type and Purpose
- **Type**: An open-source, full-frontend/static-site generator tool.
- **Purpose**: Ingest `.mdx` content + a single `dory.json` config → render static HTML/CSS/JS using Preact + Vite → serve via dev server or output to `dist` for deployment (Docker/Nginx/any static host).

##### File Structure
- **Top-Level Directories**
- `src/` – Core application code: Preact components, MDX plugins, UI layout, utilities, theme.
- `docs/` – Documentation source (`.mdx` pages, OpenAPI spec, features, introduction).
- `assets/` – Logo and static assets.
- `k8s/` – Dockerfiles + Nginx config for containerized deployment.
- **Config & Scripts**
- `package.json` & `pnpm-lock.yaml` – dependency management & scripts (`dev`, `build`).
- `vite.config.ts` – build & dev server configuration.
- `tsconfig*.json` – TypeScript compiler settings.
- **CI/CD & Governance**
- `.github/workflows/claude.yml` – GitHub Actions pipeline.
- `.github/ISSUE_TEMPLATE` – issue templates.
- `CONTRIBUTING.md`, `CODE_OF_CONDUCT.md`, `SECURITY.md` – project governance.

##### README for Additional Insights
- **Features**: Hot reload, static build, MDX support, built-in UI components, OpenAPI inference.
- **Deployment targets**: Netlify/Vercel/S3/GitHub Pages or Docker+Nginx in K8s.

##### Main Components & Their Interactions
a. **Content Layer**
- `.mdx` files in `docs/` + `openapi.json` + `dory.json` config
→ fed into
b. **Processing Layer**
- **MDX Parser & Plugins** (`src/plugins/*`, `src/mdx/*`)
- **Component Library** (`src/components/*`, `src/ui/*`)
- **Build Orchestrator** (Vite – `vite.config.ts`)
- **Hot-Reload Dev Server** (`pnpm run dev`)
→ outputs
c. **Output Layer**
- Static assets (`dist/`): HTML, CSS (Tailwind), JS (Preact bundles), images
→ served by
d. **Delivery Layer**
- Local Dev Server (Vite)
- Production Host (Nginx in Docker – `k8s/Dockerfile`, `k8s/dev.Dockerfile`, `k8s/config/nginx-default.conf`)
e. **CI/CD & Governance**
- GitHub Actions (build/test)
- Dependabot for dependency updates

##### Architectural Patterns & Design Principles
- **Plugin Architecture**: MDX support, sanitizer, API playground injection.
- **Component-Driven**: Reusable Preact components for layout/navigation/UX.
- **Config-First**: Single `dory.json` to drive site structure.
- **Static Site Generation**: No SSR, pure client build + static export.
- **Theming**: Tailwind + SCSS overrides.

- **Container boundaries** for each layer.
- **Component names** exactly as they appear in the repo (e.g., `src/mdx`, `src/components`).
- **External actors**: Developer, CI system, End-User.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Content Layer
    subgraph "Content Layer"
        direction TB
        Docs["docs/ (MDX documents)"]:::content
        Config["docs/dory.json"]:::content
        OpenAPI["docs/api-reference/openapi.json"]:::content
    end

    %% Processing Layer
    subgraph "Processing Layer"
        direction TB
        MDXPlugins["src/mdx/ (MDX Components & Plugins)"]:::processing
        Sanitize["src/plugins/sanitize.ts"]:::processing
        Components["src/components/ (Preact Component Library)"]:::processing
        UILayout["src/ui/ (UI Layout & Helpers)"]:::processing
        Utils["src/utils/ (Utilities & Hooks)"]:::processing
        Theming["Theming & Styles\n(src/app.css, src/index.css, src/theme.scss)"]:::processing
        Entry["Entry Points\n(src/main.tsx, src/app.tsx, index.html)"]:::processing
        Build["Vite & Scripts\n(vite.config.ts, package.json, pnpm-lock.yaml)"]:::processing
    end

    %% Output Layer
    subgraph "Output Layer"
        direction TB
        Static["dist/ (HTML, CSS, JS)"]:::output
    end

    %% Delivery Layer
    subgraph "Delivery Layer"
        direction TB
        DevServer["Vite Dev Server\n(pnpm run dev)"]:::delivery
        Nginx["Nginx in Docker\n(k8s/Dockerfile,\n k8s/dev.Dockerfile,\n k8s/config/nginx-default.conf)"]:::delivery
    end

    %% CI/CD
    subgraph "CI/CD & Governance"
        direction TB
        CICD["GitHub Actions\n(.github/workflows/claude.yml)"]:::ci
        Dependabot[".github/dependabot.yml"]:::ci
        Governance["Governance\n(.github/ISSUE_TEMPLATE/, CONTRIBUTING.md,\n CODE_OF_CONDUCT.md, SECURITY.md)"]:::governance
    end

    %% Data Flow
    Docs -->|reads| MDXPlugins
    Config -->|reads| MDXPlugins
    OpenAPI -->|reads| MDXPlugins
    MDXPlugins -->|provides components| Components
    Components -->|feeds| Build
    UILayout -->|feeds| Build
    Utils -->|feeds| Build
    Theming -->|applies| Build
    Entry -->|bootstraps| Build
    Build -->|outputs| Static
    Static -->|serves| DevServer
    Static -->|serves| Nginx
    CICD -->|triggers build| Build
    CICD -->|builds Docker| Nginx
    Dependabot -->|updates deps| Build

    %% Click Events
    click Docs "https://github.com/clidey/dory/tree/main/docs/"
    click Config "https://github.com/clidey/dory/blob/main/docs/dory.json"
    click OpenAPI "https://github.com/clidey/dory/blob/main/docs/api-reference/openapi.json"
    click MDXPlugins "https://github.com/clidey/dory/tree/main/src/mdx/"
    click Sanitize "https://github.com/clidey/dory/blob/main/src/plugins/sanitize.ts"
    click Components "https://github.com/clidey/dory/tree/main/src/components/"
    click UILayout "https://github.com/clidey/dory/tree/main/src/ui/"
    click Utils "https://github.com/clidey/dory/tree/main/src/utils/"
    click Build "https://github.com/clidey/dory/blob/main/vite.config.ts"
    click Build "https://github.com/clidey/dory/blob/main/package.json"
    click Build "https://github.com/clidey/dory/blob/main/pnpm-lock.yaml"
    click Theming "https://github.com/clidey/dory/blob/main/src/theme.scss"
    click Entry "https://github.com/clidey/dory/blob/main/src/main.tsx"
    click Entry "https://github.com/clidey/dory/blob/main/src/app.tsx"
    click Nginx "https://github.com/clidey/dory/tree/main/k8s/Dockerfile"
    click Nginx "https://github.com/clidey/dory/blob/main/k8s/dev.Dockerfile"
    click Nginx "https://github.com/clidey/dory/blob/main/k8s/config/nginx-default.conf"
    click CICD "https://github.com/clidey/dory/blob/main/.github/workflows/claude.yml"
    click Dependabot "https://github.com/clidey/dory/blob/main/.github/dependabot.yml"
    click Governance "https://github.com/clidey/dory/tree/main/.github/ISSUE_TEMPLATE/"
    click Governance "https://github.com/clidey/dory/blob/main/CONTRIBUTING.md"
    click Governance "https://github.com/clidey/dory/blob/main/CODE_OF_CONDUCT.md"
    click Governance "https://github.com/clidey/dory/blob/main/SECURITY.md"

    %% Styles
    classDef content fill:#dafbe1,stroke:#2c7a3c,color:#2c7a3c;
    classDef processing fill:#d0e7fd,stroke:#1d4f91,color:#1d4f91;
    classDef output fill:#ffe5b4,stroke:#cc8400,color:#cc8400;
    classDef delivery fill:#e7d0fd,stroke:#5a1d91,color:#5a1d91;
    classDef ci fill:#e0e0e0,stroke:#757575,color:#333333;
    classDef governance fill:#f5f5f5,stroke:#a0a0a0,color:#555555;
```
