How observedobserver/convertfast-ui works
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: utils CLI utils · main.tsx Segments app · index.ts CLI entry · page.tsx Template app
Components 20
Repo ops
Documentation and CI around the main packages
- Monorepo · Top-level TypeScript monorepo that ties the CLI, registry, preview app, and template together
package.json - Build CI · Workflow that builds and validates the CLI package
.github/workflows/build-cli.yml - Registry docs · Migration and release checklists for registry evolution
docs/shadcn-registry-migration.md - Release checklist · Operational checklist for registry releases
docs/shadcn-registry-release-checklist.md
CLI
User-facing generator and orchestration layer
- CLI entry · Distributable command-line entrypoint
packages/cli/src/index.ts - Init · Creates a new project from the available scaffold sources
packages/cli/src/commands/init.ts - Page cmd · Handles page creation and page-level generation flows
packages/cli/src/commands/page.ts - Block cmd · Adds blocks into an existing project
packages/cli/src/commands/block.ts - CLI utils · Configuration, copy, install, registry, and template resolution utilities
packages/cli/src/utils
Registry
Block metadata and registry build/validation
- Manifest · Registry catalog of available blocks and their file mappings
packages/registry/manifest/blocks.json - Registry scripts · 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 · React preview and catalog app for landing-page sections
packages/segments/src/main.tsx - Sections · Default marketing sections used as reference implementations
packages/segments/src/segments - Editorial set · Editorial-style section variants
packages/segments/src/editorial/segments - UI primitives · Reusable component primitives and theme plumbing for the preview app
packages/segments/src/components/ui - Public 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 · App-router scaffold copied into user projects
templates/next-template/app/page.tsx - App shell · Next app layout and global styling boundary
templates/next-template/app/layout.tsx - UI primitives · Reusable component primitives and theme plumbing for the template
templates/next-template/components/ui - Public assets · Static assets and conversion marker for scaffolded projects
templates/next-template/public/_convertfast
Connections 28
- 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