# klic-awesome-code/ai-website-cloner-template architecture

> Architecture diagram of the GitHub repository klic-awesome-code/ai-website-cloner-template, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/klic-awesome-code/ai-website-cloner-template
- Repository: https://github.com/klic-awesome-code/ai-website-cloner-template

## Overview

1. **What this repository is**
   - This is not a backend service; it is a **Next.js 16 template** for rebuilding a target website as a clone.
   - The runtime app is a mostly empty front-end shell, while the real “system” includes the **Claude Code skill** and the generated research/assets that drive the rebuild.

2. **Primary execution flow**
   - The top-level workflow starts outside the app code: a user runs **`/clone-website <target-url>`** in Claude Code with **Chrome MCP** enabled.
   - Claude performs reconnaissance, extracts assets/tokens, writes component specs, builds sections in parallel worktrees, then merges and QA-checks the result against the target.

3. **App shell boundary**
   - The actual web app lives under **`src/app`** and uses the **Next.js App Router**.
   - The only visible route structure in the tree is the root page and global layout/styles, so the template is centered on a single cloneable landing-page surface rather than a full multi-service application.

4. **Presentation layer**
   - `src/app/layout.tsx`, `src/app/page.tsx`, and `src/app/globals.css` define the root document structure, homepage composition, and global styling.
   - This layer is where the reconstructed UI ultimately renders after the AI-assisted build process.

5. **Reusable UI primitives**
   - `src/components/ui/` contains shadcn/ui-style primitives, with `button.tsx` visible in the tree.
   - These are the lowest-level reusable building blocks for the cloned UI, intended to be composed into page sections rather than acting as a separate subsystem.

6. **Shared utility layer**
   - `src/lib/utils.ts` provides shared helpers, likely the `cn()`-style class composition utility used across components.
   - This is a small but important boundary: it keeps styling/composition concerns centralized instead of duplicated in each section.

7. **Type and hook scaffolding**
   - `src/types/` and `src/hooks/` exist as extension points, but the tree shows no substantive custom implementations yet.
   - Architecturally, these are placeholders for project-specific typing and interactive behavior if the clone requires them.

8. **Generated research and design artifacts**
   - `docs/research/` is a core part of the workflow, especially the component specs generated during reverse engineering.
   - The readme describes these specs as containing exact computed styles, states, behavior, responsive values, and content, which makes this repo partly a **spec-driven build system** rather than a normal hand-authored app.

9. **Reference and inspection assets**
   - `docs/design-references/` stores screenshots/comparison material used to verify fidelity.
   - The cloning process uses these visual references as the QA boundary between the original site and the rebuilt UI.

10. **Static asset boundary**
   - `public/images/`, `public/videos/`, and `public/seo/` are the landing zone for downloaded source assets and metadata from the target site.
   - These folders are part of the clone pipeline’s output: images, video captures, favicons, and OG assets are brought into the template so the rebuilt page can match the source without relying on the original host.

11. **Configuration and orchestration**
   - `TARGET.md` is the per-run configuration surface for scope, fidelity, and page selection.
   - `.claude/skills/clone-website/SKILL.md`, along with `AGENTS.md` and `CLAUDE.md`, define the AI-agent operating rules and workflow conventions that orchestrate the build.

12. **Tooling/runtime boundaries**
   - The repository is built around **TypeScript**, **Tailwind CSS v4**, **shadcn/ui**, and **Lucide React**, all running in a standard Node/Next.js toolchain.
   - `next.config.ts`, `eslint.config.mjs`, `postcss.config.mjs`, and `tsconfig.json` support the build/lint/typecheck pipeline, but they do not introduce a separate service layer.

13. **What is intentionally absent**
   - There are no visible API routes, database layers, auth systems, or background job services in the tree.
   - That absence is important architecturally: the repo is a **frontend-first cloning template** whose complexity comes from the AI-driven reconstruction workflow, not from application backend logic.

