# abdul-0-muheed/sdc-admin architecture

> Architecture diagram of the GitHub repository abdul-0-muheed/sdc-admin, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-03-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/abdul-0-muheed/sdc-admin
- Repository: https://github.com/abdul-0-muheed/sdc-admin

## Overview

Summary / project type and purpose
- This is a Next.js (app-router) web application using Supabase as its backend (BaaS) for authentication, database and realtime events. The codebase is a single repo full‑stack web app (frontend + cloud-managed backend services), not a separate microservice architecture.
- Purpose (inferred from file structure): an admin interface for managing content (events, news) with sign-in / protected routes and realtime event handling.

Key evidence from the files
- Next.js app-router layout: src/app/layout.js, src/app/page.js, src/app/globals.css, and app route folders (src/app/admin, src/app/signin).
- Pages for admin content: src/app/admin/content/events/page.js and src/app/admin/content/news/page.js (UI for content management).
- Auth UI and protection: componets/SignIn.js, componets/AuthProvider.js, componets/ProtectedRoute.js (note: folder name typo "componets").
- Supabase integration: lib/supabaseClient.ts (client factory), lib/supabaseEvents.js (realtime/event subscription).
- Deployment/build hints: next.config.mjs, package.json, postcss.config.mjs, public static assets.
- README indicates default Next.js app created by create-next-app.

How to represent the architecture (main components and relationships)

- Browser -> Next.js App: HTTP(S) requests for pages; client-side JS fetches for data.
- Next.js App (client components) -> Supabase JS client (lib/supabaseClient.ts): direct JS SDK calls over HTTPS and WebSocket for realtime.
- Supabase -> Next.js App: responds with data (JSON), emits realtime updates to subscribed clients.
- Next.js App -> Vercel / CI: push -> build -> deploy (only for deployment flow).
- Browser <- WebSocket -> Supabase Realtime: show live updates in admin UI.
- Auth flow: SignIn component calls supabase.auth.signIn -> Supabase Auth returns session/JWT -> AuthProvider stores session and supplies to ProtectedRoute -> ProtectedRoute conditionally renders admin pages or redirects to sign-in.

##### Important architectural/design patterns to call out
- Component-based UI (React/Next.js) with App Router: UI broken into pages and reusable components (navbar, sign-in, protected route).
- Client-first BaaS pattern: business logic and data access happen from the browser using the Supabase JS client (no separate server API layer).
- Auth session provider pattern: a context/provider (AuthProvider.js) provides authentication state to the UI, with route protection wrappers (ProtectedRoute).
- Realtime subscription pattern: separate module (lib/supabaseEvents.js) handles subscribing to DB changes and propagating updates to the UI.
- Separation of concerns: lib/ for external integrations, componet(s) for UI, src/app for routing and page composition, public for static assets.
- Security consideration: environment variables for SUPABASE keys must be server-side or use anon key with RLS (Row Level Security) in Supabase.

- Next.js (App Router)
- React components
- Supabase (Auth, Postgres DB, Realtime)
- JavaScript/TypeScript (lib/supabaseClient.ts)
- Hosting/CI: Vercel (or similar)
- Protocols: HTTPS (REST-like requests), WebSocket (realtime)
- Local dev: npm run dev (localhost:3000)

- Authentication flow explicitly:
- SignIn UI -> supabaseClient.auth -> Supabase Auth -> returned session/token -> AuthProvider (store) -> ProtectedRoute gating.
- Realtime flow explicitly:
- Client subscription initialization (lib/supabaseEvents.js) -> Supabase Realtime (WebSocket) -> DB change events -> client updates UI (events/news pages).
- Data flows for content pages:
- Admin pages (events/news) perform CRUD via supabaseClient -> Postgres.
- Where row-level security or server-authorization would be enforced (Supabase side) if applicable.
- Build & deployment:
- Developer commits -> Git repo -> Vercel build -> next build -> deployed app -> CDN for public assets -> users hit Vercel edge -> Next.js handles routes.
- Error-handling and monitoring (optional but recommended):
- Logging component (Sentry/Log service) receiving errors from client and server.

