# dsc-darmstadt/dscdarmstadt architecture

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

- Interactive diagram: https://gitdiagram.com/dsc-darmstadt/dscdarmstadt
- Repository: https://github.com/dsc-darmstadt/dscdarmstadt

## Overview

##### Project Type and Purpose
- This is a full-stack web application built on Next.js (App Router).
- It serves a multi-language, SEO-optimized, PWA-enabled marketing and information site for the Developer Student Club Darmstadt.
- It delivers both static and dynamic content (SSR/SSG) and exposes a small API surface (Next.js API routes) backed by Supabase.

##### File-Structure Analysis
- Top-Level Config & Scripts
- ESLint, TypeScript, Tailwind, PostCSS, Wrangler, Cloudflare-Pages deployment files.
- `scripts/populate-db.js` for seeding Supabase.
- Public Assets
- Locale Messages
- `messages/`: JSON for `en` & `de`.
- Application Code (`src/`)
- `src/app/`: Next.js App Router – localized folder per `[locale]`, containing page routes under `/about`, `/events`, `/projects`, etc.
- `src/app/api/`: Next.js API routes mirroring pages (e.g., `GET /api/events`, `POST /api/contact`).
- `src/components/`: UI primitives (shadcn/ui), layout components (Navbar, Footer), feature-specific components.
- `src/i18n/`: next-intl setup & middleware for locale detection.
- `src/lib/`: environment variables, Supabase client, static fallback data, type definitions, utility converters.
- `src/middleware.ts`: enforces locale routing.

##### Key Insights from README
- Tech Stack: Next.js 14, TypeScript, Tailwind CSS, shadcn/ui, Framer Motion, next-intl.
- Deployment: Cloudflare Pages via `@cloudflare/next-on-pages` + Wrangler for preview.
- Data Persistence: Supabase (Postgres) accessed directly from API routes and client via `src/lib/supabase.ts`.
- Patterns:
- App Router with nested, localized layouts.
- Server vs. Client components.
- API layer co-located with frontend.

