# ratna-babu/ai-website-builder architecture

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

- Interactive diagram: https://gitdiagram.com/ratna-babu/ai-website-builder
- Repository: https://github.com/ratna-babu/ai-website-builder

## Overview

1. **Overall shape**
   - This is a **Next.js App Router** application for an AI website builder.
   - The architecture splits cleanly into:
     - a **UI layer** in `app/` and `components/`
     - **server API routes** in `app/api/`
     - a **real-time persistence layer** in `convex/`
     - shared **prompt/model configuration** in `data/` and `configs/`

2. **Primary user surfaces**
   - `app/page.js` is the public landing page, backed by components like `Hero` and `Header`.
   - `app/(main)/workspace/[id]/page.jsx` is the main product workspace, keyed by a workspace ID.
   - The workspace page is the central “builder” surface where chat, generated code, and preview likely coexist.

3. **Workspace as the core domain**
   - The repository is organized around a **workspace entity** rather than a generic document.
   - `convex/schema.js` and `convex/workspace.js` define and operate on the persistent workspace data.
   - The dynamic route `[id]` indicates the frontend loads and updates a specific workspace record through Convex.

4. **AI interaction boundary**
   - All AI-facing logic is isolated behind Next.js API routes:
     - `app/api/ai-chat/route.jsx`
     - `app/api/enhance-prompt/route.jsx`
     - `app/api/gen-ai-code/route.jsx`
   - This boundary keeps Gemini-specific request/response handling out of the React component tree.
   - The README and naming strongly suggest these routes call **Gemini Flash 2.0** for chat, prompt refinement, and code generation.

5. **Frontend composition**
   - `components/custom/ChatView.jsx` and `components/custom/CodeView.jsx` are the two main product views inside the builder.
   - `components/custom/Header.jsx` and `components/custom/Hero.jsx` serve the marketing/landing surface.
   - `components/ui/button.jsx` and `components.json` indicate a reusable UI component system layered on top of Tailwind.

6. **Client state and cross-component messaging**
   - `context/MessagesContext.js` is the main client-side state container for chat or generation messages.
   - `app/provider.jsx` and `app/ConvexClientProvider.jsx` are top-level wrappers that likely initialize shared providers for the app.
   - This suggests chat state is maintained in React context while durable workspace state lives in Convex.

7. **Convex as the persistence and realtime layer**
   - Convex is the backend database/function boundary, not just storage.
   - `convex/_generated/*` shows generated client/server bindings are used by the app.
   - `convex/workspace.js` likely exposes CRUD or streaming-style operations for workspace data, and `convex/schema.js` defines the shape of persisted records.
   - The README’s emphasis on “real-time updates” points to Convex driving live workspace synchronization.

8. **Prompt and model configuration**
   - `configs/AiModel.jsx` centralizes model selection or AI provider settings.
   - `data/Prompt.jsx` and `data/Lookup.jsx` likely contain prompt templates, prompt enrichment rules, or mapping logic used by the AI routes.
   - This separates “what to ask the model” from the route handlers that send the request.

9. **Rendering and styling boundary**
   - The app uses **Tailwind CSS** for presentation, with `app/globals.css`, `tailwind.config.mjs`, and `postcss.config.mjs` as the styling foundation.
   - `app/layout.js` is the root shell that applies global providers and styling.
   - `lib/utils.js` is the shared utility boundary for small cross-cutting helpers, likely used by UI components.

10. **End-to-end data flow**
   - A user enters a prompt in the workspace UI.
   - The prompt is stored/managed in client state via `MessagesContext`.
   - The client calls one of the API routes for prompt enhancement, chat, or code generation.
   - The server route forwards the request to Gemini and returns AI output.
   - Generated workspace/code data is persisted or updated through Convex, then reflected back into the UI through the workspace page and provider layer.

11. **Important architectural boundary to diagram**
   - Draw a clear separation between:
     - **browser/UI**: `app/`, `components/`, `context/`
     - **serverless AI endpoints**: `app/api/*`
     - **backend state**: `convex/`
     - **shared prompt/config assets**: `data/`, `configs/`
   - The workspace page is the center node connecting all four.

