# suvash23/football-chaos architecture

> Architecture diagram of the GitHub repository suvash23/football-chaos, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/suvash23/football-chaos
- Repository: https://github.com/suvash23/football-chaos

## Overview

1. **Overall shape**
   - This is a **single Next.js 15 App Router application** for a football-themed entertainment product.
   - The repo is mostly a **frontend shell + Supabase-backed data/auth layer**, with one explicit server API route and a set of static/domain pages.

2. **Application shell**
   - `src/app/layout.tsx` and `src/app/globals.css` define the shared app frame and global styling.
   - The shared chrome is split into reusable UI pieces like `src/components/navbar.tsx` and `src/components/footer.tsx`, which likely wrap most pages consistently.

3. **User-facing routes**
   - The main feature surfaces are separate routes under `src/app/*`:
     - `/` landing page
     - `/auth` authentication entry
     - `/profile` user profile
     - `/leaderboard` fan ranking view
     - `/predictions` match predictions
     - `/bingo` chaos bingo
     - `/var-simulator` image-based VAR simulator
     - `/excuses` excuse generator
     - `/groups` and `/bracket` tournament/group views
     - `/admin` administrative surface
   - Architecturally, these are independent route segments rather than a single SPA view, which makes the app easy to diagram as a set of feature modules around a shared shell.

4. **Server-side API boundary**
   - The only explicit API endpoint in the tree is `src/app/api/calculate-points/route.ts`.
   - This is the main server boundary for scoring/prediction logic: it likely receives match or prediction data, computes points, and returns results to the frontend.
   - This is important architecturally because it separates **interactive UI flows** from **trusted scoring logic**.

5. **Data and persistence layer**
   - The backend persistence layer is Supabase, wired through `src/lib/supabase.ts`.
   - The README says Supabase provides both **database and auth**, so the data flow is:
     - browser UI → Supabase auth/session
     - browser or server route → Supabase database tables
   - `database-schema.sql` defines the required tables, including profiles, matches, predictions, bingo cards, and leaderboard entries.

6. **Static domain data**
   - The app also relies on local JSON/TS assets in `src/lib/`:
     - `worldcup.json`
     - `teams_meta.json`
     - `data.ts`
   - These likely provide fixture/team metadata and seeded domain content, reducing dependence on live external sports APIs.
   - `supabase_matches_import.json` suggests a bulk import dataset for match records.

7. **Auth and user state**
   - `src/hooks/use-auth.ts` is the dedicated client-side auth hook.
   - This is the main boundary between anonymous vs authenticated behavior in the UI, and probably feeds profile/leaderboard/prediction screens with the current user/session.

8. **UI system**
   - The `src/components/ui/*` directory is a shadcn/ui-style component library wrapper.
   - These primitives (`button`, `card`, `dialog`, `tabs`, `sheet`, `select`, etc.) are the app’s presentation layer and are reused across the route pages rather than each page building its own controls.
   - `components.json`, Tailwind/PostCSS config, and `src/app/globals.css` indicate a design-system-oriented frontend.

9. **Feature composition**
   - The repo appears organized by **feature screens**, not by backend service.
   - Each page likely composes:
     - shared UI primitives
     - the auth hook/session state
     - local domain data from `src/lib`
     - Supabase reads/writes for persisted user data
   - That makes the architecture straightforward: most complexity stays in the client feature pages, while persistence stays centralized.

10. **Operational scripts and bootstrapping**
    - `scripts/seed.mjs` is the local data seeding path, likely used to populate Supabase or prepared datasets for the app.
    - `database-schema.sql` is the source of truth for database setup, which means repo onboarding includes a manual schema step rather than migrations in-app.

11. **Deployment/runtime**
    - `Dockerfile` and `vercel.json` show the app is designed to run in both containerized and Vercel hosting contexts.
    - The README explicitly targets **Vercel deployment** with environment variables for Supabase URL and anon key.
    - That means the runtime architecture is a standard Next.js frontend deployed serverlessly, with Supabase as the external managed backend.

12. **External dependencies that materially affect architecture**
    - **Supabase**: persistence and authentication backbone.
    - **Next.js App Router**: determines route structure, server/client split, and API route placement.
    - **Tailwind CSS v4 + shadcn/ui**: shapes the component architecture and styling strategy.

