# observedobserver/convertfast-ui architecture

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

- Interactive diagram: https://gitdiagram.com/observedobserver/convertfast-ui
- Repository: https://github.com/observedobserver/convertfast-ui

## Overview

1. **Overall shape**
   - This repo is a **monorepo for a landing-page scaffolding system**. It is centered on a CLI that generates pages/sections, a registry that describes available blocks, and two codebases that act as source material and previews for those blocks.

2. **Primary user-facing entry point: `packages/cli`**
   - `packages/cli` is the distributable tool invoked by commands like `init`, `page create`, `page add`, and `block add`.
   - Its command handlers live in `src/commands/` and are the main orchestration layer for generation and installation.
   - This package is where the repo’s public behavior is defined: choosing templates, copying files, resolving registry blocks, and installing dependencies.

3. **CLI orchestration flow**
   - The CLI’s utilities in `src/utils/` handle the concrete work:
     - configuration resolution,
     - file copying,
     - dependency installation,
     - registry lookup/integration,
     - template selection and segment mapping.
   - The CLI supports a **registry-aware flow**: for some operations it can try the ConvertFast registry first and fall back to local dependency installation if needed.

4. **Template source: `templates/next-template`**
   - This directory is a **Next.js app-router template** used to bootstrap new landing pages.
   - It includes app-level routes and layouts, a global stylesheet, Tailwind/PostCSS config, and reusable UI components.
   - Architecturally, this is the “copy-into-user-project” target for page generation, not a runtime service.

5. **Local preview / showcase app: `packages/segments`**
   - `packages/segments` is a **Vite + React preview application** for the available landing-page sections.
   - It contains a larger catalog of section implementations and supporting UI primitives, plus theme/dark-mode plumbing.
   - This package is useful as the visual and component reference for what the CLI can scaffold.

6. **Section organization inside the preview app**
   - `packages/segments/src/segments/` contains reusable marketing-page sections such as hero, FAQ, pricing, navbar, footer, stats, newsletter, and social proof.
   - `packages/segments/src/editorial/segments/` contains a second set of section variants geared toward an editorial-style template.
   - This separation suggests two design families: a default landing-page style and an editorial style.

7. **Shared UI and theming boundaries**
   - Both the preview app and the Next template include UI primitives under `components/ui/` and a theme provider/mode toggle.
   - Shared utility code exists for class-name composition and other small helpers.
   - These shared pieces form the low-level component boundary that all generated pages rely on.

8. **Registry subsystem: `packages/registry`**
   - `packages/registry` holds the **registry manifest** that defines available blocks for consumption by the CLI.
   - The manifest is stored as JSON, and there are scripts to **build** and **validate** the registry output.
   - Conceptually, this is the metadata layer that maps block names to the files/code the CLI should install.

9. **Source of truth and distribution boundary**
   - The repo separates:
     - **block definitions/metadata** in the registry,
     - **reference implementations** in `packages/segments`,
     - **scaffoldable project templates** in `templates/next-template`,
     - **end-user CLI behavior** in `packages/cli`.
   - That separation is important for the architecture diagram: the CLI does not own all UI code directly; it assembles projects from these sources.

10. **Static assets and public conversion marker**
   - Both the preview app and the template include `public/_convertfast`, which likely acts as a marker or shared asset namespace for generated projects.
   - `public/` at the repo root also exists, reinforcing that some assets are meant to be copied or served as-is rather than built dynamically.

11. **Documentation and release process**
   - `docs/` contains migration and registry release checklists, which indicates an active concern with **registry evolution and compatibility**.
   - GitHub Actions includes a build workflow for the CLI, so the CLI package is treated as the primary CI-validated artifact.

12. **How the system is intended to be used**
   - A user runs the CLI to initialize a project or add pages/blocks.
   - The CLI resolves the requested template/section, reads registry metadata when needed, copies the appropriate source files into the target project, and installs dependencies if required.
   - The generated output is a local landing page application, not a hosted backend service.

13. **Technologies that matter architecturally**
   - The repo is TypeScript-based and spans two frontend runtimes:
     - **Next.js** for the scaffolded template,
     - **Vite + React** for the preview/catalog app.
   - Tailwind CSS and shadcn-style UI composition are core to the generated output and the registry model.

14. **Good diagram boundaries**
   - Draw four main boxes: **CLI**, **Registry**, **Template**, and **Preview/Segments App**.
   - Show the CLI as the hub that consumes registry metadata and copies template/segment code into a user project.
   - Show the preview app and template as code sources/examples, not services.

