# brenoepics/vitepress-carbon architecture

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

- Interactive diagram: https://gitdiagram.com/brenoepics/vitepress-carbon
- Repository: https://github.com/brenoepics/vitepress-carbon

## Overview

##### Project Type and Purpose
- This is an open-source, multi-package monorepo offering:
- A “theme” library for VitePress (Vue-based static site generator)
- A “cli” tool (`vpcar`) to scaffold new VitePress-Carbon projects using JSON templates
- A “demo” VitePress site showcasing the theme in action

##### High-Level File/Package Structure
- Root: configuration (pnpm workspace, linting, build rules), CI/CD (GitHub workflows), changelogs, metadata.
- packages/theme: TypeScript + Vue components + styles → bundled library published to npm.
- packages/cli: Node.js + TS command-line app → reads templates, writes file tree, installs dependencies.
- packages/demo: VitePress site → markdown, config, public assets → uses the theme package.
- packages/templates: JSON template definitions consumed by the CLI.

##### Main Components
A. Monorepo Workspace
- Orchestrates: package.json workspaces, pnpm link, versioning, CI pipelines (GitHub Actions), lint/build tools.
B. Theme Package
- Source: `src/theme/*` (Vue components, composables, styles)
- Build: TS → ES modules, CSS assets
- Output: npm registry
C. CLI Package (`vpcar`)
- Entrypoint: bin/vpcar.mjs
- Commands: init, index, shared utilities (fs, templates, engines)
- Template Source: packages/templates/*.json
- Output: new project skeleton + installs theme dependency
D. Demo Site
- VitePress config & markdown
- Uses theme (imported via package alias)
- Dev server (Vite) → browser preview
E. External Services
- npm registry (publish/resolve)
- GitHub (source repo, Actions, Pages hosting demo)
- Developer Machine (CLI invocation, local builds)

##### Relationships & Data Flows
1. Developer → runs `pnpm install` at root → workspace links all packages
2. Developer → invokes `vpcar init` → CLI reads JSON templates → writes files → runs `npm install` in target directory (pulls in theme from registry or local workspace)
3. Developer → opens demo → VitePress (uses theme package) → renders documentation site
4. CI/CD → GitHub Actions → installs monorepo, runs tests/lints, builds packages, publishes theme & cli to npm

##### Architectural Patterns & Principles
- Monorepo with pnpm workspaces for atomic versioning, local linking, and unified CI.
- Modular separation: CLI (application), Theme (UI library), Demo (consumer app).
- Template-driven scaffolding: declarative JSON templates abstract file generation.
- Component-based UI: Vue single-file components & composables in theme.

##### Technologies & Frameworks
- Node.js + TypeScript for CLI & theme
- Vue 3 + VitePress for demo and theme components
- pnpm workspaces for package management
- GitHub Actions for CI, CodeQL, dependency review
- ESLint, Prettier, changelog tools (.changeset)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Monorepo Workspace
    subgraph "Monorepo Workspace"
        direction TB
        RootPkg["package.json"]:::monorepo
        WorkspaceYaml["pnpm-workspace.yaml"]:::monorepo
        Lockfile["pnpm-lock.yaml"]:::monorepo
        Tsconfig["tsconfig.json"]:::monorepo
        ESLint["eslint.config.mjs"]:::monorepo
        Workflows[".github/workflows"]:::monorepo
        Changeset[".changeset"]:::monorepo
    end

    %% Theme Package
    subgraph "Theme Package (Vue 3 + TS library)" 
        direction TB
        ThemePkg["package.json"]:::library
        ThemeSrc["src/theme/**"]:::library
        ThemeScripts["scripts/**"]:::library
        ThemeChangelog["CHANGELOG.md"]:::library
    end

    %% CLI Package
    subgraph "CLI Package (vpcar)" 
        direction TB
        CliPkg["package.json"]:::devtools
        CliBin["bin/vpcar.mjs"]:::devtools
        CliIndex["src/index.ts"]:::devtools
        CliMain["src/main.ts"]:::devtools
        CliRun["src/run.ts"]:::devtools
        CliCommands["src/commands/**"]:::devtools
        CliUtils["src/utils/**"]:::devtools
        CliBuildConfig["build.config.ts"]:::devtools
    end

    %% Demo Site
    subgraph "Demo Site (VitePress)"
        direction TB
        DemoPkg["package.json"]:::devtools
        DemoConfig[".vitepress/config.mts"]:::devtools
        DemoThemeOverride[".vitepress/theme/**"]:::devtools
        DemoContent["src/**/*.md"]:::devtools
        DemoPublic["src/public/**"]:::devtools
    end

    %% Templates Package
    subgraph "Templates Package"
        direction TB
        JSJson["javascript.json"]:::template
        TSJson["typescript.json"]:::template
    end

    %% External Services
    subgraph "External Services"
        direction TB
        NpmRegistry[("npm Registry")]:::external
        GitHub[("GitHub")]:::external
        GitHubPages[("GitHub Pages")]:::external
        GitHubActions(("GitHub Actions")):::external
        DevMachine(("Developer Machine")):::client
        Browser(("Browser")):::client
    end

    %% New Project output
    NewProj["New Project Skeleton"]:::devtools

    %% Relationships
    DevMachine -->|"pnpm install"| RootPkg
    RootPkg --> WorkspaceYaml
    RootPkg --> Lockfile
    RootPkg --> Tsconfig
    RootPkg --> ESLint
    RootPkg --> Workflows
    RootPkg --> Changeset

    DevMachine -->|"runs vpcar init"| CliBin
    CliBin -->|"reads templates"| JSJson
    CliBin -->|"reads templates"| TSJson
    CliBin -->|"writes files"| NewProj
    NewProj -->|"installs theme"| ThemePkg

    DevMachine -->|"vitepress dev"| DemoConfig
    DemoConfig -->|"imports theme"| ThemePkg
    DemoConfig -->|"serves site"| Browser

    GitHubActions -->|"tests & builds"| ThemePkg
    GitHubActions -->|"tests & builds"| CliPkg
    GitHubActions -->|"tests & builds"| DemoPkg
    GitHubActions -->|"publishes"| NpmRegistry
    GitHubActions -->|"deploys demo"| GitHubPages

    ThemePkg -->|"published to"| NpmRegistry
    CliPkg -->|"published to"| NpmRegistry

    %% Workspace links packages
    RootPkg -->|"workspace link"| ThemePkg
    RootPkg -->|"workspace link"| CliPkg
    RootPkg -->|"workspace link"| DemoPkg
    RootPkg -->|"workspace link"| JSJson
    RootPkg -->|"workspace link"| TSJson

    %% Click Events
    click RootPkg "https://github.com/brenoepics/vitepress-carbon/blob/main/package.json"
    click WorkspaceYaml "https://github.com/brenoepics/vitepress-carbon/blob/main/pnpm-workspace.yaml"
    click Lockfile "https://github.com/brenoepics/vitepress-carbon/blob/main/pnpm-lock.yaml"
    click Tsconfig "https://github.com/brenoepics/vitepress-carbon/blob/main/tsconfig.json"
    click ESLint "https://github.com/brenoepics/vitepress-carbon/blob/main/eslint.config.mjs"
    click Workflows "https://github.com/brenoepics/vitepress-carbon/tree/main/.github/workflows"
    click Changeset "https://github.com/brenoepics/vitepress-carbon/blob/main/.changeset"
    click ThemePkg "https://github.com/brenoepics/vitepress-carbon/blob/main/packages/theme/package.json"
    click ThemeSrc "https://github.com/brenoepics/vitepress-carbon/tree/main/packages/theme/src/theme/"
    click ThemeScripts "https://github.com/brenoepics/vitepress-carbon/blob/main/packages/theme/scripts/copyTheme.js"
    click ThemeChangelog "https://github.com/brenoepics/vitepress-carbon/blob/main/packages/theme/CHANGELOG.md"
    click CliPkg "https://github.com/brenoepics/vitepress-carbon/blob/main/packages/cli/package.json"
    click CliBin "https://github.com/brenoepics/vitepress-carbon/blob/main/packages/cli/bin/vpcar.mjs"
    click CliIndex "https://github.com/brenoepics/vitepress-carbon/blob/main/packages/cli/src/index.ts"
    click CliMain "https://github.com/brenoepics/vitepress-carbon/blob/main/packages/cli/src/main.ts"
    click CliRun "https://github.com/brenoepics/vitepress-carbon/blob/main/packages/cli/src/run.ts"
    click CliCommands "https://github.com/brenoepics/vitepress-carbon/tree/main/packages/cli/src/commands/"
    click CliUtils "https://github.com/brenoepics/vitepress-carbon/tree/main/packages/cli/src/utils/"
    click CliBuildConfig "https://github.com/brenoepics/vitepress-carbon/blob/main/packages/cli/build.config.ts"
    click DemoPkg "https://github.com/brenoepics/vitepress-carbon/blob/main/packages/demo/package.json"
    click DemoConfig "https://github.com/brenoepics/vitepress-carbon/blob/main/packages/demo/.vitepress/config.mts"
    click DemoThemeOverride "https://github.com/brenoepics/vitepress-carbon/tree/main/packages/demo/.vitepress/theme/"
    click DemoContent "https://github.com/brenoepics/vitepress-carbon/tree/main/packages/demo/src/"
    click DemoPublic "https://github.com/brenoepics/vitepress-carbon/tree/main/packages/demo/src/public/"
    click JSJson "https://github.com/brenoepics/vitepress-carbon/blob/main/packages/templates/javascript.json"
    click TSJson "https://github.com/brenoepics/vitepress-carbon/blob/main/packages/templates/typescript.json"

    %% Styles
    classDef monorepo fill:#f0f8ff,stroke:#333,stroke-width:1px
    classDef devtools fill:#add8e6,stroke:#333,stroke-width:1px
    classDef library fill:#90ee90,stroke:#333,stroke-width:1px
    classDef external fill:#ffcc99,stroke:#333,stroke-width:1px
    classDef template fill:#98fb98,stroke:#333,stroke-width:1px
    classDef client fill:#add8e6,stroke:#333,stroke-width:1px
```