13. **What to draw in an architecture diagram**
    - A central **Next.js app** box containing route modules and UI components.
    - A separate **Supabase** box for auth + database.
    - One small **server API** boundary for `/api/calculate-points`.
    - A **local static data** box for JSON fixtures and seed data feeding match/team content.
    - Shared UI primitives as an internal library reused by all feature pages.

Main entry points: [`src/app/layout.tsx`](https://github.com/suvash23/football-chaos/blob/main/src/app/layout.tsx) (App Layout), [`src/lib/supabase.ts`](https://github.com/suvash23/football-chaos/blob/main/src/lib/supabase.ts) (Supabase), [`src/lib/data.ts`](https://github.com/suvash23/football-chaos/blob/main/src/lib/data.ts) (Domain Data), [`src/app/predictions/page.tsx`](https://github.com/suvash23/football-chaos/blob/main/src/app/predictions/page.tsx) (Predictions)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_shell["App Shell"]
  node_app_layout["App Layout<br/>Next.js shell<br/>[layout.tsx]"]
  node_globals_css["Global CSS<br/>styles<br/>[globals.css]"]
  node_navbar["Navbar<br/>shared chrome<br/>[navbar.tsx]"]
  node_footer["Footer<br/>shared chrome<br/>[footer.tsx]"]
end

subgraph group_routes["Feature Routes"]
  node_home_page["Home<br/>route page<br/>[page.tsx]"]
  node_auth_page["Auth<br/>route page<br/>[page.tsx]"]
  node_profile_page["Profile<br/>route page<br/>[page.tsx]"]
  node_leaderboard_page["Leaderboard<br/>route page<br/>[page.tsx]"]
  node_predictions_page["Predictions<br/>route page<br/>[page.tsx]"]
  node_bingo_page["Bingo<br/>route page<br/>[page.tsx]"]
  node_var_page["VAR Simulator<br/>route page<br/>[page.tsx]"]
  node_excuses_page["Excuses<br/>route page<br/>[page.tsx]"]
  node_groups_page["Groups<br/>route page<br/>[page.tsx]"]
  node_bracket_page["Bracket<br/>route page<br/>[page.tsx]"]
  node_admin_page["Admin<br/>route page<br/>[page.tsx]"]
end

subgraph group_services["Data & Services"]
  node_points_api["Points API<br/>server route<br/>[route.ts]"]
  node_supabase[("Supabase<br/>auth + database client<br/>[supabase.ts]")]
  node_domain_data["Domain Data<br/>fixtures<br/>[data.ts]"]
  node_schema_seed["Schema & Seed<br/>db bootstrap"]
end

subgraph group_ui["UI Kit"]
  node_ui_kit["UI Kit<br/>component library"]
end

node_app_layout -->|"loads"| node_globals_css
node_app_layout -->|"includes"| node_navbar
node_app_layout -->|"includes"| node_footer
node_app_layout -->|"wraps"| node_ui_kit
node_home_page -->|"uses"| node_app_layout
node_auth_page -->|"uses"| node_app_layout
node_profile_page -->|"uses"| node_app_layout
node_leaderboard_page -->|"uses"| node_app_layout
node_predictions_page -->|"uses"| node_app_layout
node_bingo_page -->|"uses"| node_app_layout
node_var_page -->|"uses"| node_app_layout
node_excuses_page -->|"uses"| node_app_layout
node_groups_page -->|"uses"| node_app_layout
node_bracket_page -->|"uses"| node_app_layout
node_admin_page -->|"uses"| node_app_layout
node_auth_page -->|"auth"| node_supabase
node_profile_page -->|"reads/writes"| node_supabase
node_leaderboard_page -->|"reads"| node_supabase
node_predictions_page -->|"reads/writes"| node_supabase
node_bingo_page -->|"reads/writes"| node_supabase
node_groups_page -->|"reads"| node_supabase
node_bracket_page -->|"reads"| node_supabase
node_admin_page -->|"admin data"| node_supabase
node_predictions_page -->|"scores"| node_points_api
node_points_api -->|"persists"| node_supabase
node_points_api -->|"uses"| node_domain_data
node_home_page -->|"uses"| node_domain_data
node_predictions_page -->|"uses"| node_domain_data
node_bingo_page -->|"uses"| node_domain_data
node_var_page -->|"uses"| node_domain_data
node_groups_page -->|"uses"| node_domain_data
node_bracket_page -->|"uses"| node_domain_data
node_schema_seed -->|"bootstraps"| node_supabase

click node_app_layout "https://github.com/suvash23/football-chaos/blob/main/src/app/layout.tsx"
click node_globals_css "https://github.com/suvash23/football-chaos/blob/main/src/app/globals.css"
click node_navbar "https://github.com/suvash23/football-chaos/blob/main/src/components/navbar.tsx"
click node_footer "https://github.com/suvash23/football-chaos/blob/main/src/components/footer.tsx"
click node_ui_kit "https://github.com/suvash23/football-chaos/tree/main/src/components/ui"
click node_home_page "https://github.com/suvash23/football-chaos/blob/main/src/app/page.tsx"
click node_auth_page "https://github.com/suvash23/football-chaos/blob/main/src/app/auth/page.tsx"
click node_profile_page "https://github.com/suvash23/football-chaos/blob/main/src/app/profile/page.tsx"
click node_leaderboard_page "https://github.com/suvash23/football-chaos/blob/main/src/app/leaderboard/page.tsx"
click node_predictions_page "https://github.com/suvash23/football-chaos/blob/main/src/app/predictions/page.tsx"
click node_bingo_page "https://github.com/suvash23/football-chaos/blob/main/src/app/bingo/page.tsx"
click node_var_page "https://github.com/suvash23/football-chaos/blob/main/src/app/var-simulator/page.tsx"
click node_excuses_page "https://github.com/suvash23/football-chaos/blob/main/src/app/excuses/page.tsx"
click node_groups_page "https://github.com/suvash23/football-chaos/blob/main/src/app/groups/page.tsx"
click node_bracket_page "https://github.com/suvash23/football-chaos/blob/main/src/app/bracket/page.tsx"
click node_admin_page "https://github.com/suvash23/football-chaos/blob/main/src/app/admin/page.tsx"
click node_points_api "https://github.com/suvash23/football-chaos/blob/main/src/app/api/calculate-points/route.ts"
click node_supabase "https://github.com/suvash23/football-chaos/blob/main/src/lib/supabase.ts"
click node_domain_data "https://github.com/suvash23/football-chaos/blob/main/src/lib/data.ts"
click node_schema_seed "https://github.com/suvash23/football-chaos/blob/main/database-schema.sql"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_app_layout,node_globals_css,node_navbar,node_footer toneBlue
class node_home_page,node_auth_page,node_profile_page,node_leaderboard_page,node_predictions_page,node_bingo_page,node_var_page,node_excuses_page,node_groups_page,node_bracket_page,node_admin_page toneAmber
class node_points_api,node_supabase,node_domain_data,node_schema_seed toneMint
class node_ui_kit toneRose
```

## Components

### App Shell

Shared frame and styling for the Next.js app

- [App Layout](https://github.com/suvash23/football-chaos/blob/main/src/app/layout.tsx): Next.js shell · Root application frame and shared providers · `src/app/layout.tsx`
- [Global CSS](https://github.com/suvash23/football-chaos/blob/main/src/app/globals.css): styles · App-wide styling foundation · `src/app/globals.css`
- [Navbar](https://github.com/suvash23/football-chaos/blob/main/src/components/navbar.tsx): shared chrome · Top-level navigation used across pages · `src/components/navbar.tsx`
- [Footer](https://github.com/suvash23/football-chaos/blob/main/src/components/footer.tsx): shared chrome · Shared footer for the app · `src/components/footer.tsx`

### Feature Routes

Independent App Router pages

- [Home](https://github.com/suvash23/football-chaos/blob/main/src/app/page.tsx): route page · Landing page · `src/app/page.tsx`
- [Auth](https://github.com/suvash23/football-chaos/blob/main/src/app/auth/page.tsx): route page · Authentication entry page · `src/app/auth/page.tsx`
- [Profile](https://github.com/suvash23/football-chaos/blob/main/src/app/profile/page.tsx): route page · User profile view · `src/app/profile/page.tsx`
- [Leaderboard](https://github.com/suvash23/football-chaos/blob/main/src/app/leaderboard/page.tsx): route page · Fan ranking and scoring view · `src/app/leaderboard/page.tsx`
- [Predictions](https://github.com/suvash23/football-chaos/blob/main/src/app/predictions/page.tsx): route page · Match prediction workflow · `src/app/predictions/page.tsx`
- [Bingo](https://github.com/suvash23/football-chaos/blob/main/src/app/bingo/page.tsx): route page · Chaos bingo game page · `src/app/bingo/page.tsx`
- [VAR Simulator](https://github.com/suvash23/football-chaos/blob/main/src/app/var-simulator/page.tsx): route page · Image-based VAR simulator · `src/app/var-simulator/page.tsx`
- [Excuses](https://github.com/suvash23/football-chaos/blob/main/src/app/excuses/page.tsx): route page · Excuse generator page · `src/app/excuses/page.tsx`
- [Groups](https://github.com/suvash23/football-chaos/blob/main/src/app/groups/page.tsx): route page · Tournament group view · `src/app/groups/page.tsx`
- [Bracket](https://github.com/suvash23/football-chaos/blob/main/src/app/bracket/page.tsx): route page · Tournament bracket view · `src/app/bracket/page.tsx`
- [Admin](https://github.com/suvash23/football-chaos/blob/main/src/app/admin/page.tsx): route page · Administrative surface · `src/app/admin/page.tsx`

### Data & Services

API, persistence, and local domain datasets

- [Points API](https://github.com/suvash23/football-chaos/blob/main/src/app/api/calculate-points/route.ts): server route · Trusted scoring endpoint for prediction results · `src/app/api/calculate-points/route.ts`
- [Supabase](https://github.com/suvash23/football-chaos/blob/main/src/lib/supabase.ts): auth + database client · Shared Supabase integration for auth and persistence · `src/lib/supabase.ts`
- [Domain Data](https://github.com/suvash23/football-chaos/blob/main/src/lib/data.ts): fixtures · Local tournament and team metadata used by features · `src/lib/data.ts`
- [Schema & Seed](https://github.com/suvash23/football-chaos/blob/main/database-schema.sql): db bootstrap · Database schema and seed/import inputs · `database-schema.sql`

### UI Kit

Reusable presentation components

- [UI Kit](https://github.com/suvash23/football-chaos/tree/main/src/components/ui): component library · Reusable shadcn-style UI primitives · `src/components/ui`

## Connections

- App Layout → Global CSS: loads · Global styling is applied through the root layout
- App Layout → Navbar: includes · Shared navigation is mounted in the app shell
- App Layout → Footer: includes · Shared footer is mounted in the app shell
- App Layout → UI Kit: wraps · Pages are composed from shared UI primitives
- Home → App Layout: uses · Landing page is rendered within the shared shell
- Auth → App Layout: uses · Auth page is rendered within the shared shell
- Profile → App Layout: uses · Profile page is rendered within the shared shell
- Leaderboard → App Layout: uses · Leaderboard page is rendered within the shared shell
- Predictions → App Layout: uses · Predictions page is rendered within the shared shell
- Bingo → App Layout: uses · Bingo page is rendered within the shared shell
- VAR Simulator → App Layout: uses · VAR simulator page is rendered within the shared shell
- Excuses → App Layout: uses · Excuses page is rendered within the shared shell
- Groups → App Layout: uses · Groups page is rendered within the shared shell
- Bracket → App Layout: uses · Bracket page is rendered within the shared shell
- Admin → App Layout: uses · Admin page is rendered within the shared shell
- Auth → Supabase: auth · Authentication flows through Supabase
- Profile → Supabase: reads/writes · Profile state is backed by Supabase data
- Leaderboard → Supabase: reads · Leaderboard data is sourced from Supabase
- Predictions → Supabase: reads/writes · Prediction state is persisted in Supabase
- Bingo → Supabase: reads/writes · Game progress can be stored in Supabase
- Groups → Supabase: reads · Tournament group data is backed by Supabase
- Bracket → Supabase: reads · Bracket state is backed by Supabase
- Admin → Supabase: admin data · Administrative actions operate on Supabase data
- Predictions → Points API: scores · Client prediction flow calls trusted scoring logic
- Points API → Supabase: persists · Scoring endpoint can read or update persisted match data
- Points API → Domain Data: uses · Scoring logic depends on local tournament data
- Home → Domain Data: uses · Landing content can be driven by local domain datasets
- Predictions → Domain Data: uses · Prediction UI uses team and fixture metadata
- Bingo → Domain Data: uses · Game content can be generated from local football data
- VAR Simulator → Domain Data: uses · Simulator content uses local tournament metadata
- Groups → Domain Data: uses · Group standings and fixtures rely on local tournament data
- Bracket → Domain Data: uses · Bracket rendering relies on local tournament data
- Schema & Seed → Supabase: bootstraps · Schema and seed assets define the persistent backend model