##### Diagramming the System
a. Main Components
- Browser / PWA Client
- CDN / Edge (Cloudflare Pages)
- Next.js App (App Router)
- SSR/SSG engine at edge
- Static asset server (public/)
- API Routes
- Supabase
- Localization Service (next-intl + JSON messages)
- External Services (optional: Analytics, Google Verification)
b. Relationships & Data Flows
1. User’s browser requests `https://{branch}.dscdarmstadt.pages.dev/{locale}/…`.
2. Cloudflare Pages CDN routes to Next.js edge functions.
3. Next.js App Router:
- For page requests:
- Checks for static prerendered HTML → caches or renders via SSR/SSG.
- Loads localized messages from `messages/{locale}.json`.
- For API requests (`/api/*`):
- Runs Node route handlers (e.g., events, projects, contact).
- These handlers call Supabase client in `src/lib/supabase.ts`.
4. Supabase responds with data (Postgres).
5. Next.js returns JSON (API) or HTML/JSON payload (SSR) to the client.
6. Browser renders components (client components for interactivity, lazy-loaded), or stores as PWA.
c. Architectural Patterns & Principles
- Monolithic Next.js application with co-located API routes (“Backend for Frontend” pattern).
- Separation of concerns:
- Presentation (components/)
- Routing & middleware (app/, middleware.ts)
- Data access (lib/supabase.ts, lib/data/*.ts)
- SSG/SSR hybrid model for performance & SEO.
- PWA support via manifest + service worker (implicit in Next.js).
- i18n at routing layer, JSON-based translation.
d. Key Technologies
- Next.js App Router (SSR/SSG, dynamic routes)
- Cloudflare Pages + Wrangler + next-on-pages
- Supabase (Postgres, REST/JS client)
- Tailwind CSS, shadcn/ui, Framer Motion
- next-intl for localization

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Side
    Browser("Browser"):::frontend
    SW["Service Worker / PWA Cache"]:::frontend
    Browser --> SW
    Browser --> CDN

    %% Edge / CDN
    subgraph "Cloudflare Edge"
        CDN("Cloudflare Pages CDN"):::infra
        NextEdge["Next.js Edge Functions"]:::backend
    end
    CDN --> NextEdge

    %% Next.js Runtime
    subgraph "Next.js Application"
        MW["Global Middleware"]:::backend
        click MW "https://github.com/dsc-darmstadt/dscdarmstadt/blob/cloudflare/src/middleware.ts"
        NextEdge --> MW

        subgraph "App Router & Pages"
            AR["App Router"]:::backend
            click AR "https://github.com/dsc-darmstadt/dscdarmstadt/tree/cloudflare/src/app/"
            AR --> Pages
            subgraph "Localized Routes"
                LOC_ROUTES["[locale] Pages"]:::backend
                click LOC_ROUTES "https://github.com/dsc-darmstadt/dscdarmstadt/tree/cloudflare/src/app/[locale]/"
                LOC_ROUTES --> AboutClient
                LOC_ROUTES --> AboutServer
                LOC_ROUTES --> EventsPage
                LOC_ROUTES --> EventsClient
                LOC_ROUTES --> EventDetails
                LOC_ROUTES --> ProjectsPage
                LOC_ROUTES --> ProjectsClient
            end
            click AboutClient "https://github.com/dsc-darmstadt/dscdarmstadt/blob/cloudflare/src/app/[locale]/about/about-client.tsx"
            click AboutServer "https://github.com/dsc-darmstadt/dscdarmstadt/blob/cloudflare/src/app/[locale]/about/page.tsx"
            click EventsPage "https://github.com/dsc-darmstadt/dscdarmstadt/blob/cloudflare/src/app/[locale]/events/page.tsx"
            click EventsClient "https://github.com/dsc-darmstadt/dscdarmstadt/blob/cloudflare/src/app/[locale]/events/events-client.tsx"
            click EventDetails "https://github.com/dsc-darmstadt/dscdarmstadt/blob/cloudflare/src/app/[locale]/events/[eventId]/page.tsx"
            click ProjectsPage "https://github.com/dsc-darmstadt/dscdarmstadt/blob/cloudflare/src/app/[locale]/projects/page.tsx"
            click ProjectsClient "https://github.com/dsc-darmstadt/dscdarmstadt/blob/cloudflare/src/app/[locale]/projects/projects-client.tsx"
        end
        MW --> AR

        subgraph "API Routes"
            API["Next.js API Routes"]:::backend
            click API "https://github.com/dsc-darmstadt/dscdarmstadt/tree/cloudflare/src/app/api/"
            EventsAPI["Events API"]:::backend
            click EventsAPI "https://github.com/dsc-darmstadt/dscdarmstadt/blob/cloudflare/src/app/api/events/route.ts"
            EventAPI["Event Detail API"]:::backend
            click EventAPI "https://github.com/dsc-darmstadt/dscdarmstadt/blob/cloudflare/src/app/api/events/[eventId]/route.ts"
            ProjectsAPI["Projects API"]:::backend
            click ProjectsAPI "https://github.com/dsc-darmstadt/dscdarmstadt/blob/cloudflare/src/app/api/projects/route.ts"
            ProjectAPI["Project Detail API"]:::backend
            click ProjectAPI "https://github.com/dsc-darmstadt/dscdarmstadt/blob/cloudflare/src/app/api/projects/[projectId]/route.ts"
            TeamAPI["Team API"]:::backend
            click TeamAPI "https://github.com/dsc-darmstadt/dscdarmstadt/blob/cloudflare/src/app/api/team/route.ts"
            TeamMemberAPI["Team Member API"]:::backend
            click TeamMemberAPI "https://github.com/dsc-darmstadt/dscdarmstadt/blob/cloudflare/src/app/api/team/[memberId]/route.ts"
            ContactAPI["Contact API"]:::backend
            click ContactAPI "https://github.com/dsc-darmstadt/dscdarmstadt/blob/cloudflare/src/app/api/contact/route.ts"
            API --> EventsAPI
            API --> EventAPI
            API --> ProjectsAPI
            API --> ProjectAPI
            API --> TeamAPI
            API --> TeamMemberAPI
            API --> ContactAPI
        end
        AR --> API

        subgraph "Localization Service"
            I18N["next-intl setup"]:::static
            click I18N "https://github.com/dsc-darmstadt/dscdarmstadt/blob/cloudflare/src/i18n/request.ts"
            Msgs["Locale JSON Messages"]:::static
            click Msgs "https://github.com/dsc-darmstadt/dscdarmstadt/blob/cloudflare/messages/en.json"
            click Msgs "https://github.com/dsc-darmstadt/dscdarmstadt/blob/cloudflare/messages/de.json"
            AR --> I18N
            I18N --> Msgs
        end

        subgraph "Static Assets"
            Public["public/"]:::static
            click Public "https://github.com/dsc-darmstadt/dscdarmstadt/tree/cloudflare/public/"
            Manifest["manifest.json"]:::static
            click Manifest "https://github.com/dsc-darmstadt/dscdarmstadt/blob/cloudflare/public/manifest.json"
            Robots["robots.txt"]:::static
            click Robots "https://github.com/dsc-darmstadt/dscdarmstadt/blob/cloudflare/public/robots.txt"
            Images["images/"]:::static
            click Images "https://github.com/dsc-darmstadt/dscdarmstadt/tree/cloudflare/public/images/"
            Public --> Manifest
            Public --> Robots
            Public --> Images
            AR --> Public
        end
    end

    %% Data & External
    subgraph "Data & External Services"
        Supabase["Supabase Postgres"]:::data
        click Supabase "https://github.com/dsc-darmstadt/dscdarmstadt/blob/cloudflare/src/lib/supabase.ts"
        Env["Environment Vars"]:::data
        click Env "https://github.com/dsc-darmstadt/dscdarmstadt/blob/cloudflare/src/lib/env.ts"
        FallbackData["Static Fallback Data"]:::data
        click FallbackData "https://github.com/dsc-darmstadt/dscdarmstadt/blob/cloudflare/src/lib/data/events.ts"
        click FallbackData "https://github.com/dsc-darmstadt/dscdarmstadt/blob/cloudflare/src/lib/data/projects.ts"
        click FallbackData "https://github.com/dsc-darmstadt/dscdarmstadt/blob/cloudflare/src/lib/data/team.ts"
        Utils["Utility Functions & Types"]:::data
        click Utils "https://github.com/dsc-darmstadt/dscdarmstadt/blob/cloudflare/src/lib/utils/converters.ts"
        click Utils "https://github.com/dsc-darmstadt/dscdarmstadt/blob/cloudflare/src/lib/utils/index.ts"
        click Utils "https://github.com/dsc-darmstadt/dscdarmstadt/blob/cloudflare/src/lib/types/index.ts"
        Metadata["Metadata & SEO Helpers"]:::data
        click Metadata "https://github.com/dsc-darmstadt/dscdarmstadt/blob/cloudflare/src/lib/metadata.ts"
        Supabase --> API
        API --> Supabase
        AR --> Supabase
        Browser --> ExtServices
        ExtServices["External Services\n(Analytics, Google)"]:::infra
    end

    %% Styles & Config
    subgraph "Global Config & Styles"
        Tailwind["tailwind.config.ts"]:::config
        click Tailwind "https://github.com/dsc-darmstadt/dscdarmstadt/blob/cloudflare/tailwind.config.ts"
        PostCSS["postcss.config.mjs"]:::config
        click PostCSS "https://github.com/dsc-darmstadt/dscdarmstadt/blob/cloudflare/postcss.config.mjs"
        GlobalsCSS["Global CSS"]:::config
        click GlobalsCSS "https://github.com/dsc-darmstadt/dscdarmstadt/blob/cloudflare/src/app/globals.css"
        NextConfig["next.config.mjs"]:::config
        click NextConfig "https://github.com/dsc-darmstadt/dscdarmstadt/blob/cloudflare/next.config.mjs"
        Wrangler["wrangler.jsonc"]:::config
        click Wrangler "https://github.com/dsc-darmstadt/dscdarmstadt/blob/cloudflare/wrangler.jsonc"
        SeedScript["populate-db.js"]:::config
        click SeedScript "https://github.com/dsc-darmstadt/dscdarmstadt/blob/cloudflare/scripts/populate-db.js"
    end

    %% Connections
    Browser -->|"requests"| CDN
    CDN -->|"executes"| NextEdge
    NextEdge --> MW
    Browser -->|"fetches assets"| Public
    Browser -->|"PWA offline"| SW

    %% Class Definitions
    classDef frontend fill:#D6EAF8,stroke:#1B4F72,color:#1B2631;
    classDef backend fill:#F9E79F,stroke:#B7950B,color:#784212;
    classDef static fill:#A9DFBF,stroke:#196F3D,color:#145A32;
    classDef data fill:#F5B7B1,stroke:#922B21,color:#641E16;
    classDef infra fill:#D2B4DE,stroke:#512E5F,color:#4A235A;
    classDef config fill:#AED6F1,stroke:#1A5276,color:#1B2631;
```
