# sabbirhosen44/ai-website-builder architecture

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

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

## Overview

1. This is a two-tier full-stack TypeScript application: a React/Vite frontend and an Express/Node backend. The backend exposes REST APIs under `/api/v1` plus an auth surface under `/api/auth`, and the frontend consumes them through Axios and TanStack Query.

2. The backend follows a clear controller → service → persistence flow. Routes in `backend/routes` map to controllers, controllers delegate to services, and services use Prisma via `backend/lib/prisma.ts` to access PostgreSQL. Error handling is centralized through async wrappers and a global error middleware.

3. The main domain is “projects” and “users.” Project APIs handle creating projects, updating generated code, saving manual edits, previewing content, publishing/unpublishing, listing public projects, deleting projects, and rolling back to version snapshots. User APIs handle credit balance, credit purchase, and listing a user’s projects.

4. AI generation is isolated in `backend/services/ai.service.ts` and configured through `backend/config/ai.config.ts`, `openai.config.ts`, and prompt constants. The README indicates a fallback chain across multiple LLMs, so AI request handling is a dedicated subsystem rather than embedded in controllers.

5. Credit-based monetization is a separate backend concern. `backend/config/stripe.config.ts`, `backend/services/stripe.service.ts`, and `backend/controllers/webhook.controller.ts` indicate Stripe-backed payments and webhook processing, likely used to replenish user credits and reconcile payment events.

6. Authentication is backend-enforced and likely session/JWT-based via Better Auth plus custom middleware. `backend/lib/auth.ts` and `backend/middlewares/auth.middleware.ts` show that protected project and user routes are gated before business logic runs.

7. Persistence is centered on Prisma and PostgreSQL. The presence of a Prisma schema and migrations suggests the system stores users, projects, versions, and conversation history as first-class entities, with version immutability being an architectural feature for rollback and auditability.

8. The frontend is organized as a routed SPA. `App.tsx`, `layout/RootLayout.tsx`, and pages like `HomePage`, `ProjectsPage`, `MyProjectsPage`, `PreviewPage`, `PricingPage`, `SettingsPage`, and `AuthPage` define the user-facing flows from marketing pages to authenticated product areas.

9. The editor experience is a composed UI made of specialized panels rather than a monolithic page. Components like `ChatSidebar`, `EditorPanel`, `PreviewPanel`, and `ConfirmModal` suggest a split workspace where the user chats with the AI, inspects generated code, and previews output side by side.

10. Client-side state and server state are separated. `src/lib/react-query.ts`, feature hooks in `src/hooks`, and API modules in `src/api` indicate that remote data is fetched and cached centrally, while UI components stay mostly declarative.

11. Auth and API configuration on the frontend are also isolated. `src/lib/auth-client.ts` and `src/lib/axios.ts` act as boundary adapters between the SPA and backend, so authentication, base URLs, and request behavior are not scattered across components.

12. The main runtime data flow is: user input in the chat/editor UI → frontend API call → authenticated backend controller → service layer → AI/Stripe/Prisma integrations → persisted project/version state → refreshed UI preview and project views. The architecture is therefore centered on an AI-assisted project lifecycle with persistence, billing, and rollback as supporting subsystems.