Main entry points: [`packages/cli/src/utils`](https://github.com/observedobserver/convertfast-ui/tree/main/packages/cli/src/utils) (CLI utils), [`packages/segments/src/main.tsx`](https://github.com/observedobserver/convertfast-ui/blob/main/packages/segments/src/main.tsx) (Segments app), [`packages/cli/src/index.ts`](https://github.com/observedobserver/convertfast-ui/blob/main/packages/cli/src/index.ts) (CLI entry), [`templates/next-template/app/page.tsx`](https://github.com/observedobserver/convertfast-ui/blob/main/templates/next-template/app/page.tsx) (Template app)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_repo_ops["Repo ops"]
  node_root_package["Monorepo<br/>workspace<br/>[package.json]"]
  node_build_workflow["Build CI<br/>github-actions<br/>[build-cli.yml]"]
  node_docs_migration["Registry docs"]
  node_docs_release["Release checklist<br/>docs"]
end

subgraph group_cli["CLI"]
  node_cli_index(("CLI entry<br/>ts entrypoint<br/>[index.ts]"))
  node_cli_init["Init<br/>command<br/>[init.ts]"]
  node_cli_page["Page cmd<br/>command<br/>[page.ts]"]
  node_cli_block["Block cmd<br/>command<br/>[block.ts]"]
  node_cli_utils{{"CLI utils<br/>helpers"}}
end

subgraph group_registry["Registry"]
  node_registry_manifest[("Manifest<br/>json registry<br/>[blocks.json]")]
  node_registry_scripts["Registry scripts<br/>build/validate<br/>[build-registry.mjs]"]
end

subgraph group_segments["Preview app"]
  node_segments_app(("Segments app<br/>Vite preview<br/>[main.tsx]"))
  node_segments_catalog["Sections<br/>segment catalog"]
  node_segments_editorial["Editorial set<br/>segment variants"]
  node_segments_ui["UI primitives<br/>shared UI"]
  node_segments_public["Public assets"]
end

subgraph group_template["Next template"]
  node_template_app(("Template app<br/>Next.js app<br/>[page.tsx]"))
  node_template_layout["App shell<br/>layout/styles<br/>[layout.tsx]"]
  node_template_ui["UI primitives<br/>shared UI"]
  node_template_public["Public assets"]
end

node_root_package -->|"includes"| node_cli_index
node_root_package -->|"includes"| node_segments_app
node_root_package -->|"includes"| node_registry_manifest
node_root_package -->|"includes"| node_template_app
node_build_workflow -->|"builds"| node_cli_index
node_docs_migration -.->|"guides"| node_registry_manifest
node_docs_release -.->|"guides"| node_registry_scripts
node_cli_index -->|"dispatches"| node_cli_init
node_cli_index -->|"dispatches"| node_cli_page
node_cli_index -->|"dispatches"| node_cli_block
node_cli_init -->|"uses"| node_cli_utils
node_cli_page -->|"uses"| node_cli_utils
node_cli_block -->|"uses"| node_cli_utils
node_cli_utils -->|"reads"| node_registry_manifest
node_cli_utils -->|"copies from"| node_segments_catalog
node_cli_utils -->|"copies from"| node_segments_editorial
node_cli_utils -->|"copies from"| node_template_app
node_cli_utils -->|"copies from"| node_template_ui
node_cli_utils -->|"copies from"| node_template_public
node_segments_app -->|"hosts"| node_segments_catalog
node_segments_app -->|"hosts"| node_segments_editorial
node_segments_app -->|"uses"| node_segments_ui
node_segments_app -->|"serves"| node_segments_public
node_template_app -->|"uses"| node_template_layout
node_template_app -->|"uses"| node_template_ui
node_template_app -->|"serves"| node_template_public
node_registry_scripts -->|"builds"| node_registry_manifest
node_cli_utils -.->|"targets"| node_template_layout

click node_root_package "https://github.com/observedobserver/convertfast-ui/blob/main/package.json"
click node_build_workflow "https://github.com/observedobserver/convertfast-ui/blob/main/.github/workflows/build-cli.yml"
click node_docs_migration "https://github.com/observedobserver/convertfast-ui/blob/main/docs/shadcn-registry-migration.md"
click node_docs_release "https://github.com/observedobserver/convertfast-ui/blob/main/docs/shadcn-registry-release-checklist.md"
click node_cli_index "https://github.com/observedobserver/convertfast-ui/blob/main/packages/cli/src/index.ts"
click node_cli_init "https://github.com/observedobserver/convertfast-ui/blob/main/packages/cli/src/commands/init.ts"
click node_cli_page "https://github.com/observedobserver/convertfast-ui/blob/main/packages/cli/src/commands/page.ts"
click node_cli_block "https://github.com/observedobserver/convertfast-ui/blob/main/packages/cli/src/commands/block.ts"
click node_cli_utils "https://github.com/observedobserver/convertfast-ui/tree/main/packages/cli/src/utils"
click node_registry_manifest "https://github.com/observedobserver/convertfast-ui/blob/main/packages/registry/manifest/blocks.json"
click node_registry_scripts "https://github.com/observedobserver/convertfast-ui/blob/main/packages/registry/scripts/build-registry.mjs"
click node_segments_app "https://github.com/observedobserver/convertfast-ui/blob/main/packages/segments/src/main.tsx"
click node_segments_catalog "https://github.com/observedobserver/convertfast-ui/tree/main/packages/segments/src/segments"
click node_segments_editorial "https://github.com/observedobserver/convertfast-ui/tree/main/packages/segments/src/editorial/segments"
click node_segments_ui "https://github.com/observedobserver/convertfast-ui/tree/main/packages/segments/src/components/ui"
click node_segments_public "https://github.com/observedobserver/convertfast-ui/tree/main/packages/segments/public/_convertfast"
click node_template_app "https://github.com/observedobserver/convertfast-ui/blob/main/templates/next-template/app/page.tsx"
click node_template_layout "https://github.com/observedobserver/convertfast-ui/blob/main/templates/next-template/app/layout.tsx"
click node_template_ui "https://github.com/observedobserver/convertfast-ui/tree/main/templates/next-template/components/ui"
click node_template_public "https://github.com/observedobserver/convertfast-ui/tree/main/templates/next-template/public/_convertfast"

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_root_package,node_build_workflow,node_docs_migration,node_docs_release toneBlue
class node_cli_index,node_cli_init,node_cli_page,node_cli_block,node_cli_utils toneAmber
class node_registry_manifest,node_registry_scripts toneMint
class node_segments_app,node_segments_catalog,node_segments_editorial,node_segments_ui,node_segments_public toneRose
class node_template_app,node_template_layout,node_template_ui,node_template_public toneIndigo
```

## Components

### Repo ops

Documentation and CI around the main packages

- [Monorepo](https://github.com/observedobserver/convertfast-ui/blob/main/package.json): workspace · Top-level TypeScript monorepo that ties the CLI, registry, preview app, and template together · `package.json`
- [Build CI](https://github.com/observedobserver/convertfast-ui/blob/main/.github/workflows/build-cli.yml): github-actions · Workflow that builds and validates the CLI package · `.github/workflows/build-cli.yml`
- [Registry docs](https://github.com/observedobserver/convertfast-ui/blob/main/docs/shadcn-registry-migration.md): docs · Migration and release checklists for registry evolution · `docs/shadcn-registry-migration.md`
- [Release checklist](https://github.com/observedobserver/convertfast-ui/blob/main/docs/shadcn-registry-release-checklist.md): docs · Operational checklist for registry releases · `docs/shadcn-registry-release-checklist.md`

### CLI

User-facing generator and orchestration layer

- [CLI entry](https://github.com/observedobserver/convertfast-ui/blob/main/packages/cli/src/index.ts): ts entrypoint · Distributable command-line entrypoint · `packages/cli/src/index.ts`
- [Init](https://github.com/observedobserver/convertfast-ui/blob/main/packages/cli/src/commands/init.ts): command · Creates a new project from the available scaffold sources · `packages/cli/src/commands/init.ts`
- [Page cmd](https://github.com/observedobserver/convertfast-ui/blob/main/packages/cli/src/commands/page.ts): command · Handles page creation and page-level generation flows · `packages/cli/src/commands/page.ts`
- [Block cmd](https://github.com/observedobserver/convertfast-ui/blob/main/packages/cli/src/commands/block.ts): command · Adds blocks into an existing project · `packages/cli/src/commands/block.ts`
- [CLI utils](https://github.com/observedobserver/convertfast-ui/tree/main/packages/cli/src/utils): helpers · Configuration, copy, install, registry, and template resolution utilities · `packages/cli/src/utils`

### Registry

Block metadata and registry build/validation

- [Manifest](https://github.com/observedobserver/convertfast-ui/blob/main/packages/registry/manifest/blocks.json): json registry · Registry catalog of available blocks and their file mappings · `packages/registry/manifest/blocks.json`
- [Registry scripts](https://github.com/observedobserver/convertfast-ui/blob/main/packages/registry/scripts/build-registry.mjs): build/validate · Scripts that build and validate the registry output · `packages/registry/scripts/build-registry.mjs`

### Preview app

Vite + React catalog and visual source for sections

- [Segments app](https://github.com/observedobserver/convertfast-ui/blob/main/packages/segments/src/main.tsx): Vite preview · React preview and catalog app for landing-page sections · `packages/segments/src/main.tsx`
- [Sections](https://github.com/observedobserver/convertfast-ui/tree/main/packages/segments/src/segments): segment catalog · Default marketing sections used as reference implementations · `packages/segments/src/segments`
- [Editorial set](https://github.com/observedobserver/convertfast-ui/tree/main/packages/segments/src/editorial/segments): segment variants · Editorial-style section variants · `packages/segments/src/editorial/segments`
- [UI primitives](https://github.com/observedobserver/convertfast-ui/tree/main/packages/segments/src/components/ui): shared UI · Reusable component primitives and theme plumbing for the preview app · `packages/segments/src/components/ui`
- [Public assets](https://github.com/observedobserver/convertfast-ui/tree/main/packages/segments/public/_convertfast): assets · Static assets and conversion marker for the preview app · `packages/segments/public/_convertfast`

### Next template

Scaffolded project template copied into user projects

- [Template app](https://github.com/observedobserver/convertfast-ui/blob/main/templates/next-template/app/page.tsx): Next.js app · App-router scaffold copied into user projects · `templates/next-template/app/page.tsx`
- [App shell](https://github.com/observedobserver/convertfast-ui/blob/main/templates/next-template/app/layout.tsx): layout/styles · Next app layout and global styling boundary · `templates/next-template/app/layout.tsx`
- [UI primitives](https://github.com/observedobserver/convertfast-ui/tree/main/templates/next-template/components/ui): shared UI · Reusable component primitives and theme plumbing for the template · `templates/next-template/components/ui`
- [Public assets](https://github.com/observedobserver/convertfast-ui/tree/main/templates/next-template/public/_convertfast): assets · Static assets and conversion marker for scaffolded projects · `templates/next-template/public/_convertfast`

## Connections

- Monorepo → CLI entry: includes · Workspace publishes the CLI package
- Monorepo → Segments app: includes · Workspace contains the preview application
- Monorepo → Manifest: includes · Workspace contains the registry package
- Monorepo → Template app: includes · Workspace contains the scaffold template
- Build CI → CLI entry: builds · CI focuses on the CLI artifact
- Registry docs → Manifest: guides · Documents registry changes and migration concerns
- Release checklist → Registry scripts: guides · Documents registry release process and validation
- CLI entry → Init: dispatches · CLI entrypoint routes into command handlers
- CLI entry → Page cmd: dispatches · CLI entrypoint routes into command handlers
- CLI entry → Block cmd: dispatches · CLI entrypoint routes into command handlers
- Init → CLI utils: uses · Init orchestration relies on shared utilities
- Page cmd → CLI utils: uses · Page generation relies on shared utilities
- Block cmd → CLI utils: uses · Block installation relies on shared utilities
- CLI utils → Manifest: reads · Resolves block metadata from the registry
- CLI utils → Sections: copies from · Can source segment implementations from the preview catalog
- CLI utils → Editorial set: copies from · Can source editorial variants when needed
- CLI utils → Template app: copies from · Uses the Next template as scaffold source
- CLI utils → UI primitives: copies from · Reuses shared UI primitives for generated output
- CLI utils → Public assets: copies from · Carries static conversion assets into generated projects
- Segments app → Sections: hosts · Preview app renders the default section catalog
- Segments app → Editorial set: hosts · Preview app renders editorial variants
- Segments app → UI primitives: uses · Catalog and previews depend on shared UI and theme boundaries
- Segments app → Public assets: serves · Preview app includes static conversion assets
- Template app → App shell: uses · App pages depend on layout and globals
- Template app → UI primitives: uses · Scaffolded pages depend on shared UI primitives
- Template app → Public assets: serves · Template includes static assets for generated projects
- Registry scripts → Manifest: builds · Scripts generate and validate the registry manifest
- CLI utils → App shell: targets · Generation flow ultimately writes into the scaffolded app structure
