# hardeepsingh980/sikhsoorme architecture

> Architecture diagram of the GitHub repository hardeepsingh980/sikhsoorme, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/hardeepsingh980/sikhsoorme
- Repository: https://github.com/hardeepsingh980/sikhsoorme

## Overview

##### Project Type and Purpose
- This is a full-stack Next.js web application bootstrapped with `create-next-app`.
- It renders a content-driven site (pages under `app/` such as “about,” “categories,” “soorme/[category]/[slug]”) and includes search, timeline, and data-driven pages based on JSON files and a Supabase backend.
- Build scripts generate static JSON (in `public/generated/`) and optionally push data to Supabase.

##### File Structure Analysis
- **app/** – Next.js App Router directory: static and dynamic routes, global layout (`layout.tsx`), global CSS (`globals.css`), and route-specific logic (e.g., `search/actions.ts`).
- **components/** – Reusable UI atoms (`ui/`), molecules (cards, badges, forms), and higher-level layouts (Header, Footer, QuickStats).
- **data/** – Raw content JSON for “personalities.”
- **public/generated/** – Build-time artifacts: `categories.json`, `homepageData.json`, `timeline.json`.
- **lib/** – Shared utilities: Supabase client (`supabase.ts`), helper functions (`utils.ts`).
- **scripts/** – Node scripts that read `data/`, generate JSON in `public/generated/`, and optionally push data to Supabase.
- **.github/workflows/** – CI/CD (e.g., `deploy.yml`).
- **tailwind.config.ts**, **postcss.config.mjs** – Tailwind CSS setup.
- **next.config.ts** – Next.js config for SSG/SSR, font optimization, etc.

##### Key Architectural Patterns
- **Static-Site Generation (SSG)** for most content pages using JSON under `public/generated/`.
- **Server-Side Rendering (SSR) / Server Actions** for dynamic features (e.g., search) that call the Supabase API via `lib/supabase.ts`.
- **App Router** (Next.js 13+), dynamic routes (`app/soorme/[category]/[slug]`).
- **Build Pipeline** – Custom scripts generate and transform data at build time, integrated into CI/CD.
- **Component-Driven UI** leveraging Tailwind CSS and headless UI primitives.

##### Components
a. Client (Web Browser)
b. CDN / Edge Network (Vercel Hosting)
c. Next.js Serverless Functions (App Router, SSR, Server Actions)
d. Static Assets (public/generated JSON, CSS, JS bundles)
e. Supabase Database (external service)
f. Build System
- GitHub Actions → runs `scripts/` → produces JSON → deploys to Vercel
g. Developer Workstation (Git push, CI trigger)

##### Interaction Flows
- **Build Time**
1. Developer commits → GitHub Actions triggers → build scripts (`scripts/generate*`) read `data/`, write to `public/generated/`.
2. Next.js build compiles pages/components, incorporates generated JSON into static pages.
3. Deploy to Vercel.
- **Runtime**
1. Browser requests a page → served from CDN (static or SSR).
2. For dynamic routes (search), Next.js Server Action calls Supabase via `lib/supabase.ts` → returns results → page renders.
3. User navigation uses Next.js client router to fetch JSON or hit SSR endpoints.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Build Pipeline
    subgraph "Build Pipeline"
        dev["Developer Workstation"]:::build
        gh["GitHub Actions Build"]:::build
        scripts["Data Generation Scripts"]:::build
        raw_data["Raw Content Data\ndata/personalities"]:::build
        gen_json["Generated Static JSON\npublic/generated"]:::build
        configs["Config Files\n(next.config.ts,\ntailwind.config.ts,\npostcss.config.mjs)"]:::build
        vercel_build["Vercel Build & Deploy"]:::build

        dev --> gh
        gh --> scripts
        scripts --> raw_data
        scripts --> gen_json
        configs --> gh
        gen_json --> vercel_build
    end

    %% Hosting Layer
    subgraph "Vercel Hosting"
        vercel_build --> cdn["Vercel CDN (Static)"]:::runtime
        vercel_build --> serverless["Vercel Serverless\n(Next.js SSR/SSG)"]:::runtime

        %% Static Assets
        gen_json --> static_assets["Static Assets\n(public/generated)"]:::runtime
        static_assets --> cdn

        %% App Router
        subgraph "App Router (app/)" 
            layout["Global Layout\napp/layout.tsx"]:::app
            styles["Global Styles\nglobals.css"]:::app
            page_home["Home\napp/page.tsx"]:::app
            page_about["About\napp/about/page.tsx"]:::app
            page_contact["Contact\napp/contact/page.tsx"]:::app
            page_license["License\napp/license/page.tsx"]:::app
            page_privacy["Privacy\napp/privacy/page.tsx"]:::app
            page_contribute["Contribute\napp/contribute/page.tsx"]:::app
            page_categories["Categories\napp/categories/page.tsx"]:::app
            page_all["All Items\napp/all/page.tsx"]:::app
            page_all_types["All Items Types\napp/all/types.ts"]:::app
            page_timeline["Timeline\napp/timeline/page.tsx"]:::app
            page_cat_list["Category Listing\napp/soorme/[category]/page.tsx"]:::app
            page_item_detail["Item Detail\napp/soorme/[category]/[slug]/page.tsx"]:::app
            search_actions["Search Actions\napp/search/actions.ts"]:::app
            search_page["Search Page\napp/search/page.tsx"]:::app

            serverless --> layout
            serverless --> styles
            serverless --> page_home
            serverless --> page_about
            serverless --> page_contact
            serverless --> page_license
            serverless --> page_privacy
            serverless --> page_contribute
            serverless --> page_categories
            serverless --> page_all
            serverless --> page_all_types
            serverless --> page_timeline
            serverless --> page_cat_list
            serverless --> page_item_detail
            serverless --> search_actions
            serverless --> search_page
        end
    end

    %% Runtime Services
    subgraph "Runtime Services"
        supabase[(Supabase Database & Auth)]:::external
        serverless --> supabase
    end

    %% Client
    browser["Web Browser"]:::client
    browser --> cdn
    browser --> serverless

    %% Click Events
    click dev "https://github.com/hardeepsingh980/sikhsoorme/blob/main/."
    click gh "https://github.com/hardeepsingh980/sikhsoorme/blob/main/.github/workflows/deploy.yml"
    click scripts "https://github.com/hardeepsingh980/sikhsoorme/tree/main/scripts/"
    click raw_data "https://github.com/hardeepsingh980/sikhsoorme/tree/main/data/personalities/"
    click gen_json "https://github.com/hardeepsingh980/sikhsoorme/tree/main/public/generated/"
    click configs "https://github.com/hardeepsingh980/sikhsoorme/blob/main/next.config.ts"
    click configs "https://github.com/hardeepsingh980/sikhsoorme/blob/main/tailwind.config.ts"
    click configs "https://github.com/hardeepsingh980/sikhsoorme/blob/main/postcss.config.mjs"
    click vercel_build "https://github.com/hardeepsingh980/sikhsoorme/blob/main/."
    click cdn "https://github.com/hardeepsingh980/sikhsoorme/blob/main/."
    click serverless "https://github.com/hardeepsingh980/sikhsoorme/tree/main/app/"
    click layout "https://github.com/hardeepsingh980/sikhsoorme/blob/main/app/layout.tsx"
    click styles "https://github.com/hardeepsingh980/sikhsoorme/blob/main/app/globals.css"
    click page_home "https://github.com/hardeepsingh980/sikhsoorme/blob/main/app/page.tsx"
    click page_about "https://github.com/hardeepsingh980/sikhsoorme/blob/main/app/about/page.tsx"
    click page_contact "https://github.com/hardeepsingh980/sikhsoorme/blob/main/app/contact/page.tsx"
    click page_license "https://github.com/hardeepsingh980/sikhsoorme/blob/main/app/license/page.tsx"
    click page_privacy "https://github.com/hardeepsingh980/sikhsoorme/blob/main/app/privacy/page.tsx"
    click page_contribute "https://github.com/hardeepsingh980/sikhsoorme/blob/main/app/contribute/page.tsx"
    click page_categories "https://github.com/hardeepsingh980/sikhsoorme/blob/main/app/categories/page.tsx"
    click page_all "https://github.com/hardeepsingh980/sikhsoorme/blob/main/app/all/page.tsx"
    click page_all_types "https://github.com/hardeepsingh980/sikhsoorme/blob/main/app/all/types.ts"
    click page_timeline "https://github.com/hardeepsingh980/sikhsoorme/blob/main/app/timeline/page.tsx"
    click page_cat_list "https://github.com/hardeepsingh980/sikhsoorme/blob/main/app/soorme/[category]/page.tsx"
    click page_item_detail "https://github.com/hardeepsingh980/sikhsoorme/blob/main/app/soorme/[category]/[slug]/page.tsx"
    click search_actions "https://github.com/hardeepsingh980/sikhsoorme/blob/main/app/search/actions.ts"
    click search_page "https://github.com/hardeepsingh980/sikhsoorme/blob/main/app/search/page.tsx"
    click static_assets "https://github.com/hardeepsingh980/sikhsoorme/tree/main/public/generated/"
    click supabase "https://github.com/hardeepsingh980/sikhsoorme/blob/main/."
    
    %% Styles
    classDef build fill:#dddddd,stroke:#888888,color:#333333
    classDef runtime fill:#e0f7ff,stroke:#007acc,color:#003366
    classDef external fill:#e6ffe6,stroke:#33cc33,color:#006600
    classDef client fill:#fff2cc,stroke:#ff9900,color:#996600
    classDef app fill:#f0f0f0,stroke:#cccccc,color:#333333
```
