# r4m21/balaji-decor-website architecture

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

- Interactive diagram: https://gitdiagram.com/r4m21/balaji-decor-website
- Repository: https://github.com/r4m21/balaji-decor-website

## Overview

##### Project type & purpose (from file tree + README)
This is a **Next.js (App Router) web application** that looks like a **marketing/lead-generation site** for a service business:

- User-facing pages:
- Home: `app/page.tsx`
- Service detail pages: `app/services/[slug]/page.tsx` + `lib/services.ts`
- Location pages: `app/locations/[slug]/page.tsx` + `lib/locations.ts`
- Thank-you page: `app/thank-you/page.tsx`
- SEO endpoints: `app/sitemap.ts`, `app/robots.ts`
- Error handling: `app/error.tsx`, `app/not-found.tsx`
- Lead capture + messaging integrations:
- Contact endpoint: `app/api/contact/route.ts` (likely used by `components/sections/ContactForm.tsx`)
- WhatsApp webhook: `app/api/whatsapp/webhook/route.ts` (incoming messages/events from WhatsApp provider)
- Shared “backend-ish” utilities in `lib/`:
- `lib/db.ts` (persistence)
- `lib/mailer.ts` (email sending)
- `lib/recaptcha.ts` (bot protection)
- `lib/rate-limit.ts` (abuse protection)
- `lib/whatsapp.ts`, `lib/whatsapp-templates.ts` (WhatsApp integration)
- `lib/env.ts`, `lib/config.ts` (configuration)

##### the frontend UI (pages/components), and
2) **backend API routes** (contact + WhatsApp webhook) that integrate with external services and storage.

##### Server/API layer (still inside the same Next.js app)
- `app/api/contact/route.ts`
- `app/api/whatsapp/webhook/route.ts`

##### Domain/config/integration layer
- `lib/*` as internal services:
- Persistence: `lib/db.ts`
- Email: `lib/mailer.ts`
- WhatsApp: `lib/whatsapp.ts`, `lib/whatsapp-templates.ts`
- Security: `lib/rate-limit.ts`, `lib/recaptcha.ts`
- Data sources for dynamic routes: `lib/services.ts`, `lib/locations.ts`
- Configuration: `lib/env.ts`, `lib/config.ts`

##### Platform/build/deploy
- Next.js config: `next.config.ts`
- Styling/build: `tailwind.config.ts`, `postcss.config.mjs`, `styles/globals.css`
- TypeScript: `tsconfig.json`, `global.d.ts`, `types/*`
- Hosting implied by README: **Vercel** (or any Node runtime)

##### Next.js App (Vercel/Node runtime)
- **App Router Pages** (`app/*`)
- **API Routes** (`app/api/*`)
##### External services
- **Email provider** (SMTP/API) used by `lib/mailer.ts`
- **Google reCAPTCHA** (or similar) used by `lib/recaptcha.ts`
- **WhatsApp Cloud API / WhatsApp provider** used by `lib/whatsapp.ts`

##### API route calls
- `lib/rate-limit.ts` (prevent spam)
- `lib/recaptcha.ts` (verify human)
- `lib/mailer.ts` (send lead email)
- `lib/db.ts` (store lead, if implemented)

- `ContactForm.tsx` → `/api/contact`
- `/api/contact` → `rate-limit` → (allow/deny)
- `/api/contact` → `recaptcha` → reCAPTCHA external API
- `/api/contact` → `mailer` → Email provider
- `/api/contact` → `db` → Database

##### Webhook route calls
- `lib/whatsapp.ts` (signature validation / parsing / sending replies)
- `lib/whatsapp-templates.ts` (message templates)
- optionally `lib/db.ts` (store conversations/events)

- WhatsApp Provider → `/api/whatsapp/webhook`
- `/api/whatsapp/webhook` → `whatsapp.ts` → (optional outbound) WhatsApp Cloud API
- `/api/whatsapp/webhook` → `db`

##### SEO/metadata flows (often omitted, but this repo has explicit files)
- Search engine crawlers → `app/sitemap.ts`, `app/robots.ts`

##### Architectural patterns to highlight
- **Monolith-but-layered Next.js app**: UI + API routes in one deployable unit.
- **App Router route-based architecture**: folders map to routes (`app/services/[slug]`, `app/api/...`).
- **Integration adapters in `lib/`**:
- `mailer.ts` as an outbound adapter
- `whatsapp.ts` as an inbound/outbound adapter
- `db.ts` as persistence adapter
- **Cross-cutting concerns** centralized:
- `env.ts`/`config.ts` for configuration
- `rate-limit.ts` and `recaptcha.ts` for security/abuse prevention

