# dscubed/dscubed-website architecture

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

- Interactive diagram: https://gitdiagram.com/dscubed/dscubed-website
- Repository: https://github.com/dscubed/dscubed-website

## Overview

##### Project type and purpose
- This is a full-stack web application built with Next.js (React) that serves both static and server-rendered pages.
- It includes an admin interface for creating, editing, and deleting content, public pages for events, competitions, committee listings, sponsors, and integration with Supabase for authentication and data storage.

##### File structure
- Top-level entry points:
– next.config.js, middleware.ts, package.json – core Next.js configuration
– app/ folder – Next.js 13+ App Router with file-based routing and server/client components
– public/ – static assets (images, PDFs, logos) served via CDN
– utils/supabase/ – Supabase client, server, and middleware wrappers
- Core directories in app/:
– app/page.tsx – home page
– app/[feature]/page.tsx – feature pages (events, competitions, sponsors, map, study, QR, committee)
– app/admin/ – authenticated admin UI routes (login, create, edit)
– app/auth/ – OAuth redirect route
– app/components/ – React UI components organized by domain (home, events, competitions, committee, admin, sponsors, etc.)
- API/Backend footprints:
– app/auth/callback/route.ts – Next.js API route for OAuth callbacks
– utils/supabase/server.ts – server-side Supabase client
– utils/supabase/client.ts – client-side Supabase instance
– middleware.ts – route protection and session handling via Supabase middleware

##### README for additional insights
- Uses Supabase for authentication (including Google OAuth) and likely for data persistence (events, competitions, committee members, sponsors, etc.).
- Requires environment variables (.env.local) and callback URL configuration in Supabase.
- Supports local dev over HTTP/HTTPS.

a. Main components
1. Next.js Application
- App Router server (Node.js)
- React components (app/components/)
- API routes (e.g., auth callbacks)
2. Supabase
- Authentication service (OAuth, session management)
- Database (tables for events, competitions, members, sponsors)
3. User’s Browser
- Static assets from public/
- SSR or SSG pages delivered by Next.js
4. External services
- Google OAuth
- (Optional) CDN or hosting platform (e.g., Vercel)
b. Relationships and data flows
- Browser → Next.js server: requests pages or API endpoints
- Next.js server → Supabase server:
– Reads/writes database via server.ts
– Verifies/authenticates sessions via middleware
- Next.js client components → Supabase client: real-time data or client-side calls (if used)
- OAuth callback flow:
1. User clicks “Sign in” → redirect to Google
2. Google → Next.js auth/callback/route → Supabase session creation → redirect back to admin UI
c. Architectural patterns and design principles
- File-based routing (Next.js App Router) separates pages and API routes
- Server-side rendering (SSR) and static site generation (SSG) for public pages
- Component modularization by feature/domain (atomic/component grouping)
- Middleware for cross-cutting concerns (auth, redirects)
- Clear separation of client vs server code (client.ts vs server.ts in util/supabase)
d. Key technologies/frameworks
- Next.js 13+ App Router
- React with TypeScript
- Tailwind CSS (tailwind.config.js, postcss.config.js)
- Supabase (Auth + Postgres)
- Node.js for server runtime
- Vercel (implied) or similar for deployment

