# rqkeebhasan-png/efootball- architecture

> Architecture diagram of the GitHub repository rqkeebhasan-png/efootball-, 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/rqkeebhasan-png/efootball-
- Repository: https://github.com/rqkeebhasan-png/efootball-

## Overview

1. **Overall shape**
   - This is a **single-page React app** for eFootball tournament operations.
   - The frontend is the primary application; the backend is **Supabase** providing **Auth, Postgres, Storage, and Realtime**.
   - There is no custom server in the repo; all business data flows directly from the UI to Supabase.

2. **Application shell and routing**
   - `src/main.tsx` and `src/App.tsx` define the app bootstrap and route composition.
   - `src/components/layout/AppLayout.tsx` and `Navbar.tsx` provide the shared shell for authenticated areas.
   - `ProtectedRoute.tsx` enforces route-level access control, likely based on login state and user role.

3. **Role-based surface area**
   - The app is split into two major user domains: **player** and **admin**.
   - Player pages live under `src/pages/player/` and cover dashboard, tournaments, matches, profile, public profile, and search.
   - Admin pages live under `src/pages/admin/` and cover dashboard, tournament CRUD, player management, reviews/disputes, and tournament details.

4. **Authentication and session state**
   - `src/hooks/useAuth.ts` and `src/store/authStore.ts` form the auth boundary.
   - Supabase Auth is the source of truth for login/session.
   - The auth store likely mirrors the current user, profile, and role so the UI can render player vs admin views and gate protected routes.

5. **Tournament domain flow**
   - `useTournament.ts` feeds tournament-related pages and components such as `TournamentCard`, `BracketView`, and `AdminTournamentDetailPage`.
   - The tournament flow includes listing tournaments, viewing bracket state, creating/editing tournaments, and navigating into a specific tournament’s matches and bracket.
   - `src/utils/bracket.ts` is an important domain utility: it encapsulates single-elimination bracket generation and seeding logic.

6. **Match lifecycle**
   - `useMatch.ts` connects match pages and match components such as `MatchCard` and `SubmitResultModal`.
   - The main match flow is: players view assigned matches, submit a result with proof, and then the system either auto-confirms or sends the result into a review path.
   - The 1-hour result window and default-win behavior are part of the domain rules surfaced in the UI and enforced through backend data/state.

7. **Dispute and moderation path**
   - Admin review pages (`AdminReviewsPage.tsx`) indicate a moderation queue for disputed or unconfirmed match outcomes.
   - This creates a separate control flow from ordinary player interactions: player submissions move into either confirmation or referee review.
   - `AdminPlayersPage.tsx` and `SuspendedPage.tsx` show that account status is also an administrative concern.

8. **Realtime notifications**
   - `src/store/notificationStore.ts` and `src/components/player/NotificationPanel.tsx` form the in-app notification subsystem.
   - README indicates Supabase Realtime drives updates, so notifications are likely pushed from backend changes into the UI without polling.
   - This subsystem is separate from core routing and is used to surface match updates, confirmations, and admin actions.

9. **Supabase data boundary**
   - `src/lib/supabase.ts` is the central client boundary for all backend access.
   - The app depends on Supabase for:
     - **Auth**: login, register, password reset
     - **Database**: tournaments, profiles, matches, reviews, roles
     - **Storage**: screenshot uploads for match proofs
     - **Realtime**: notification delivery and live status changes
   - The migrations under `supabase/migrations/` define the persistence model and security rules.

10. **Security and authorization model**
    - `002_rls_policies.sql` is architecturally important because it enforces **row-level security** in the database, not just in the UI.
    - Role checks are therefore layered:
      - route/UI gating in the frontend
      - RLS policies in Supabase
    - This matters for diagramming because the trust boundary is not in the client; Supabase is the enforcement point.

11. **File upload and media handling**
    - `003_storage_buckets.sql` shows a dedicated storage layer for screenshot evidence.
    - Match result submission therefore has a two-part write path: structured data into the database and proof media into storage.
    - The storage bucket is part of the app’s core match verification workflow, not an optional add-on.

12. **UI component architecture**
    - `src/components/ui/` contains the reusable design system primitives: buttons, cards, forms, inputs, etc.
    - Feature components are grouped by domain (`layout`, `tournament`, `match`, `player`) rather than by technical layer.
    - This keeps tournament and match flows composed from shared primitives without duplicating UI scaffolding.

