# jakobwiley/cd-golf-league architecture

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

- Interactive diagram: https://gitdiagram.com/jakobwiley/cd-golf-league
- Repository: https://github.com/jakobwiley/cd-golf-league

## Overview

##### Project type and purpose
- This is a full-stack web application built with Next.js (App Router) for managing a golf league: schedules, scores, real-time updates, standings, and admin.
- It uses a serverless deployment model (Vercel), a Postgres database (Supabase), Prisma/Supabase ORM, and integrates with an external GHIN service for handicap data.

##### File structure
- Top-level “app/” contains Next.js routes: UI pages (`.tsx`), API endpoints (`app/api/*`), hooks, components, lib utilities, and middleware.
- “lib/” and “app/lib/” hold shared utility code: database client wrappers, GHIN adapter, scoring logic.
- “scripts/” drives build, deployment, maintenance, and data-migration tasks.
- “supabase/” holds database migrations.
- Root has configuration: `next.config.js`, `vercel.json`, `.env.*` examples, TypeScript and Jest config.

##### README for additional insights
- Confirms Prisma ORM (or Supabase) models: Team, Player, Match, MatchScore, MatchPoints, MatchPlayer.
- Real-time updates via Socket.io or Supabase Realtime.
- Admin cron routes for scheduled data fixes or migrations.
- Development uses mock data file; production uses real Postgres.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Presentation Layer
    subgraph "Presentation Layer"
        Browser["Browser / Client"]:::frontend
        subgraph "Next.js UI"
            NextUI["Next.js UI Layer"]:::frontend
            ReactComp["React Components Library"]:::frontend
        end
    end

    %% Serverless Application Layer
    subgraph "Serverless Application Layer"
        subgraph "API Layer"
            API["Next.js API Layer"]:::backend
        end
        subgraph "Real-time Service"
            WSRoute["WebSocket Service Endpoint"]:::backend
            WSHook["useWebSocket Hook"]:::frontend
            SocketLib["socketClient.ts"]:::backend
            RealtimeLib["realtime-client.js"]:::backend
        end
        subgraph "Domain Logic & Utilities"
            Scoring["Scoring Functions"]:::backend
            HandicapAppLib["App Handicap Utilities"]:::backend
            HandicapLib["Shared Handicap Utilities"]:::backend
            GHINApp["App GHIN Adapter"]:::backend
            GHINLib["Shared GHIN Adapter"]:::backend
            DbClient["Supabase Client Wrapper"]:::backend
            ApiConfig["API Configuration"]:::backend
            ApiUtils["API Utilities"]:::backend
            MockStorage["Mock Storage Abstraction"]:::backend
            MockData["Mock Data JSON"]:::backend
        end
        subgraph "Admin & Cron Jobs"
            AdminAPI["Admin API Endpoints"]:::backend
            CronAPI["Scheduled Cron Endpoints"]:::backend
        end
    end

    %% Data Layer
    DB["Supabase Postgres"]:::db
    Migrations["Supabase Migrations"]:::db

    %% External Services
    GHINService["GHIN External API"]:::external

    %% Dev/Ops Layer
    Vercel["Vercel Platform"]:::devops
    CI["GitHub Actions (CI/CD)"]:::devops
    ScriptsDir["Dev/Ops Scripts"]:::devops
    ConfigFiles["Configuration & Environment"]:::devops

    %% Relationships
    Browser -->|"HTTP Requests"| NextUI
    Browser -->|"WebSocket"| WSRoute
    NextUI -->|"calls REST"| API
    API -->|"reads/writes"| DB
    API -->|"calls"| GHINService
    Scoring --> DB
    Scoring --> GHINService
    WSRoute --> DB
    DB -->|"pub/sub"| WSRoute
    WSHook --> WSRoute
    DbClient --> DB
    ApiConfig --> API
    ApiUtils --> API
    GHINApp --> GHINService
    GHINLib --> GHINService
    HandicapAppLib --> DB
    HandicapLib --> DB
    MockStorage --> MockData
    AdminAPI --> DB
    CronAPI --> DB
    CI --> Vercel
    CI -->|"runs"| ScriptsDir
    Vercel --> API
    Vercel --> NextUI
    ConfigFiles --> Vercel
    ScriptsDir --> DB
    ScriptsDir --> Migrations
    Migrations --> DB

    %% Click Events
    click NextUI "https://github.com/jakobwiley/cd-golf-league/tree/main//app"
    click ReactComp "https://github.com/jakobwiley/cd-golf-league/tree/main//app/components"
    click API "https://github.com/jakobwiley/cd-golf-league/tree/main//app/api"
    click WSRoute "https://github.com/jakobwiley/cd-golf-league/blob/main//app/api/scores/ws/route.ts"
    click WSHook "https://github.com/jakobwiley/cd-golf-league/blob/main//app/hooks/useWebSocket.ts"
    click SocketLib "https://github.com/jakobwiley/cd-golf-league/blob/main//lib/socketClient.ts"
    click RealtimeLib "https://github.com/jakobwiley/cd-golf-league/blob/main//lib/realtime-client.js"
    click DbClient "https://github.com/jakobwiley/cd-golf-league/blob/main//lib/supabase.ts"
    click ApiConfig "https://github.com/jakobwiley/cd-golf-league/blob/main//lib/apiConfig.ts"
    click ApiUtils "https://github.com/jakobwiley/cd-golf-league/blob/main//lib/api-utils.ts"
    click GHINApp "https://github.com/jakobwiley/cd-golf-league/blob/main//app/lib/ghin.ts"
    click GHINLib "https://github.com/jakobwiley/cd-golf-league/blob/main//lib/ghin.ts"
    click Scoring "https://github.com/jakobwiley/cd-golf-league/blob/main//app/lib/scoring.ts"
    click HandicapAppLib "https://github.com/jakobwiley/cd-golf-league/blob/main//app/lib/handicap.ts"
    click HandicapLib "https://github.com/jakobwiley/cd-golf-league/blob/main//lib/handicap.ts"
    click Migrations "https://github.com/jakobwiley/cd-golf-league/tree/main//supabase/migrations"
    click AdminAPI "https://github.com/jakobwiley/cd-golf-league/blob/main//app/api/admin/create-match-points-procedure/route.ts"
    click CronAPI "https://github.com/jakobwiley/cd-golf-league/blob/main//app/api/cron/ensure-match-points/route.ts"
    click MockData "https://github.com/jakobwiley/cd-golf-league/blob/main/.mock-data.json"
    click MockStorage "https://github.com/jakobwiley/cd-golf-league/blob/main//lib/mock-storage.ts"
    click ScriptsDir "https://github.com/jakobwiley/cd-golf-league/tree/main//scripts"
    click CI "https://github.com/jakobwiley/cd-golf-league/tree/main//.github/workflows"
    click ConfigFiles "https://github.com/jakobwiley/cd-golf-league/blob/main/next.config.js"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#0366D6,stroke-width:1px
    classDef backend fill:#DFFFD0,stroke:#228B22,stroke-width:1px
    classDef db fill:#FFE4B5,stroke:#FF8C00,stroke-width:1px
    classDef external fill:#E5D0FF,stroke:#800080,stroke-width:1px
    classDef devops fill:#F0F0F0,stroke:#708090,stroke-width:1px
```