14. **How to draw the architecture**
   - A useful diagram would show three zones: **Claude Code / Chrome MCP orchestration**, **research + generated assets in docs/public**, and the **Next.js UI runtime in src/**.
   - Data flows from the target website into the research/spec/asset folders, then into the React/Tailwind component tree, and finally into the rendered clone in the browser.

Main entry points: [`src/app/page.tsx`](https://github.com/klic-awesome-code/ai-website-cloner-template/blob/master/src/app/page.tsx) (Home page), [`.claude/skills/clone-website/SKILL.md`](https://github.com/klic-awesome-code/ai-website-cloner-template/blob/master/.claude/skills/clone-website/SKILL.md) (Clone skill), [`docs/research`](https://github.com/klic-awesome-code/ai-website-cloner-template/tree/master/docs/research) (Component specs), [`src/app/layout.tsx`](https://github.com/klic-awesome-code/ai-website-cloner-template/blob/master/src/app/layout.tsx) (Layout)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_orchestration["Orchestration"]
  node_target_site(("Target site<br/>external source"))
  node_chrome_mcp["Chrome MCP<br/>browser probe"]
  node_clone_skill["Clone skill<br/>agent workflow<br/>[SKILL.md]"]
  node_agent_rules["Agent rules<br/>workflow docs<br/>[AGENTS.md]"]
  node_claude_notes["Claude notes<br/>workflow docs<br/>[CLAUDE.md]"]
  node_target_config["Target config<br/>run config<br/>[TARGET.md]"]
end

subgraph group_artifacts["Research & Assets"]
  node_inspection_guide["Inspection guide<br/>research guide"]
  node_component_specs["Component specs<br/>design specs"]
  node_design_refs["Design refs<br/>visual references"]
  node_images_assets[("Images<br/>static assets")]
  node_video_assets[("Videos<br/>static assets")]
  node_seo_assets[("SEO assets<br/>static assets")]
end

subgraph group_runtime["Next.js App"]
  node_app_layout["Layout<br/>app shell<br/>[layout.tsx]"]
  node_app_page["Home page<br/>app shell<br/>[page.tsx]"]
  node_app_styles["Global styles<br/>css layer<br/>[globals.css]"]
  node_ui_button["Button<br/>ui primitive<br/>[button.tsx]"]
  node_utils_lib["Utils<br/>shared helper<br/>[utils.ts]"]
  node_hooks_stub["Hooks<br/>extension point"]
  node_types_stub["Types<br/>extension point"]
end

subgraph group_tooling["Toolchain"]
  node_next_config["Next config<br/>build config<br/>[next.config.ts]"]
  node_eslint_config["ESLint<br/>lint config<br/>[eslint.config.mjs]"]
  node_postcss_config["PostCSS<br/>css toolchain<br/>[postcss.config.mjs]"]
  node_tsconfig["TypeScript<br/>type config<br/>[tsconfig.json]"]
end

node_target_site -->|"inspect"| node_chrome_mcp
node_chrome_mcp -->|"capture"| node_inspection_guide
node_inspection_guide -->|"specify"| node_component_specs
node_target_site -->|"compare"| node_design_refs
node_target_site -->|"download"| node_images_assets
node_target_site -->|"capture"| node_video_assets
node_target_site -->|"mirror"| node_seo_assets
node_clone_skill -->|"governed by"| node_agent_rules
node_clone_skill -->|"guided by"| node_claude_notes
node_clone_skill -->|"scoped by"| node_target_config
node_clone_skill -->|"drives"| node_component_specs
node_component_specs -->|"inform"| node_app_page
node_design_refs -->|"verify"| node_app_page
node_images_assets -->|"feed"| node_app_page
node_video_assets -->|"feed"| node_app_page
node_seo_assets -->|"seed"| node_app_layout
node_app_layout -->|"wrap"| node_app_page
node_app_page -->|"uses"| node_app_styles
node_app_page -->|"composes"| node_ui_button
node_ui_button -->|"depends on"| node_utils_lib
node_hooks_stub -.->|"extends"| node_app_page
node_types_stub -.->|"types"| node_app_page
node_next_config -->|"configures"| node_app_layout
node_postcss_config -->|"processes"| node_app_styles
node_tsconfig -->|"checks"| node_app_page
node_eslint_config -->|"checks"| node_app_page

click node_clone_skill "https://github.com/klic-awesome-code/ai-website-cloner-template/blob/master/.claude/skills/clone-website/SKILL.md"
click node_agent_rules "https://github.com/klic-awesome-code/ai-website-cloner-template/blob/master/AGENTS.md"
click node_claude_notes "https://github.com/klic-awesome-code/ai-website-cloner-template/blob/master/CLAUDE.md"
click node_target_config "https://github.com/klic-awesome-code/ai-website-cloner-template/blob/master/TARGET.md"
click node_inspection_guide "https://github.com/klic-awesome-code/ai-website-cloner-template/blob/master/docs/research/INSPECTION_GUIDE.md"
click node_component_specs "https://github.com/klic-awesome-code/ai-website-cloner-template/tree/master/docs/research"
click node_design_refs "https://github.com/klic-awesome-code/ai-website-cloner-template/tree/master/docs/design-references"
click node_images_assets "https://github.com/klic-awesome-code/ai-website-cloner-template/tree/master/public/images"
click node_video_assets "https://github.com/klic-awesome-code/ai-website-cloner-template/tree/master/public/videos"
click node_seo_assets "https://github.com/klic-awesome-code/ai-website-cloner-template/tree/master/public/seo"
click node_app_layout "https://github.com/klic-awesome-code/ai-website-cloner-template/blob/master/src/app/layout.tsx"
click node_app_page "https://github.com/klic-awesome-code/ai-website-cloner-template/blob/master/src/app/page.tsx"
click node_app_styles "https://github.com/klic-awesome-code/ai-website-cloner-template/blob/master/src/app/globals.css"
click node_ui_button "https://github.com/klic-awesome-code/ai-website-cloner-template/blob/master/src/components/ui/button.tsx"
click node_utils_lib "https://github.com/klic-awesome-code/ai-website-cloner-template/blob/master/src/lib/utils.ts"
click node_hooks_stub "https://github.com/klic-awesome-code/ai-website-cloner-template/tree/master/src/hooks"
click node_types_stub "https://github.com/klic-awesome-code/ai-website-cloner-template/tree/master/src/types"
click node_next_config "https://github.com/klic-awesome-code/ai-website-cloner-template/blob/master/next.config.ts"
click node_eslint_config "https://github.com/klic-awesome-code/ai-website-cloner-template/blob/master/eslint.config.mjs"
click node_postcss_config "https://github.com/klic-awesome-code/ai-website-cloner-template/blob/master/postcss.config.mjs"
click node_tsconfig "https://github.com/klic-awesome-code/ai-website-cloner-template/blob/master/tsconfig.json"

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_target_site,node_chrome_mcp,node_clone_skill,node_agent_rules,node_claude_notes,node_target_config toneBlue
class node_inspection_guide,node_component_specs,node_design_refs,node_images_assets,node_video_assets,node_seo_assets toneAmber
class node_app_layout,node_app_page,node_app_styles,node_ui_button,node_utils_lib,node_hooks_stub,node_types_stub toneMint
class node_next_config,node_eslint_config,node_postcss_config,node_tsconfig toneRose
```

## Components

### Orchestration

Claude Code workflow and agent instructions that drive the cloning process.

- **Target site**: external source · The website being reverse engineered and cloned.
- **Chrome MCP**: browser probe · Browser automation and inspection channel used during reconnaissance.
- [Clone skill](https://github.com/klic-awesome-code/ai-website-cloner-template/blob/master/.claude/skills/clone-website/SKILL.md): agent workflow · Claude Code skill that coordinates the clone-website procedure. · `.claude/skills/clone-website/SKILL.md`
- [Agent rules](https://github.com/klic-awesome-code/ai-website-cloner-template/blob/master/AGENTS.md): workflow docs · Repository-wide operating instructions for the cloning process. · `AGENTS.md`
- [Claude notes](https://github.com/klic-awesome-code/ai-website-cloner-template/blob/master/CLAUDE.md): workflow docs · Claude-specific guidance and repository conventions. · `CLAUDE.md`
- [Target config](https://github.com/klic-awesome-code/ai-website-cloner-template/blob/master/TARGET.md): run config · Per-run scope and fidelity settings for a specific clone task. · `TARGET.md`

### Research & Assets

Generated specs, visual references, and downloaded static assets used to rebuild the site.

- [Inspection guide](https://github.com/klic-awesome-code/ai-website-cloner-template/blob/master/docs/research/INSPECTION_GUIDE.md): research guide · Guidance for extracting and recording target-page details. · `docs/research/INSPECTION_GUIDE.md`
- [Component specs](https://github.com/klic-awesome-code/ai-website-cloner-template/tree/master/docs/research): design specs · Generated specifications for styles, states, responsiveness, and content. · `docs/research`
- [Design refs](https://github.com/klic-awesome-code/ai-website-cloner-template/tree/master/docs/design-references): visual references · Screenshots and comparison material used for fidelity checks. · `docs/design-references`
- [Images](https://github.com/klic-awesome-code/ai-website-cloner-template/tree/master/public/images): static assets · Downloaded image assets for the reconstructed page. · `public/images`
- [Videos](https://github.com/klic-awesome-code/ai-website-cloner-template/tree/master/public/videos): static assets · Downloaded video assets and captures from the target site. · `public/videos`
- [SEO assets](https://github.com/klic-awesome-code/ai-website-cloner-template/tree/master/public/seo): static assets · Favicons, OG images, and related metadata assets. · `public/seo`

### Next.js App

The front-end template that renders the cloned experience.

- [Layout](https://github.com/klic-awesome-code/ai-website-cloner-template/blob/master/src/app/layout.tsx): app shell · Root document structure for the Next.js app router. · `src/app/layout.tsx`
- [Home page](https://github.com/klic-awesome-code/ai-website-cloner-template/blob/master/src/app/page.tsx): app shell · Primary landing surface where the clone is assembled. · `src/app/page.tsx`
- [Global styles](https://github.com/klic-awesome-code/ai-website-cloner-template/blob/master/src/app/globals.css): css layer · App-wide styling foundation for the cloned UI. · `src/app/globals.css`
- [Button](https://github.com/klic-awesome-code/ai-website-cloner-template/blob/master/src/components/ui/button.tsx): ui primitive · Reusable shadcn-style control used in composed sections. · `src/components/ui/button.tsx`
- [Utils](https://github.com/klic-awesome-code/ai-website-cloner-template/blob/master/src/lib/utils.ts): shared helper · Shared helper utilities for class composition and common logic. · `src/lib/utils.ts`
- [Hooks](https://github.com/klic-awesome-code/ai-website-cloner-template/tree/master/src/hooks): extension point · Placeholder for interactive behavior if the clone needs it. · `src/hooks`
- [Types](https://github.com/klic-awesome-code/ai-website-cloner-template/tree/master/src/types): extension point · Placeholder for project-specific TypeScript types. · `src/types`

### Toolchain

Build, lint, and type-check support for the template.

- [Next config](https://github.com/klic-awesome-code/ai-website-cloner-template/blob/master/next.config.ts): build config · Next.js build and runtime configuration. · `next.config.ts`
- [ESLint](https://github.com/klic-awesome-code/ai-website-cloner-template/blob/master/eslint.config.mjs): lint config · Linting rules for the template. · `eslint.config.mjs`
- [PostCSS](https://github.com/klic-awesome-code/ai-website-cloner-template/blob/master/postcss.config.mjs): css toolchain · PostCSS pipeline supporting Tailwind CSS v4. · `postcss.config.mjs`
- [TypeScript](https://github.com/klic-awesome-code/ai-website-cloner-template/blob/master/tsconfig.json): type config · TypeScript compiler configuration for the repo. · `tsconfig.json`

## Connections

- Target site → Chrome MCP: inspect · Claude uses the browser channel to interrogate the source site.
- Chrome MCP → Inspection guide: capture · Inspection findings are recorded through the research workflow.
- Inspection guide → Component specs: specify · Reverse engineering produces detailed section and component specs.
- Target site → Design refs: compare · Visual references are collected to verify fidelity against the target.
- Target site → Images: download · Source imagery is copied into the template asset tree.
- Target site → Videos: capture · Video or motion assets are gathered from the target site.
- Target site → SEO assets: mirror · Metadata and social preview assets are brought into the clone.
- Clone skill → Agent rules: governed by · The skill follows repository-wide operating rules.
- Clone skill → Claude notes: guided by · Claude-specific conventions shape execution.
- Clone skill → Target config: scoped by · Each run is constrained by the target configuration.
- Clone skill → Component specs: drives · The skill turns research into buildable specifications.
- Component specs → Home page: inform · Specs guide how the page sections are composed.
- Design refs → Home page: verify · Rendered output is compared with reference screenshots.
- Images → Home page: feed · Downloaded assets are consumed by the page build.
- Videos → Home page: feed · Motion assets are wired into the UI where needed.
- SEO assets → Layout: seed · SEO and metadata assets influence the root document.
- Layout → Home page: wrap · The root layout contains the page surface.
- Home page → Global styles: uses · Page rendering depends on the global style layer.
- Home page → Button: composes · Page sections reuse shared UI primitives.
- Button → Utils: depends on · Primitive components share class-composition utilities.
- Hooks → Home page: extends · Interactive behavior can be added into the page layer.
- Types → Home page: types · Project-specific types can support the page and components.
- Next config → Layout: configures · Next.js settings govern app runtime behavior.
- PostCSS → Global styles: processes · PostCSS transforms the styling pipeline.
- TypeScript → Home page: checks · TypeScript validates the app source.
- ESLint → Home page: checks · Linting applies to the application code.