suvash23/football-chaos

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.