- shared modules shown as sub-components used by multiple routes

**UI Routes**
- `app/layout.tsx` (shell)
- `app/page.tsx` (home)
- `app/services/[slug]/page.tsx` (service detail)
- `app/locations/[slug]/page.tsx` (location detail)
- `app/thank-you/page.tsx`
- `app/sitemap.ts`, `app/robots.ts`
- `app/error.tsx`, `app/not-found.tsx`

**UI Building Blocks**
- `components/sections/ContactForm.tsx` (ties to /api/contact)
- `components/ui/FloatingButtons.tsx` (likely triggers WhatsApp/phone CTA)
- `components/providers/ThemeProvider.tsx`

**API Entry Points**
- `app/api/contact/route.ts`
- `app/api/whatsapp/webhook/route.ts`

**Internal Services**
- `lib/env.ts` + `lib/config.ts`
- `lib/rate-limit.ts`
- `lib/recaptcha.ts`
- `lib/mailer.ts`
- `lib/db.ts`
- `lib/whatsapp.ts` + `lib/whatsapp-templates.ts`
- `lib/services.ts` + `lib/locations.ts`

**External Dependencies**
- Database service
- Email service
- Google reCAPTCHA
- WhatsApp provider / WhatsApp Cloud API

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% ====== External Actors / Systems ======
  Visitor["Visitor Browser"]:::external
  Crawler["Search Engine Crawler"]:::external
  Staff["Staff/Admin (receives lead emails)"]:::external

  EmailProvider["Email Provider (SMTP/API)"]:::cloud
  RecaptchaSvc["Google reCAPTCHA API"]:::cloud
  WhatsAppProvider["WhatsApp Provider / Cloud API"]:::cloud
  DB[(Managed Database)]:::db

  %% ====== Platform / Hosting ======
  subgraph "Hosting / Delivery"
    CDN["CDN / Edge Network"]:::platform
    Vercel["Vercel / Node Runtime (Next.js deploy)"]:::platform
    StaticAssets["Static Assets (public/)"]:::platform
  end

  Visitor -->|"HTTPS requests"| CDN
  Crawler -->|"crawl /robots.txt & /sitemap.xml"| CDN
  CDN -->|"route to runtime"| Vercel
  CDN -->|"serve static files"| StaticAssets

  %% ====== Next.js App (Monolith) ======
  subgraph "Next.js Application (App Router + API Routes)"
    direction TB

    %% --- UI / Presentation Layer ---
    subgraph "Frontend UI (app/* + components/*)"
      direction TB

      Layout["App Router Layout (Shell)"]:::ui
      ThemeProvider["Theme Provider"]:::ui

      Header["Header"]:::ui
      Footer["Footer"]:::ui
      FloatingButtons["Floating CTA Buttons"]:::ui

      subgraph "UI Routes (app/*)"
        direction TB
        Home["Home Page Route (/)"]:::ui
        ServiceDetail["Service Detail Route (/services/[slug])"]:::ui
        LocationDetail["Location Detail Route (/locations/[slug])"]:::ui
        ThankYou["Thank-you Route (/thank-you)"]:::ui

        Sitemap["Sitemap Endpoint (/sitemap.xml)"]:::ui
        Robots["Robots Endpoint (/robots.txt)"]:::ui

        ErrorPage["Error Boundary Page"]:::ui
        NotFound["Not Found Page"]:::ui
      end

      subgraph "UI Sections (components/sections/*)"
        direction TB
        ContactForm["Contact Form Section"]:::ui
        ServicePageSection["Service Page Section"]:::ui
      end
    end

    %% --- Server/API Layer ---
    subgraph "Backend API (app/api/*)"
      direction TB
      ContactAPI["POST /api/contact"]:::api
      WhatsAppWebhookAPI["POST /api/whatsapp/webhook"]:::api
    end

    %% --- Application Services / Lib Layer ---
    subgraph "Application Services (lib/*)"
      direction TB

      subgraph "Domain Data Sources"
        direction TB
        ServicesDS["Services Data Source"]:::lib
        LocationsDS["Locations Data Source"]:::lib
      end

      subgraph "Cross-cutting Concerns"
        direction TB
        RateLimit["Rate Limiter"]:::security
        Recaptcha["reCAPTCHA Verify Adapter"]:::security
        Env["Environment Handling"]:::config
        Config["Configuration"]:::config
      end

      subgraph "Integration Adapters"
        direction TB
        Mailer["Mailer (Email Adapter)"]:::lib
        WhatsApp["WhatsApp Integration Adapter"]:::lib
        WhatsAppTemplates["WhatsApp Message Templates"]:::lib
        DBClient["DB Client / Persistence"]:::lib
      end
    end

    %% --- Build / Styling / Types (Project Config) ---
    subgraph "Build / Styling / Types"
      direction TB
      NextConfig["Next.js Configuration"]:::build
      Tailwind["Tailwind Configuration"]:::build
      PostCSS["PostCSS Configuration"]:::build
      GlobalsCSS["Global CSS"]:::build
      TSConfig["TypeScript Configuration"]:::build
      GlobalDTS["Shared Type Declarations (global.d.ts)"]:::build
      TypesGlobalDTS["Additional Type Declarations (types/global.d.ts)"]:::build
    end
  end

  %% ====== UI Composition / Rendering ======
  Layout -->|"wraps"| ThemeProvider
  Layout -->|"includes"| Header
  Layout -->|"includes"| Footer
  Layout -->|"renders"| FloatingButtons

  Visitor -->|"GET /"| Home
  Visitor -->|"GET /services/[slug]"| ServiceDetail
  Visitor -->|"GET /locations/[slug]"| LocationDetail
  Visitor -->|"GET /thank-you"| ThankYou

  Home -->|"composes"| ServicePageSection
  ServiceDetail -->|"composes"| ServicePageSection
  Home -->|"renders"| ContactForm
  ServiceDetail -->|"renders"| ContactForm
  LocationDetail -->|"renders"| ContactForm

  %% Dynamic data for pages
  ServiceDetail -->|"load content/slugs"| ServicesDS
  LocationDetail -->|"load content/slugs"| LocationsDS

  %% SEO endpoints
  Crawler -->|"GET /sitemap.xml"| Sitemap
  Crawler -->|"GET /robots.txt"| Robots
  Sitemap -->|"enumerate URLs"| ServicesDS
  Sitemap -->|"enumerate URLs"| LocationsDS

  %% ====== Contact Form Lead Flow ======
  ContactForm -->|"POST contact form"| ContactAPI
  ContactAPI -->|"check limits"| RateLimit
  ContactAPI -->|"verify token"| Recaptcha
  Recaptcha -->|"HTTPS verify"| RecaptchaSvc

  ContactAPI -->|"send lead email"| Mailer
  Mailer -->|"SMTP/API send"| EmailProvider
  EmailProvider -->|"deliver notification"| Staff

  ContactAPI -->|"store lead"| DBClient
  DBClient -->|"read/write"| DB

  %% ====== WhatsApp Webhook Flow ======
  WhatsAppProvider -->|"Webhook event"| WhatsAppWebhookAPI
  WhatsAppWebhookAPI -->|"validate/parse & reply"| WhatsApp
  WhatsApp -->|"use templates"| WhatsAppTemplates
  WhatsApp -->|"send message"| WhatsAppProvider
  WhatsAppWebhookAPI -->|"store event/conversation"| DBClient

  %% ====== Config usage ======
  ContactAPI -->|"load env/config"| Env
  ContactAPI -->|"load env/config"| Config
  WhatsAppWebhookAPI -->|"load env/config"| Env
  WhatsAppWebhookAPI -->|"load env/config"| Config
  Mailer -->|"load env/config"| Env
  WhatsApp -->|"load env/config"| Env
  DBClient -->|"load env/config"| Env

  %% ====== Click Events (Component Mapping) ======
  click Layout "https://github.com/r4m21/balaji-decor-website/blob/main/app/layout.tsx"
  click Home "https://github.com/r4m21/balaji-decor-website/blob/main/app/page.tsx"
  click ServiceDetail "https://github.com/r4m21/balaji-decor-website/blob/main/app/services/[slug]/page.tsx"
  click LocationDetail "https://github.com/r4m21/balaji-decor-website/blob/main/app/locations/[slug]/page.tsx"
  click ThankYou "https://github.com/r4m21/balaji-decor-website/blob/main/app/thank-you/page.tsx"
  click Sitemap "https://github.com/r4m21/balaji-decor-website/blob/main/app/sitemap.ts"
  click Robots "https://github.com/r4m21/balaji-decor-website/blob/main/app/robots.ts"
  click ErrorPage "https://github.com/r4m21/balaji-decor-website/blob/main/app/error.tsx"
  click NotFound "https://github.com/r4m21/balaji-decor-website/blob/main/app/not-found.tsx"

  click ContactAPI "https://github.com/r4m21/balaji-decor-website/blob/main/app/api/contact/route.ts"
  click WhatsAppWebhookAPI "https://github.com/r4m21/balaji-decor-website/blob/main/app/api/whatsapp/webhook/route.ts"

  click Header "https://github.com/r4m21/balaji-decor-website/blob/main/components/layout/Header.tsx"
  click Footer "https://github.com/r4m21/balaji-decor-website/blob/main/components/layout/Footer.tsx"
  click ThemeProvider "https://github.com/r4m21/balaji-decor-website/blob/main/components/providers/ThemeProvider.tsx"

  click ContactForm "https://github.com/r4m21/balaji-decor-website/blob/main/components/sections/ContactForm.tsx"
  click ServicePageSection "https://github.com/r4m21/balaji-decor-website/blob/main/components/sections/ServicePage.tsx"
  click FloatingButtons "https://github.com/r4m21/balaji-decor-website/blob/main/components/ui/FloatingButtons.tsx"

  click ServicesDS "https://github.com/r4m21/balaji-decor-website/blob/main/lib/services.ts"
  click LocationsDS "https://github.com/r4m21/balaji-decor-website/blob/main/lib/locations.ts"
  click DBClient "https://github.com/r4m21/balaji-decor-website/blob/main/lib/db.ts"
  click Mailer "https://github.com/r4m21/balaji-decor-website/blob/main/lib/mailer.ts"
  click Recaptcha "https://github.com/r4m21/balaji-decor-website/blob/main/lib/recaptcha.ts"
  click RateLimit "https://github.com/r4m21/balaji-decor-website/blob/main/lib/rate-limit.ts"
  click WhatsApp "https://github.com/r4m21/balaji-decor-website/blob/main/lib/whatsapp.ts"
  click WhatsAppTemplates "https://github.com/r4m21/balaji-decor-website/blob/main/lib/whatsapp-templates.ts"
  click Config "https://github.com/r4m21/balaji-decor-website/blob/main/lib/config.ts"
  click Env "https://github.com/r4m21/balaji-decor-website/blob/main/lib/env.ts"

  click GlobalsCSS "https://github.com/r4m21/balaji-decor-website/blob/main/styles/globals.css"
  click StaticAssets "https://github.com/r4m21/balaji-decor-website/tree/main/public/"
  click NextConfig "https://github.com/r4m21/balaji-decor-website/blob/main/next.config.ts"
  click Tailwind "https://github.com/r4m21/balaji-decor-website/blob/main/tailwind.config.ts"
  click PostCSS "https://github.com/r4m21/balaji-decor-website/blob/main/postcss.config.mjs"
  click TSConfig "https://github.com/r4m21/balaji-decor-website/blob/main/tsconfig.json"
  click GlobalDTS "https://github.com/r4m21/balaji-decor-website/blob/main/global.d.ts"
  click TypesGlobalDTS "https://github.com/r4m21/balaji-decor-website/blob/main/types/global.d.ts"

  %% ====== Styles ======
  classDef external fill:#ffffff,stroke:#475569,stroke-width:1px,color:#0f172a
  classDef platform fill:#e0f2fe,stroke:#0284c7,stroke-width:1px,color:#0f172a
  classDef ui fill:#dbeafe,stroke:#2563eb,stroke-width:1px,color:#0f172a
  classDef api fill:#ffedd5,stroke:#ea580c,stroke-width:1px,color:#0f172a
  classDef lib fill:#e5e7eb,stroke:#6b7280,stroke-width:1px,color:#111827
  classDef security fill:#fee2e2,stroke:#ef4444,stroke-width:1px,color:#111827
  classDef config fill:#fef9c3,stroke:#ca8a04,stroke-width:1px,color:#111827
  classDef cloud fill:#f3e8ff,stroke:#7c3aed,stroke-width:1px,color:#111827
  classDef db fill:#dcfce7,stroke:#16a34a,stroke-width:1px,color:#052e16
  classDef build fill:#f1f5f9,stroke:#64748b,stroke-width:1px,color:#0f172a
```