12. **Operational/deployment note**
   - The README indicates deployment on **Vercel** and runtime dependency on `GEMINI_API_KEY` plus `NEXT_PUBLIC_CONVEX_URL`.
   - The live preview may be slow or time out because code generation can exceed Vercel function limits, which is relevant when diagramming the server boundary and latency-sensitive path.

Main entry points: [`app/(main)/workspace/[id]/page.jsx`](https://github.com/ratna-babu/ai-website-builder/blob/main/app/(main)/workspace/[id]/page.jsx) (Workspace), [`components/custom/ChatView.jsx`](https://github.com/ratna-babu/ai-website-builder/blob/main/components/custom/ChatView.jsx) (Chat view), [`app/api/enhance-prompt/route.jsx`](https://github.com/ratna-babu/ai-website-builder/blob/main/app/api/enhance-prompt/route.jsx) (Prompt enhance), [`components/custom/CodeView.jsx`](https://github.com/ratna-babu/ai-website-builder/blob/main/components/custom/CodeView.jsx) (Code view)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["UI layer"]
  node_app_layout["Root shell<br/>next layout<br/>[layout.js]"]
  node_app_page["Landing page<br/>next page<br/>[page.js]"]
  node_workspace_page["Workspace<br/>next route<br/>[page.jsx]"]
  node_provider["App provider<br/>react wrapper<br/>[provider.jsx]"]
  node_convex_provider["Convex provider<br/>client provider"]
  node_header["Header<br/>marketing component<br/>[Header.jsx]"]
  node_hero["Hero<br/>marketing component<br/>[Hero.jsx]"]
  node_chat_view["Chat view<br/>builder view<br/>[ChatView.jsx]"]
  node_code_view["Code view<br/>builder view<br/>[CodeView.jsx]"]
  node_messages_context["Messages state<br/>react context<br/>[MessagesContext.js]"]
end

subgraph group_api["AI endpoints"]
  node_ai_chat_api["AI chat<br/>route handler<br/>[route.jsx]"]
  node_enhance_api["Prompt enhance<br/>route handler<br/>[route.jsx]"]
  node_codegen_api["Code gen<br/>route handler<br/>[route.jsx]"]
end

subgraph group_state["Persistence"]
  node_schema[("Workspace schema<br/>convex schema<br/>[schema.js]")]
  node_workspace_fn["Workspace ops<br/>convex functions<br/>[workspace.js]"]
end

subgraph group_shared["Shared config"]
  node_ai_model["Model config<br/>ai settings<br/>[AiModel.jsx]"]
  node_prompt_data["Prompt data<br/>prompt templates<br/>[Prompt.jsx]"]
  node_lookup_data["Lookup data<br/>prompt mapping<br/>[Lookup.jsx]"]
end

subgraph group_styles["Style system"]
  node_globals_css["Global styles<br/>tailwind css<br/>[globals.css]"]
  node_button_ui["Button UI<br/>ui primitive<br/>[button.jsx]"]
  node_utils["Utils<br/>helpers<br/>[utils.js]"]
end

node_app_layout -->|"wraps"| node_provider
node_app_layout -->|"loads"| node_globals_css
node_provider -->|"includes"| node_convex_provider
node_app_page -->|"renders"| node_header
node_app_page -->|"renders"| node_hero
node_workspace_page -->|"composes"| node_chat_view
node_workspace_page -->|"composes"| node_code_view
node_workspace_page -->|"uses"| node_messages_context
node_workspace_page -->|"syncs"| node_workspace_fn
node_chat_view -->|"reads/writes"| node_messages_context
node_code_view -->|"reads"| node_messages_context
node_chat_view -->|"calls"| node_ai_chat_api
node_chat_view -->|"calls"| node_enhance_api
node_code_view -->|"calls"| node_codegen_api
node_ai_chat_api -->|"configures"| node_ai_model
node_enhance_api -->|"configures"| node_ai_model
node_codegen_api -->|"configures"| node_ai_model
node_ai_chat_api -->|"uses"| node_prompt_data
node_enhance_api -->|"uses"| node_prompt_data
node_codegen_api -->|"uses"| node_prompt_data
node_enhance_api -->|"uses"| node_lookup_data
node_schema -->|"shapes"| node_workspace_fn
node_workspace_fn -->|"exposes"| node_convex_provider
node_button_ui -->|"uses"| node_utils

click node_app_layout "https://github.com/ratna-babu/ai-website-builder/blob/main/app/layout.js"
click node_app_page "https://github.com/ratna-babu/ai-website-builder/blob/main/app/page.js"
click node_workspace_page "https://github.com/ratna-babu/ai-website-builder/blob/main/app/(main)/workspace/[id]/page.jsx"
click node_provider "https://github.com/ratna-babu/ai-website-builder/blob/main/app/provider.jsx"
click node_convex_provider "https://github.com/ratna-babu/ai-website-builder/blob/main/app/ConvexClientProvider.jsx"
click node_header "https://github.com/ratna-babu/ai-website-builder/blob/main/components/custom/Header.jsx"
click node_hero "https://github.com/ratna-babu/ai-website-builder/blob/main/components/custom/Hero.jsx"
click node_chat_view "https://github.com/ratna-babu/ai-website-builder/blob/main/components/custom/ChatView.jsx"
click node_code_view "https://github.com/ratna-babu/ai-website-builder/blob/main/components/custom/CodeView.jsx"
click node_messages_context "https://github.com/ratna-babu/ai-website-builder/blob/main/context/MessagesContext.js"
click node_ai_chat_api "https://github.com/ratna-babu/ai-website-builder/blob/main/app/api/ai-chat/route.jsx"
click node_enhance_api "https://github.com/ratna-babu/ai-website-builder/blob/main/app/api/enhance-prompt/route.jsx"
click node_codegen_api "https://github.com/ratna-babu/ai-website-builder/blob/main/app/api/gen-ai-code/route.jsx"
click node_schema "https://github.com/ratna-babu/ai-website-builder/blob/main/convex/schema.js"
click node_workspace_fn "https://github.com/ratna-babu/ai-website-builder/blob/main/convex/workspace.js"
click node_ai_model "https://github.com/ratna-babu/ai-website-builder/blob/main/configs/AiModel.jsx"
click node_prompt_data "https://github.com/ratna-babu/ai-website-builder/blob/main/data/Prompt.jsx"
click node_lookup_data "https://github.com/ratna-babu/ai-website-builder/blob/main/data/Lookup.jsx"
click node_globals_css "https://github.com/ratna-babu/ai-website-builder/blob/main/app/globals.css"
click node_button_ui "https://github.com/ratna-babu/ai-website-builder/blob/main/components/ui/button.jsx"
click node_utils "https://github.com/ratna-babu/ai-website-builder/blob/main/lib/utils.js"

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_app_layout,node_app_page,node_workspace_page,node_provider,node_convex_provider,node_header,node_hero,node_chat_view,node_code_view,node_messages_context toneBlue
class node_ai_chat_api,node_enhance_api,node_codegen_api toneAmber
class node_schema,node_workspace_fn toneMint
class node_ai_model,node_prompt_data,node_lookup_data toneRose
class node_globals_css,node_button_ui,node_utils toneIndigo
```

## Components

### UI layer

App Router pages and React views for landing and workspace

- [Root shell](https://github.com/ratna-babu/ai-website-builder/blob/main/app/layout.js): next layout · App-wide layout and provider composition · `app/layout.js`
- [Landing page](https://github.com/ratna-babu/ai-website-builder/blob/main/app/page.js): next page · Public marketing entry point · `app/page.js`
- [Workspace](https://github.com/ratna-babu/ai-website-builder/blob/main/app/(main)/workspace/[id]/page.jsx): next route · Main builder surface for a workspace ID · `app/(main)/workspace/[id]/page.jsx`
- [App provider](https://github.com/ratna-babu/ai-website-builder/blob/main/app/provider.jsx): react wrapper · Top-level client provider composition · `app/provider.jsx`
- [Convex provider](https://github.com/ratna-babu/ai-website-builder/blob/main/app/ConvexClientProvider.jsx): client provider · Initializes Convex client access · `app/ConvexClientProvider.jsx`
- [Header](https://github.com/ratna-babu/ai-website-builder/blob/main/components/custom/Header.jsx): marketing component · Top navigation for landing pages · `components/custom/Header.jsx`
- [Hero](https://github.com/ratna-babu/ai-website-builder/blob/main/components/custom/Hero.jsx): marketing component · Landing page hero section · `components/custom/Hero.jsx`
- [Chat view](https://github.com/ratna-babu/ai-website-builder/blob/main/components/custom/ChatView.jsx): builder view · Chat and prompt interaction surface · `components/custom/ChatView.jsx`
- [Code view](https://github.com/ratna-babu/ai-website-builder/blob/main/components/custom/CodeView.jsx): builder view · Generated code and preview surface · `components/custom/CodeView.jsx`
- [Messages state](https://github.com/ratna-babu/ai-website-builder/blob/main/context/MessagesContext.js): react context · Client-side message and generation state · `context/MessagesContext.js`

### AI endpoints

Serverless routes that broker model calls

- [AI chat](https://github.com/ratna-babu/ai-website-builder/blob/main/app/api/ai-chat/route.jsx): route handler · Chat completion endpoint · `app/api/ai-chat/route.jsx`
- [Prompt enhance](https://github.com/ratna-babu/ai-website-builder/blob/main/app/api/enhance-prompt/route.jsx): route handler · Prompt refinement endpoint · `app/api/enhance-prompt/route.jsx`
- [Code gen](https://github.com/ratna-babu/ai-website-builder/blob/main/app/api/gen-ai-code/route.jsx): route handler · AI code generation endpoint · `app/api/gen-ai-code/route.jsx`

### Persistence

Convex schema and workspace operations

- [Workspace schema](https://github.com/ratna-babu/ai-website-builder/blob/main/convex/schema.js): convex schema · Persistent data model for workspaces · `convex/schema.js`
- [Workspace ops](https://github.com/ratna-babu/ai-website-builder/blob/main/convex/workspace.js): convex functions · Workspace CRUD and realtime operations · `convex/workspace.js`

### Shared config

Prompt templates and model settings

- [Model config](https://github.com/ratna-babu/ai-website-builder/blob/main/configs/AiModel.jsx): ai settings · Central model/provider selection · `configs/AiModel.jsx`
- [Prompt data](https://github.com/ratna-babu/ai-website-builder/blob/main/data/Prompt.jsx): prompt templates · Prompt text and generation instructions · `data/Prompt.jsx`
- [Lookup data](https://github.com/ratna-babu/ai-website-builder/blob/main/data/Lookup.jsx): prompt mapping · Prompt enrichment or lookup support data · `data/Lookup.jsx`

### Style system

Global styling and reusable UI primitives

- [Global styles](https://github.com/ratna-babu/ai-website-builder/blob/main/app/globals.css): tailwind css · App-wide styling foundation · `app/globals.css`
- [Button UI](https://github.com/ratna-babu/ai-website-builder/blob/main/components/ui/button.jsx): ui primitive · Reusable button component · `components/ui/button.jsx`
- [Utils](https://github.com/ratna-babu/ai-website-builder/blob/main/lib/utils.js): helpers · Shared utility helpers · `lib/utils.js`

## Connections

- Root shell → App provider: wraps · Composes app-wide client providers
- Root shell → Global styles: loads · Applies global styling
- App provider → Convex provider: includes · Installs Convex client access
- Landing page → Header: renders · Landing page uses the header
- Landing page → Hero: renders · Landing page uses the hero section
- Workspace → Chat view: composes · Builder surface includes chat
- Workspace → Code view: composes · Builder surface includes code preview
- Workspace → Messages state: uses · Workspace reads and updates client message state
- Workspace → Workspace ops: syncs · Loads and persists workspace data
- Chat view → Messages state: reads/writes · Chat interaction is mediated by context state
- Code view → Messages state: reads · Code view reflects generation state
- Chat view → AI chat: calls · Sends chat prompts to the server
- Chat view → Prompt enhance: calls · Requests prompt refinement
- Code view → Code gen: calls · Requests AI code generation
- AI chat → Model config: configures · Uses shared model settings
- Prompt enhance → Model config: configures · Uses shared model settings
- Code gen → Model config: configures · Uses shared model settings
- AI chat → Prompt data: uses · Applies prompt templates
- Prompt enhance → Prompt data: uses · Applies prompt templates
- Code gen → Prompt data: uses · Applies prompt templates
- Prompt enhance → Lookup data: uses · Enrichment and lookup support data
- Workspace schema → Workspace ops: shapes · Workspace functions operate on the schema
- Workspace ops → Convex provider: exposes · Client talks to Convex through generated bindings
- Button UI → Utils: uses · UI primitive depends on shared helpers