##### Detail without overthinking
- Break the system into at least these components:
– Client (Browser + React components)
– Next.js Server (routing layer, SSR/SSG pages, API routes)
– Authentication (middleware, OAuth callback)
– Database (Supabase)
– External (Google OAuth, Hosting/CDN)
- Critical data paths (page requests, API calls, auth flows).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Browser
    Browser["User Browser"]:::frontend

    %% Vercel Hosting and CDN
    subgraph "Vercel Hosting / CDN"
        CDN["Public Assets (public/)"]:::cdn
        click CDN "https://github.com/dscubed/dscubed-website/tree/main/public/"
        NextServer["Next.js Server"]:::backend
    end

    %% Next.js Server Configuration & Middleware
    subgraph "Next.js Configuration"
        ConfigFiles["Config Files"]:::config
        click ConfigFiles "https://github.com/dscubed/dscubed-website/blob/main/next.config.js"
        click ConfigFiles "https://github.com/dscubed/dscubed-website/blob/main/postcss.config.js"
        click ConfigFiles "https://github.com/dscubed/dscubed-website/blob/main/tailwind.config.js"
        MiddlewareRoot["middleware.ts"]:::backend
        click MiddlewareRoot "https://github.com/dscubed/dscubed-website/blob/main/middleware.ts"
    end

    %% Supabase Utils
    subgraph "Supabase Utilities"
        SupClient["Client-side Supabase"]:::backend
        click SupClient "https://github.com/dscubed/dscubed-website/blob/main/utils/supabase/client.ts"
        SupServer["Server-side Supabase"]:::backend
        click SupServer "https://github.com/dscubed/dscubed-website/blob/main/utils/supabase/server.ts"
        SupMiddleware["Supabase Middleware"]:::backend
        click SupMiddleware "https://github.com/dscubed/dscubed-website/blob/main/utils/supabase/middleware.ts"
    end

    %% App Router
    subgraph "Next.js App Router"
        Layout["app/layout.tsx"]:::frontend
        click Layout "https://github.com/dscubed/dscubed-website/blob/main/app/layout.tsx"
        GlobalError["app/global-error.tsx"]:::frontend
        click GlobalError "https://github.com/dscubed/dscubed-website/blob/main/app/global-error.tsx"

        %% Public Pages
        subgraph "Public Pages" 
            Home["Home Page"]:::frontend
            click Home "https://github.com/dscubed/dscubed-website/blob/main/app/page.tsx"
            Events["Events Page"]:::frontend
            click Events "https://github.com/dscubed/dscubed-website/blob/main/app/events/page.tsx"
            Competitions["Competitions Page"]:::frontend
            click Competitions "https://github.com/dscubed/dscubed-website/blob/main/app/competitions/page.tsx"
            Sponsors["Sponsors Page"]:::frontend
            click Sponsors "https://github.com/dscubed/dscubed-website/blob/main/app/sponsors/page.tsx"
            Committee24["Committee 2024"]:::frontend
            click Committee24 "https://github.com/dscubed/dscubed-website/blob/main/app/committee-2024/page.tsx"
            Committee25["Committee 2025"]:::frontend
            click Committee25 "https://github.com/dscubed/dscubed-website/blob/main/app/committee-2025/page.tsx"
            MapPage["Map Page"]:::frontend
            click MapPage "https://github.com/dscubed/dscubed-website/blob/main/app/map/page.tsx"
            Study["Study Page"]:::frontend
            click Study "https://github.com/dscubed/dscubed-website/blob/main/app/study/page.tsx"
            QRInstagram["QR Instagram Page"]:::frontend
            click QRInstagram "https://github.com/dscubed/dscubed-website/blob/main/app/qr/instagram/page.tsx"
        end

        %% Admin Pages
        subgraph "Admin Interface (Protected)"
            AdminLayout["Admin Layout"]:::frontend
            click AdminLayout "https://github.com/dscubed/dscubed-website/blob/main/app/admin/layout.tsx"
            AdminHome["Admin Home"]:::frontend
            click AdminHome "https://github.com/dscubed/dscubed-website/blob/main/app/admin/page.tsx"
            AdminLogin["Admin Login"]:::frontend
            click AdminLogin "https://github.com/dscubed/dscubed-website/blob/main/app/admin/login/page.tsx"
            AdminCreate["Admin Create"]:::frontend
            click AdminCreate "https://github.com/dscubed/dscubed-website/blob/main/app/admin/create/page.tsx"
            AdminEdit["Admin Edit"]:::frontend
            click AdminEdit "https://github.com/dscubed/dscubed-website/blob/main/app/admin/edit/[id]/page.tsx"
        end

        %% API Routes
        AuthCallback["OAuth Callback Route"]:::backend
        click AuthCallback "https://github.com/dscubed/dscubed-website/blob/main/app/auth/callback/route.ts"
    end

    %% External Services
    Google["Google OAuth"]:::external
    SupabaseAuth["Supabase Auth Service"]:::auth
    SupabaseDB["Supabase Database"]:::database

    %% Connections
    Browser --> CDN
    CDN --> NextServer
    NextServer --> ConfigFiles
    NextServer --> MiddlewareRoot
    NextServer --> SupServer
    NextServer --> SupClient
    NextServer --> SupMiddleware
    NextServer --> SupabaseAuth
    NextServer --> SupabaseDB

    Browser -->|"Requests Public Pages"| Home
    Browser -->|"Requests Public Pages"| Events
    Browser -->|"Requests Public Pages"| Competitions
    Browser -->|"Requests Public Pages"| Sponsors
    Browser -->|"Requests Public Pages"| Committee24
    Browser -->|"Requests Public Pages"| Committee25
    Browser -->|"Requests Public Pages"| MapPage
    Browser -->|"Requests Public Pages"| Study
    Browser -->|"Requests Public Pages"| QRInstagram

    Browser -->|"Access Admin"| AdminLogin
    AdminLogin -->|"After Auth"| AdminHome
    AdminHome -->|"Perform CRUD"| AdminCreate
    AdminHome -->|"Perform CRUD"| AdminEdit

    Browser -->|"Initiate OAuth"| Google
    Google --> AuthCallback
    AuthCallback --> SupabaseAuth
    SupabaseAuth -->|"Create Session"| SupMiddleware
    SupMiddleware --> AdminHome

    NextServer -->|"Reads/Writes"| SupabaseDB

    %% Styles
    classDef frontend fill:#D6EAF8,stroke:#1B4F72,stroke-width:2px;
    classDef backend fill:#E8DAEF,stroke:#4A235A,stroke-width:2px;
    classDef external fill:#FDEDEC,stroke:#922B21,stroke-width:2px;
    classDef auth fill:#FEF9E7,stroke:#B9770E,stroke-width:2px;
    classDef database fill:#E9F7EF,stroke:#145A32,stroke-width:2px;
    classDef config fill:#FCF3CF,stroke:#7D6608,stroke-width:2px;
    classDef cdn fill:#F0F3F4,stroke:#566573,stroke-width:2px;
```