Main entry points: [`backend/routes/project.route.ts`](https://github.com/sabbirhosen44/ai-website-builder/blob/main/backend/routes/project.route.ts) (API Routes), [`backend/services/project.service.ts`](https://github.com/sabbirhosen44/ai-website-builder/blob/main/backend/services/project.service.ts) (Project Service), [`frontend/src/lib/axios.ts`](https://github.com/sabbirhosen44/ai-website-builder/blob/main/frontend/src/lib/axios.ts) (API Layer), [`frontend/src/pages/HomePage.tsx`](https://github.com/sabbirhosen44/ai-website-builder/blob/main/frontend/src/pages/HomePage.tsx) (Pages)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_backend["Backend"]
  node_server["Server<br/>Express entry<br/>[server.ts]"]
  node_api_routes["API Routes<br/>HTTP routing<br/>[project.route.ts]"]
  node_project_controller["Project Ctrl<br/>controller"]
  node_user_controller["User Ctrl<br/>controller<br/>[user.controller.ts]"]
  node_webhook_controller["Webhook Ctrl<br/>controller"]
  node_project_service["Project Service<br/>domain service<br/>[project.service.ts]"]
  node_user_service["User Service<br/>domain service<br/>[user.service.ts]"]
  node_ai_service["AI Service<br/>LLM orchestration<br/>[ai.service.ts]"]
  node_stripe_service["Stripe Service<br/>payments<br/>[stripe.service.ts]"]
  node_prisma_client[("Prisma<br/>persistence client<br/>[prisma.ts]")]
  node_auth_lib["Auth Lib<br/>auth adapter<br/>[auth.ts]"]
  node_middleware["Middleware<br/>request pipeline"]
end

subgraph group_frontend["Frontend"]
  node_frontend_app["SPA Shell<br/>React app<br/>[App.tsx]"]
  node_root_layout["Root Layout<br/>[RootLayout.tsx]"]
  node_pages["Pages<br/>route views<br/>[HomePage.tsx]"]
  node_workspace_ui["Workspace UI<br/>editor interface<br/>[ChatSidebar.tsx]"]
  node_client_api["API Layer<br/>HTTP client<br/>[axios.ts]"]
  node_query_state["Query State<br/>server state<br/>[react-query.ts]"]
  node_auth_client["Auth Client<br/>auth adapter<br/>[auth-client.ts]"]
end

node_server -->|"uses"| node_middleware
node_server -->|"mounts"| node_api_routes
node_api_routes -->|"maps to"| node_project_controller
node_api_routes -->|"maps to"| node_user_controller
node_api_routes -->|"maps to"| node_webhook_controller
node_project_controller -->|"delegates"| node_project_service
node_user_controller -->|"delegates"| node_user_service
node_webhook_controller -->|"delegates"| node_stripe_service
node_project_service -->|"calls"| node_ai_service
node_project_service -->|"persists"| node_prisma_client
node_user_service -->|"persists"| node_prisma_client
node_stripe_service -->|"persists"| node_prisma_client
node_middleware -->|"guards"| node_auth_lib
node_frontend_app -->|"composes"| node_root_layout
node_root_layout -->|"renders"| node_pages
node_pages -->|"uses"| node_workspace_ui
node_workspace_ui -->|"calls"| node_client_api
node_client_api -->|"feeds"| node_query_state
node_client_api -->|"uses"| node_auth_client
node_query_state -->|"powers"| node_pages

click node_server "https://github.com/sabbirhosen44/ai-website-builder/blob/main/backend/server.ts"
click node_api_routes "https://github.com/sabbirhosen44/ai-website-builder/blob/main/backend/routes/project.route.ts"
click node_project_controller "https://github.com/sabbirhosen44/ai-website-builder/blob/main/backend/controllers/project.controller.ts"
click node_user_controller "https://github.com/sabbirhosen44/ai-website-builder/blob/main/backend/controllers/user.controller.ts"
click node_webhook_controller "https://github.com/sabbirhosen44/ai-website-builder/blob/main/backend/controllers/webhook.controller.ts"
click node_project_service "https://github.com/sabbirhosen44/ai-website-builder/blob/main/backend/services/project.service.ts"
click node_user_service "https://github.com/sabbirhosen44/ai-website-builder/blob/main/backend/services/user.service.ts"
click node_ai_service "https://github.com/sabbirhosen44/ai-website-builder/blob/main/backend/services/ai.service.ts"
click node_stripe_service "https://github.com/sabbirhosen44/ai-website-builder/blob/main/backend/services/stripe.service.ts"
click node_prisma_client "https://github.com/sabbirhosen44/ai-website-builder/blob/main/backend/lib/prisma.ts"
click node_auth_lib "https://github.com/sabbirhosen44/ai-website-builder/blob/main/backend/lib/auth.ts"
click node_middleware "https://github.com/sabbirhosen44/ai-website-builder/blob/main/backend/middlewares/asyncHandler.middleware.ts"
click node_frontend_app "https://github.com/sabbirhosen44/ai-website-builder/blob/main/frontend/src/App.tsx"
click node_root_layout "https://github.com/sabbirhosen44/ai-website-builder/blob/main/frontend/src/layout/RootLayout.tsx"
click node_pages "https://github.com/sabbirhosen44/ai-website-builder/blob/main/frontend/src/pages/HomePage.tsx"
click node_workspace_ui "https://github.com/sabbirhosen44/ai-website-builder/blob/main/frontend/src/components/ChatSidebar.tsx"
click node_client_api "https://github.com/sabbirhosen44/ai-website-builder/blob/main/frontend/src/lib/axios.ts"
click node_query_state "https://github.com/sabbirhosen44/ai-website-builder/blob/main/frontend/src/lib/react-query.ts"
click node_auth_client "https://github.com/sabbirhosen44/ai-website-builder/blob/main/frontend/src/lib/auth-client.ts"

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_server,node_api_routes,node_project_controller,node_user_controller,node_webhook_controller,node_project_service,node_user_service,node_ai_service,node_stripe_service,node_prisma_client,node_auth_lib,node_middleware toneBlue
class node_frontend_app,node_root_layout,node_pages,node_workspace_ui,node_client_api,node_query_state,node_auth_client toneAmber
```

## Components

### Backend

Express/Node API, business logic, and persistence

- [Server](https://github.com/sabbirhosen44/ai-website-builder/blob/main/backend/server.ts): Express entry · Bootstraps the API server and mounts routes and middleware. · `backend/server.ts`
- [API Routes](https://github.com/sabbirhosen44/ai-website-builder/blob/main/backend/routes/project.route.ts): HTTP routing · Maps REST surfaces to controllers for projects and users. · `backend/routes/project.route.ts`
- [Project Ctrl](https://github.com/sabbirhosen44/ai-website-builder/blob/main/backend/controllers/project.controller.ts): controller · Handles project lifecycle requests and delegates to services. · `backend/controllers/project.controller.ts`
- [User Ctrl](https://github.com/sabbirhosen44/ai-website-builder/blob/main/backend/controllers/user.controller.ts): controller · Handles user credit and project listing requests. · `backend/controllers/user.controller.ts`
- [Webhook Ctrl](https://github.com/sabbirhosen44/ai-website-builder/blob/main/backend/controllers/webhook.controller.ts): controller · Processes Stripe webhook events from the payment surface. · `backend/controllers/webhook.controller.ts`
- [Project Service](https://github.com/sabbirhosen44/ai-website-builder/blob/main/backend/services/project.service.ts): domain service · Implements project creation, updates, versions, preview, publish, and rollback. · `backend/services/project.service.ts`
- [User Service](https://github.com/sabbirhosen44/ai-website-builder/blob/main/backend/services/user.service.ts): domain service · Implements user-centric credit and ownership workflows. · `backend/services/user.service.ts`
- [AI Service](https://github.com/sabbirhosen44/ai-website-builder/blob/main/backend/services/ai.service.ts): LLM orchestration · Coordinates generation requests and model fallback logic. · `backend/services/ai.service.ts`
- [Stripe Service](https://github.com/sabbirhosen44/ai-website-builder/blob/main/backend/services/stripe.service.ts): payments · Handles payment-side logic that supports credit purchases and reconciliation. · `backend/services/stripe.service.ts`
- [Prisma](https://github.com/sabbirhosen44/ai-website-builder/blob/main/backend/lib/prisma.ts): persistence client · Shared database access layer for PostgreSQL via Prisma. · `backend/lib/prisma.ts`
- [Auth Lib](https://github.com/sabbirhosen44/ai-website-builder/blob/main/backend/lib/auth.ts): auth adapter · Backend auth integration and session/JWT support. · `backend/lib/auth.ts`
- [Middleware](https://github.com/sabbirhosen44/ai-website-builder/blob/main/backend/middlewares/asyncHandler.middleware.ts): request pipeline · Async wrapping, auth gating, and global error handling. · `backend/middlewares/asyncHandler.middleware.ts`

### Frontend

React/Vite SPA, UI flows, and client data access

- [SPA Shell](https://github.com/sabbirhosen44/ai-website-builder/blob/main/frontend/src/App.tsx): React app · Top-level client application and route composition. · `frontend/src/App.tsx`
- [Root Layout](https://github.com/sabbirhosen44/ai-website-builder/blob/main/frontend/src/layout/RootLayout.tsx): layout · Shared frame for the routed frontend experience. · `frontend/src/layout/RootLayout.tsx`
- [Pages](https://github.com/sabbirhosen44/ai-website-builder/blob/main/frontend/src/pages/HomePage.tsx): route views · Public and authenticated screens for marketing, auth, projects, preview, pricing, and settings. · `frontend/src/pages/HomePage.tsx`
- [Workspace UI](https://github.com/sabbirhosen44/ai-website-builder/blob/main/frontend/src/components/ChatSidebar.tsx): editor interface · Composed chat/editor/preview workspace for AI-assisted building. · `frontend/src/components/ChatSidebar.tsx`
- [API Layer](https://github.com/sabbirhosen44/ai-website-builder/blob/main/frontend/src/lib/axios.ts): HTTP client · Axios-based backend adapter and feature API modules. · `frontend/src/lib/axios.ts`
- [Query State](https://github.com/sabbirhosen44/ai-website-builder/blob/main/frontend/src/lib/react-query.ts): server state · TanStack Query setup and feature hooks for cached remote data. · `frontend/src/lib/react-query.ts`
- [Auth Client](https://github.com/sabbirhosen44/ai-website-builder/blob/main/frontend/src/lib/auth-client.ts): auth adapter · Frontend auth integration boundary for the SPA. · `frontend/src/lib/auth-client.ts`

## Connections

- Server → Middleware: uses · Requests pass through async handling, auth checks, and error middleware.
- Server → API Routes: mounts · Server exposes REST routes under the API surface.
- API Routes → Project Ctrl: maps to · Project routes dispatch into project controller handlers.
- API Routes → User Ctrl: maps to · User routes dispatch into user controller handlers.
- API Routes → Webhook Ctrl: maps to · Webhook endpoints dispatch into payment event handling.
- Project Ctrl → Project Service: delegates · Controllers keep business logic in the service layer.
- User Ctrl → User Service: delegates · User requests are processed by domain services.
- Webhook Ctrl → Stripe Service: delegates · Webhook events are translated into Stripe-backed domain actions.
- Project Service → AI Service: calls · Project generation and regeneration rely on AI orchestration.
- Project Service → Prisma: persists · Projects, versions, and related state are stored through Prisma.
- User Service → Prisma: persists · User credits and ownership data are read and updated in PostgreSQL.
- Stripe Service → Prisma: persists · Payment reconciliation updates application state through the database.
- Middleware → Auth Lib: guards · Protected endpoints are enforced through backend auth integration.
- SPA Shell → Root Layout: composes · The SPA is framed by shared layout and routing structure.
- Root Layout → Pages: renders · Route-level pages provide the main product and marketing flows.
- Pages → Workspace UI: uses · Editor and preview pages assemble the chat/editor workspace.
- Workspace UI → API Layer: calls · UI actions trigger backend requests through the API boundary.
- API Layer → Query State: feeds · API modules are consumed through query hooks and cached server state.
- API Layer → Auth Client: uses · Request behavior and authentication are configured at the client boundary.
- Query State → Pages: powers · Pages read and refresh server state through hooks.