Visual conventions to include

What to include (checklist)
- Clear component labels: Browser, Next.js App (Pages, Components, Layout), lib/supabaseClient.ts, lib/supabaseEvents.js, Supabase (Auth, DB, Realtime), CI/CD/Hosting.
- Browser -> Next.js (HTTP)
- Browser -> Supabase (via supabaseClient from client)
- Next.js build/deploy flows to Vercel
- Annotations:
- Protocols (HTTPS, WS)
- Environment variables used (SUPABASE_URL, SUPABASE_ANON_KEY / SERVICE_KEY)
- Location of role-based access or row-level security (Supabase)
- Distinguish frontend (UI), app server/edge, external services, and dev pipelines.

- UI / Pages:
- src/app/page.js (public homepage)
- src/app/signin/page.js + componets/SignIn.js (signin flow)
- src/app/admin/page.js (admin landing)
- src/app/admin/content/events/page.js and news/page.js (content editors)
- componets/navbar.js (navigation)
- Auth and protection:
- componets/AuthProvider.js (auth context/session)
- componets/ProtectedRoute.js (route guarding)
- Integration:
- lib/supabaseClient.ts (single supabase JS client instance)
- lib/supabaseEvents.js (realtime subscription/handlers)

Where to emphasize precision and what not to overthink
- Be very detailed about the data flow and auth boundaries: who holds the JWT, which client calls go to Supabase, and how realtime subscriptions are established.
- Don’t overcomplicate by inventing backend microservices that do not exist. This repo uses a BaaS model—represent Supabase as the backend with the Next.js app as the client-side orchestrator.
- As many components as possible and show how they connect (files -> logical components -> external services).

Recommended drawing tools & formats