13. **Data and formatting helpers**
    - `src/types/` centralizes the domain model shape used across hooks, pages, and components.
    - `src/utils/format.ts` handles presentation formatting, while `bracket.ts` handles tournament logic.
    - These utilities sit between raw Supabase data and rendered UI, translating backend records into domain-aware view models.

14. **Delivery and runtime**
    - The app is built with **Vite**, styled with **Tailwind CSS**, and hosted on **GitHub Pages**.
    - `.github/workflows/deploy.yml` provides CI/CD that builds and deploys the static frontend on pushes to `main`.
    - Environment configuration is client-side only via `VITE_SUPABASE_URL` and `VITE_SUPABASE_ANON_KEY`, which is consistent with a static hosting architecture.

15. **How to draw the architecture**
    - A good diagram would show:
      - Users entering the **React/Vite SPA**
      - The SPA routing into **player** and **admin** areas
      - Frontend hooks/stores calling the **Supabase client**
      - Supabase splitting into **Auth**, **Postgres with RLS**, **Storage**, and **Realtime**
      - A separate **GitHub Actions → GitHub Pages** deployment path for the frontend build
    - The main boundary is between the client app and Supabase; most business behavior is implemented as frontend domain logic plus backend data/security rules.

Main entry points: [`src/App.tsx`](https://github.com/rqkeebhasan-png/efootball-/blob/main/src/App.tsx) (App), [`src/lib/supabase.ts`](https://github.com/rqkeebhasan-png/efootball-/blob/main/src/lib/supabase.ts) (Supabase client), [`src/pages/player`](https://github.com/rqkeebhasan-png/efootball-/tree/main/src/pages/player) (Player area), [`src/hooks/useMatch.ts`](https://github.com/rqkeebhasan-png/efootball-/blob/main/src/hooks/useMatch.ts) (Match flow)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend app"]
  node_main["main<br/>bootstrap<br/>[main.tsx]"]
  node_app["App<br/>router shell<br/>[App.tsx]"]
  node_layout["App shell<br/>layout<br/>[AppLayout.tsx]"]
  node_protected{{"Protected route<br/>access gate<br/>[ProtectedRoute.tsx]"}}
  node_authhook["Auth hook<br/>session hook<br/>[useAuth.ts]"]
  node_authstore["Auth store<br/>state store<br/>[authStore.ts]"]
  node_player["Player area<br/>player routes"]
  node_admin["Admin area<br/>admin routes"]
  node_tourney["Tournament flow<br/>domain hook<br/>[useTournament.ts]"]
  node_match["Match flow<br/>domain hook<br/>[useMatch.ts]"]
  node_notif["Notifications<br/>realtime UI"]
  node_ui["UI kit<br/>design system"]
  node_utils["Domain utils<br/>helpers"]
end

subgraph group_supabase["Supabase backend"]
  node_supabaseclient["Supabase client<br/>backend boundary<br/>[supabase.ts]"]
  node_auth[("Supabase Auth<br/>identity service")]
  node_db[("Postgres + RLS<br/>data layer")]
  node_storage[("Storage bucket<br/>media store")]
  node_realtime["Realtime<br/>event stream"]
end

subgraph group_delivery["Delivery"]
  node_deploy["Deploy workflow<br/>ci/cd<br/>[deploy.yml]"]
end

node_main -->|"mounts"| node_app
node_app -->|"uses"| node_layout
node_app -->|"guards"| node_protected
node_app -->|"routes"| node_player
node_app -->|"routes"| node_admin
node_protected -->|"checks session"| node_authhook
node_authhook -->|"syncs"| node_authstore
node_authhook -->|"calls"| node_supabaseclient
node_player -->|"loads"| node_tourney
node_player -->|"loads"| node_match
node_player -->|"shows"| node_notif
node_admin -->|"manages"| node_tourney
node_admin -->|"reviews"| node_match
node_match -->|"uploads proof"| node_storage
node_match -->|"writes results"| node_db
node_tourney -->|"reads/writes"| node_db
node_notif -->|"subscribes"| node_realtime
node_supabaseclient -->|"auth"| node_auth
node_supabaseclient -->|"data"| node_db
node_supabaseclient -->|"media"| node_storage
node_supabaseclient -->|"events"| node_realtime
node_db -.->|"references roles"| node_auth
node_utils -->|"supports"| node_tourney
node_utils -->|"formats"| node_player
node_deploy -->|"builds"| node_main

click node_main "https://github.com/rqkeebhasan-png/efootball-/blob/main/src/main.tsx"
click node_app "https://github.com/rqkeebhasan-png/efootball-/blob/main/src/App.tsx"
click node_layout "https://github.com/rqkeebhasan-png/efootball-/blob/main/src/components/layout/AppLayout.tsx"
click node_protected "https://github.com/rqkeebhasan-png/efootball-/blob/main/src/components/layout/ProtectedRoute.tsx"
click node_authhook "https://github.com/rqkeebhasan-png/efootball-/blob/main/src/hooks/useAuth.ts"
click node_authstore "https://github.com/rqkeebhasan-png/efootball-/blob/main/src/store/authStore.ts"
click node_player "https://github.com/rqkeebhasan-png/efootball-/tree/main/src/pages/player"
click node_admin "https://github.com/rqkeebhasan-png/efootball-/tree/main/src/pages/admin"
click node_tourney "https://github.com/rqkeebhasan-png/efootball-/blob/main/src/hooks/useTournament.ts"
click node_match "https://github.com/rqkeebhasan-png/efootball-/blob/main/src/hooks/useMatch.ts"
click node_notif "https://github.com/rqkeebhasan-png/efootball-/blob/main/src/store/notificationStore.ts"
click node_ui "https://github.com/rqkeebhasan-png/efootball-/tree/main/src/components/ui"
click node_utils "https://github.com/rqkeebhasan-png/efootball-/tree/main/src/utils"
click node_supabaseclient "https://github.com/rqkeebhasan-png/efootball-/blob/main/src/lib/supabase.ts"
click node_db "https://github.com/rqkeebhasan-png/efootball-/tree/main/supabase/migrations"
click node_storage "https://github.com/rqkeebhasan-png/efootball-/blob/main/supabase/migrations/003_storage_buckets.sql"
click node_deploy "https://github.com/rqkeebhasan-png/efootball-/blob/main/.github/workflows/deploy.yml"

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_main,node_app,node_layout,node_protected,node_authhook,node_authstore,node_player,node_admin,node_tourney,node_match,node_notif,node_ui,node_utils toneBlue
class node_supabaseclient,node_auth,node_db,node_storage,node_realtime toneAmber
class node_deploy toneMint
```

## Components

### Frontend app

React/Vite SPA, feature routes, and shared UI.

- [main](https://github.com/rqkeebhasan-png/efootball-/blob/main/src/main.tsx): bootstrap · Vite entrypoint that mounts the React app. · `src/main.tsx`
- [App](https://github.com/rqkeebhasan-png/efootball-/blob/main/src/App.tsx): router shell · Top-level route composition for the single-page app. · `src/App.tsx`
- [App shell](https://github.com/rqkeebhasan-png/efootball-/blob/main/src/components/layout/AppLayout.tsx): layout · Shared authenticated layout and navigation chrome. · `src/components/layout/AppLayout.tsx`
- [Protected route](https://github.com/rqkeebhasan-png/efootball-/blob/main/src/components/layout/ProtectedRoute.tsx): access gate · Route guard for login and role-based access. · `src/components/layout/ProtectedRoute.tsx`
- [Auth hook](https://github.com/rqkeebhasan-png/efootball-/blob/main/src/hooks/useAuth.ts): session hook · Connects UI state to Supabase auth session and profile. · `src/hooks/useAuth.ts`
- [Auth store](https://github.com/rqkeebhasan-png/efootball-/blob/main/src/store/authStore.ts): state store · Mirrors current user, profile, and role for the UI. · `src/store/authStore.ts`
- [Player area](https://github.com/rqkeebhasan-png/efootball-/tree/main/src/pages/player): player routes · Player-facing tournament, match, profile, and search pages. · `src/pages/player`
- [Admin area](https://github.com/rqkeebhasan-png/efootball-/tree/main/src/pages/admin): admin routes · Operations surface for tournaments, players, and reviews. · `src/pages/admin`
- [Tournament flow](https://github.com/rqkeebhasan-png/efootball-/blob/main/src/hooks/useTournament.ts): domain hook · Fetches and coordinates tournament listing and detail state. · `src/hooks/useTournament.ts`
- [Match flow](https://github.com/rqkeebhasan-png/efootball-/blob/main/src/hooks/useMatch.ts): domain hook · Drives assigned matches, result submission, and review paths. · `src/hooks/useMatch.ts`
- [Notifications](https://github.com/rqkeebhasan-png/efootball-/blob/main/src/store/notificationStore.ts): realtime UI · In-app notification panel fed by live backend updates. · `src/store/notificationStore.ts`
- [UI kit](https://github.com/rqkeebhasan-png/efootball-/tree/main/src/components/ui): design system · Reusable buttons, cards, forms, and inputs. · `src/components/ui`
- [Domain utils](https://github.com/rqkeebhasan-png/efootball-/tree/main/src/utils): helpers · Bracket generation and display formatting helpers. · `src/utils`

### Supabase backend

Managed auth, database, storage, realtime, and security rules.

- [Supabase client](https://github.com/rqkeebhasan-png/efootball-/blob/main/src/lib/supabase.ts): backend boundary · Central client used by the frontend to reach Supabase services. · `src/lib/supabase.ts`
- **Supabase Auth**: identity service · Login, registration, password reset, and session source of truth.
- [Postgres + RLS](https://github.com/rqkeebhasan-png/efootball-/tree/main/supabase/migrations): data layer · Persistent tournament, profile, match, review, and role data with row-level security. · `supabase/migrations`
- [Storage bucket](https://github.com/rqkeebhasan-png/efootball-/blob/main/supabase/migrations/003_storage_buckets.sql): media store · Screenshot evidence uploads for match proof. · `supabase/migrations/003_storage_buckets.sql`
- **Realtime**: event stream · Pushes live updates for match status and notifications.

### Delivery

Static build and deployment pipeline for the frontend.

- [Deploy workflow](https://github.com/rqkeebhasan-png/efootball-/blob/main/.github/workflows/deploy.yml): ci/cd · Builds and publishes the static frontend to GitHub Pages. · `.github/workflows/deploy.yml`

## Connections

- main → App: mounts · Bootstraps the SPA root.
- App → App shell: uses · Wraps authenticated views in the shared shell.
- App → Protected route: guards · Applies route access control.
- App → Player area: routes · Sends logged-in players to player pages.
- App → Admin area: routes · Sends admins to operations pages.
- Protected route → Auth hook: checks session · Reads login and role state for gating.
- Auth hook → Auth store: syncs · Keeps current user and role in local UI state.
- Auth hook → Supabase client: calls · Uses the shared client for auth and profile access.
- Player area → Tournament flow: loads · Player views depend on tournament data.
- Player area → Match flow: loads · Player views depend on match data and submissions.
- Player area → Notifications: shows · Surfaces live notifications in the player surface.
- Admin area → Tournament flow: manages · Admin CRUD and detail pages use tournament state.
- Admin area → Match flow: reviews · Moderation flows inspect submitted match outcomes.
- Match flow → Storage bucket: uploads proof · Sends screenshot evidence to storage.
- Match flow → Postgres + RLS: writes results · Persists results, confirmations, and review records.
- Tournament flow → Postgres + RLS: reads/writes · Uses persisted tournament and bracket data.
- Notifications → Realtime: subscribes · Receives pushed updates from backend events.
- Supabase client → Supabase Auth: auth · Routes sign-in and session calls to Supabase Auth.
- Supabase client → Postgres + RLS: data · Reads and writes application records.
- Supabase client → Storage bucket: media · Uploads and retrieves match proof files.
- Supabase client → Realtime: events · Consumes live status updates.
- Postgres + RLS → Supabase Auth: references roles · Database policies and user metadata depend on identity.
- Domain utils → Tournament flow: supports · Bracket logic feeds tournament pages and components.
- Domain utils → Player area: formats · Presentation helpers support player-facing views.
- Deploy workflow → main: builds · CI builds the Vite app from the frontend entrypoint.