##### Middle left: Browser (User)
- nested: SignIn UI, Admin UI (events/news), Navbar
##### Middle center: Next.js App (deployed)
- split into Server/Edge responsibilities and Client components
- Lib/supabaseClient.ts and lib/supabaseEvents.js as connectors
##### Middle right: Supabase
- Auth, Postgres DB, Realtime (WebSocket)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Top: Dev & CI/CD
    Dev["Developer / Git (local)"]:::dev
    Dev -->|pushes| Repo["Git Repository"]:::dev
    Repo -->|trigger CI/CD| CI["CI/CD (Vercel)"]:::ci
    CI -->|build: next build / deploy| Vercel["Vercel / Hosting (Edge)"]:::ci
    Vercel -.->|serves| CDN["CDN (static assets)"]:::infra

    %% Middle: Client (Browser) on left
    subgraph "Browser / Client (User)" 
        direction TB
        Browser["Browser (User)"]:::browser

        subgraph "Public UI"
            direction TB
            Home["Home Page\nsrc/app/page.js"]:::page
            SignInPage["Sign-In Page\nsrc/app/signin/page.js"]:::page
            SignInComp["SignIn Component\ncomponets/SignIn.js"]:::component
            Navbar["Navbar\ncomponets/navbar.js"]:::component
        end

        subgraph "Admin UI (Protected)"
            direction TB
            AdminLanding["Admin Landing\nsrc/app/admin/page.js"]:::page
            EventsEditor["Events Editor\nsrc/app/admin/content/events/page.js"]:::page
            NewsEditor["News Editor\nsrc/app/admin/content/news/page.js"]:::page
            ProtectedRoute["ProtectedRoute\ncomponets/ProtectedRoute.js"]:::component
        end

        Browser -->|visits| Home
        Browser -->|visits| SignInPage
        SignInPage -->|uses| SignInComp
        Home -->|shows| Navbar
        SignInPage -->|shows| Navbar
        AdminLanding -->|shows| Navbar
        AdminLanding -->|gated by| ProtectedRoute
        EventsEditor -->|gated by| ProtectedRoute
        NewsEditor -->|gated by| ProtectedRoute
    end

    %% Center: Next.js App (deployed) - server/edge and client code
    subgraph "Next.js App (App Router) - Deployed" 
        direction TB
        NextApp["Next.js App\n(src/app)"]:::next
        Layout["Layout & Styles\nsrc/app/layout.js\nsrc/app/globals.css"]:::file
        Components["UI Components\ncomponets/*"]:::component
        AuthProvider["AuthProvider\ncomponets/AuthProvider.js"]:::component
        SupabaseClient["supabaseClient.ts\nlib/supabaseClient.ts"]:::lib
        SupabaseEvents["supabaseEvents.js\nlib/supabaseEvents.js"]:::lib
        StaticPublic["Public Static Assets\npublic/"]:::infra
        NextConfig["next.config.mjs\npackage.json\nREADME.md"]:::file

        NextApp --> Layout
        NextApp --> Components
        Components -->|wraps| AuthProvider
        AuthProvider -->|uses| SupabaseClient
        Components -->|calls| SupabaseClient
        Components -->|subscribes via| SupabaseEvents
        NextApp --> StaticPublic
        NextApp --> NextConfig
    end

    %% Right: Supabase (external)
    subgraph "Supabase (BaaS - External Service)" 
        direction TB
        SupabaseAuth["Auth Service (JWT / Sessions)"]:::external
        SupabaseDB["Postgres DB (events, news)"]:::db
        SupabaseRealtime["Realtime (WebSocket)"]:::external
        SupabaseStorage["Storage (optional)"]:::external
    end

    %% Bottom: Local dev optional
    subgraph "Local Development (optional)" 
        direction TB
        LocalDev["Local Dev Machine\nnpm run dev (localhost:3000)"]:::dev
        LocalDev -->|runs| Browser
        LocalDev -.->|edits files| Repo
    end

    %% Connections: Browser <> Next.js (HTTP) and Browser <> Supabase (via supabaseClient)
    Browser -->|HTTPS requests| NextApp
    Browser -->|supabaseClient HTTPS calls| SupabaseAuth
    Browser -->|supabaseClient HTTPS CRUD| SupabaseDB
    Browser -.->|Realtime WS subscription| SupabaseRealtime
    SupabaseRealtime -->|emits DB change events| Browser

    %% NextApp <> Supabase (server-side calls / env)
    NextApp -->|server-side / edge env: uses SUPABASE_URL, SERVICE_KEY| SupabaseDB
    NextApp -->|server-side: auth management| SupabaseAuth

    %% CI/CD <> NextApp
    Vercel -->|deploys app| NextApp
    CDN -->|serves static files| Browser
    StaticPublic -->|bundled to CDN on deploy| CDN

    %% Auth flow details
    SignInComp -->|calls| SupabaseClient
    SupabaseClient -->|calls supabase.auth.signIn over HTTPS| SupabaseAuth
    SupabaseAuth -->|returns session/JWT| SupabaseClient
    SupabaseClient -->|provides session to| AuthProvider
    AuthProvider -->|context| ProtectedRoute
    ProtectedRoute -->|allows| AdminLanding
    ProtectedRoute -->|allows| EventsEditor
    ProtectedRoute -->|allows| NewsEditor

    %% Realtime subscription flow details
    EventsEditor -->|init subscribe via| SupabaseEvents
    NewsEditor -->|init subscribe via| SupabaseEvents
    SupabaseEvents -->|opens WS| SupabaseRealtime
    SupabaseRealtime -->|pushes row change events| SupabaseEvents
    SupabaseEvents -->|update UI state| EventsEditor
    SupabaseEvents -->|update UI state| NewsEditor

    %% Annotations / Environment
    Env["Env Vars: SUPABASE_URL, SUPABASE_ANON_KEY, SUPABASE_SERVICE_KEY"]:::note
    Env -.->|used by| SupabaseClient
    Env -.->|used by| NextApp

    %% Click Events (file mappings)
    click Home "https://github.com/abdul-0-muheed/sdc-admin/blob/main/src/app/page.js"
    click SignInPage "https://github.com/abdul-0-muheed/sdc-admin/blob/main/src/app/signin/page.js"
    click SignInComp "https://github.com/abdul-0-muheed/sdc-admin/blob/main/componets/SignIn.js"
    click Navbar "https://github.com/abdul-0-muheed/sdc-admin/blob/main/componets/navbar.js"
    click AdminLanding "https://github.com/abdul-0-muheed/sdc-admin/blob/main/src/app/admin/page.js"
    click EventsEditor "https://github.com/abdul-0-muheed/sdc-admin/blob/main/src/app/admin/content/events/page.js"
    click NewsEditor "https://github.com/abdul-0-muheed/sdc-admin/blob/main/src/app/admin/content/news/page.js"
    click Layout "https://github.com/abdul-0-muheed/sdc-admin/blob/main/src/app/layout.js"
    click StaticPublic "https://github.com/abdul-0-muheed/sdc-admin/tree/main/public/"
    click AuthProvider "https://github.com/abdul-0-muheed/sdc-admin/blob/main/componets/AuthProvider.js"
    click ProtectedRoute "https://github.com/abdul-0-muheed/sdc-admin/blob/main/componets/ProtectedRoute.js"
    click SupabaseClient "https://github.com/abdul-0-muheed/sdc-admin/blob/main/lib/supabaseClient.ts"
    click SupabaseEvents "https://github.com/abdul-0-muheed/sdc-admin/blob/main/lib/supabaseEvents.js"
    click NextConfig "https://github.com/abdul-0-muheed/sdc-admin/blob/main/next.config.mjs"
    click NextConfig "https://github.com/abdul-0-muheed/sdc-admin/blob/main/package.json"
    click NextConfig "https://github.com/abdul-0-muheed/sdc-admin/blob/main/README.md"

    %% Styles / classes
    classDef browser fill:#D0E8FF,stroke:#2B6CB0,stroke-width:2px;
    classDef next fill:#E6F9E6,stroke:#20A020,stroke-width:2px;
    classDef component fill:#FFF4E6,stroke:#E07B00,stroke-width:1.5px;
    classDef lib fill:#F0F5FF,stroke:#4C51BF,stroke-width:1.5px;
    classDef db fill:#F7E6FF,stroke:#8B5CF6,stroke-width:2px,stroke-dasharray: 5 2;
    classDef external fill:#F3E8FF,stroke:#7C3AED,stroke-width:2px;
    classDef infra fill:#F2F4F7,stroke:#6B7280,stroke-width:1.5px;
    classDef dev fill:#FEE2E2,stroke:#DC2626,stroke-width:1.5px,stroke-dasharray: 4 2;
    classDef ci fill:#E6EEF8,stroke:#374151,stroke-width:1.5px;
    classDef page fill:#E8FDF5,stroke:#059669,stroke-width:1.2px;
    classDef file fill:#FEF3C7,stroke:#D97706,stroke-width:1.2px;
    classDef note fill:#FFF7ED,stroke:#92400E,stroke-width:1px;

    class Browser browser
    class Home,SignInPage,AdminLanding,EventsEditor,NewsEditor page
    class SignInComp,Navbar,ProtectedRoute,AuthProvider component
    class NextApp next
    class Layout,NextConfig file
    class SupabaseClient,SupabaseEvents lib
    class SupabaseDB db
    class SupabaseAuth,SupabaseRealtime,SupabaseStorage external
    class StaticPublic,CDN infra
    class Dev,Repo,LocalDev dev
    class CI,Vercel ci
    class Env note
```
