# rsayyed591/hacktrack-client architecture

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

- Interactive diagram: https://gitdiagram.com/rsayyed591/hacktrack-client
- Repository: https://github.com/rsayyed591/hacktrack-client

## Overview

1. **Repository scope**
   - This repo is the **HackTrack frontend client** only. It is a **React 18 + Vite** single-page app that talks to a separate **Node.js/Express backend** through a central API layer.
   - The frontend is designed around **role-based access control** for four user types: **Participant, Judge, Admin, Super Admin**.

2. **Application entry and runtime**
   - `src/main.jsx` bootstraps the app, and `index.html` is the Vite entry point.
   - `src/App.jsx` is the top-level composition point, likely wiring routes and global providers.
   - Styling is split between global CSS (`src/index.css`, `src/App.css`) and utility-based styling via **Tailwind CSS**.

3. **Core architectural pattern: role-based SPA**
   - The app is organized as a **workspace-per-role** model rather than a single generic dashboard.
   - Each role has its own page subtree under `src/pages/`:
     - `auth/` for login and role selection
     - `participant/` for participant actions
     - `judge/` for scoring and feedback
     - `admin/` for event operations
     - `superadmin/` for higher-level event administration
   - This makes the role boundaries a primary architectural concern.

4. **Authentication and session state**
   - `src/contexts/AuthContext.jsx` is the central state boundary for authentication.
   - It likely stores the current user, token, and role, and exposes login/logout/session hydration to the rest of the app.
   - The README indicates **JWT authentication**, so the frontend is a token-based client rather than a server session app.

5. **Route protection and authorization**
   - `src/components/ProtectedRoute.jsx` is the route guard layer.
   - The README mentions additional role-specific guards conceptually (`AdminRoute`, `JudgeRoute`, `SuperAdminRoute`), but in this tree the visible guard abstraction is `ProtectedRoute`.
   - The routing boundary prevents unauthorized access to role-specific pages and is the main security control in the client.

6. **API boundary**
   - `src/services/api.js` is the single service layer for backend communication.
   - This is the main integration boundary between UI and server: all domain pages likely call into this module for HTTP operations.
   - The environment variable `VITE_API_BASE_URL` in `.env` determines which backend the frontend targets.

7. **Participant subsystem**
   - `src/pages/participant/` contains participant-facing workflows:
     - `CheckIn.jsx` for QR/event check-in
     - `Food.jsx` for food distribution access
     - `ProblemStatement.jsx` for assigned challenge viewing
     - `Certificate.jsx` for certificate access
     - `Photos.jsx` for media uploads or viewing
   - `Participant.jsx` is the role shell/dashboard for this workspace.

8. **Judge subsystem**
   - `src/pages/judge/` contains judge workflows:
     - `AssignedTeams.jsx` for teams to evaluate
     - `GiveMarks.jsx` and `EditMarks.jsx` for scoring
     - `ViewPreviousFeedback.jsx` for prior evaluations
   - `Judge.jsx` acts as the judge workspace container.
   - This subsystem is evaluation-centric and depends on backend-provided assignments and submissions.

9. **Admin subsystem**
   - `src/pages/admin/` handles event operations and on-ground logistics:
     - user and team management (`AddUser`, `AddBulkUser`, `AddTeam`, `Teams`, `Participants`)
     - check-in operations (`CheckIn`, `CheckInQR`, `CheckedInUsers`, `NotCheckedInUsers`)
     - food QR flow (`FoodQR`)
     - dashboard views (`Dashboard`, `AdminDashboard`)
     - problem statement management (`AddPS`)
   - This role is operational rather than evaluative, focused on participant/event state.

10. **Super Admin subsystem**
   - `src/pages/superadmin/` is the highest-privilege control plane:
     - judge allocation (`AssignJudges`, `AssignedJudges`)
     - team and user management (`AddTeam`, `AddUser`, `Teams`, `Participants`)
     - leaderboard access (`LeaderBoard`)
     - overall dashboards (`Dashboard`, `SuperAdminDashboard`)
   - This role appears to manage cross-event coordination and authority assignment.

11. **Shared UI and interaction components**
   - `src/components/` contains reusable UI pieces used across roles:
     - `Loader.jsx` for async/loading states
     - `GoBackButton.jsx` for navigation convenience
     - `AutoComplete.jsx` for selection-heavy forms
   - These shared components reduce duplication across the many admin-style forms and screens.

12. **Data flow and user journey**
   - Typical flow: **login/role selection → AuthContext stores identity → ProtectedRoute checks access → role dashboard loads → page-specific API calls fetch/update backend state**.
   - Feature pages are thin UI shells around backend-driven data such as teams, judges, check-ins, marks, and leaderboard entries.
   - The app is therefore mostly a **stateful client over a centralized event-management API**, not a self-contained local domain engine.

13. **Deployment and build infrastructure**
   - The project is built with **Vite** and deployed on **Vercel** (`vercel.json` present).
   - `tailwind.config.js` and `postcss.config.js` support the styling pipeline.
   - `eslint.config.js` indicates code quality/linting is part of the development workflow.

14. **What matters most for an architecture diagram**
   - The key diagram boundaries are:
     - **Browser SPA shell**
     - **Auth/session context**
     - **Route protection layer**
     - **Role-specific workspaces**
     - **Shared UI components**
     - **API service layer**
     - **External backend API / database**
   - The architecture is fundamentally a **role-partitioned frontend** talking to one backend, with authorization enforced on the client through context plus protected routes.

Main entry points: [`src/components/ProtectedRoute.jsx`](https://github.com/rsayyed591/hacktrack-client/blob/main/src/components/ProtectedRoute.jsx) (ProtectedRoute), [`src/App.jsx`](https://github.com/rsayyed591/hacktrack-client/blob/main/src/App.jsx) (App.jsx), [`src/services/api.js`](https://github.com/rsayyed591/hacktrack-client/blob/main/src/services/api.js) (API service), [`src/components`](https://github.com/rsayyed591/hacktrack-client/tree/main/src/components) (Shared UI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_g_core["Core app"]
  node_n_index["index.html<br/>Vite entry<br/>[index.html]"]
  node_n_main["main.jsx<br/>bootstrap<br/>[main.jsx]"]
  node_n_app["App.jsx<br/>app shell<br/>[App.jsx]"]
  node_n_auth(("AuthContext<br/>session state<br/>[AuthContext.jsx]"))
  node_n_guard{{"ProtectedRoute<br/>route guard<br/>[ProtectedRoute.jsx]"}}
  node_n_api["API service<br/>backend client<br/>[api.js]"]
  node_n_shared["Shared UI<br/>reusable components"]
  node_n_loader(("Loader<br/>loading state<br/>[Loader.jsx]"))
  node_n_goback(("GoBackButton<br/>navigation helper<br/>[GoBackButton.jsx]"))
  node_n_autocomplete(("AutoComplete<br/>form helper<br/>[AutoComplete.jsx]"))
end

subgraph group_g_roles["Role workspaces"]
  node_n_auth_pages["Auth pages<br/>auth workspace"]
  node_n_participant["Participant<br/>[Participant.jsx]"]
  node_n_judge["Judge<br/>[Judge.jsx]"]
  node_n_admin["Admin<br/>[AdminDashboard.jsx]"]
  node_n_superadmin["Super Admin<br/>control workspace"]
end

subgraph group_g_infra["Build & deploy"]
  node_n_styles["Styles<br/>css/tailwind<br/>[index.css]"]
  node_n_build["Build config<br/>tooling<br/>[vite.config.js]"]
end

node_n_backend[("Backend API<br/>external server")]

node_n_index -->|"loads"| node_n_main
node_n_main -->|"mounts"| node_n_app
node_n_app -->|"provides session"| node_n_auth
node_n_app -->|"wraps routes"| node_n_guard
node_n_guard -->|"allows"| node_n_auth_pages
node_n_guard -->|"allows"| node_n_participant
node_n_guard -->|"allows"| node_n_judge
node_n_guard -->|"allows"| node_n_admin
node_n_guard -->|"allows"| node_n_superadmin
node_n_auth_pages -->|"login state"| node_n_auth
node_n_participant -->|"fetches data"| node_n_api
node_n_judge -->|"submits marks"| node_n_api
node_n_admin -->|"operates events"| node_n_api
node_n_superadmin -->|"controls platform"| node_n_api
node_n_api -->|"HTTP"| node_n_backend
node_n_shared -->|"includes"| node_n_loader
node_n_shared -->|"includes"| node_n_goback
node_n_shared -->|"includes"| node_n_autocomplete
node_n_app -->|"uses"| node_n_styles
node_n_build -->|"builds"| node_n_app
node_n_build -->|"processes"| node_n_styles

click node_n_index "https://github.com/rsayyed591/hacktrack-client/blob/main/index.html"
click node_n_main "https://github.com/rsayyed591/hacktrack-client/blob/main/src/main.jsx"
click node_n_app "https://github.com/rsayyed591/hacktrack-client/blob/main/src/App.jsx"
click node_n_auth "https://github.com/rsayyed591/hacktrack-client/blob/main/src/contexts/AuthContext.jsx"
click node_n_guard "https://github.com/rsayyed591/hacktrack-client/blob/main/src/components/ProtectedRoute.jsx"
click node_n_api "https://github.com/rsayyed591/hacktrack-client/blob/main/src/services/api.js"
click node_n_shared "https://github.com/rsayyed591/hacktrack-client/tree/main/src/components"
click node_n_loader "https://github.com/rsayyed591/hacktrack-client/blob/main/src/components/Loader.jsx"
click node_n_goback "https://github.com/rsayyed591/hacktrack-client/blob/main/src/components/GoBackButton.jsx"
click node_n_autocomplete "https://github.com/rsayyed591/hacktrack-client/blob/main/src/components/AutoComplete.jsx"
click node_n_auth_pages "https://github.com/rsayyed591/hacktrack-client/tree/main/src/pages/auth"
click node_n_participant "https://github.com/rsayyed591/hacktrack-client/blob/main/src/pages/participant/Participant.jsx"
click node_n_judge "https://github.com/rsayyed591/hacktrack-client/blob/main/src/pages/judge/Judge.jsx"
click node_n_admin "https://github.com/rsayyed591/hacktrack-client/blob/main/src/pages/admin/AdminDashboard.jsx"
click node_n_superadmin "https://github.com/rsayyed591/hacktrack-client/blob/main/src/pages/superadmin/SuperAdminDashboard.jsx"
click node_n_styles "https://github.com/rsayyed591/hacktrack-client/blob/main/src/index.css"
click node_n_build "https://github.com/rsayyed591/hacktrack-client/blob/main/vite.config.js"

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_n_index,node_n_main,node_n_app,node_n_auth,node_n_guard,node_n_api,node_n_shared,node_n_loader,node_n_goback,node_n_autocomplete toneBlue
class node_n_auth_pages,node_n_participant,node_n_judge,node_n_admin,node_n_superadmin toneAmber
class node_n_styles,node_n_build toneMint
class node_n_backend toneNeutral
```

## Components

### Core app

Browser SPA shell, bootstrapping, auth, routing, and shared UI.

- [index.html](https://github.com/rsayyed591/hacktrack-client/blob/main/index.html): Vite entry · HTML entry point for the frontend bundle. · `index.html`
- [main.jsx](https://github.com/rsayyed591/hacktrack-client/blob/main/src/main.jsx): bootstrap · Mounts the React application into the page. · `src/main.jsx`
- [App.jsx](https://github.com/rsayyed591/hacktrack-client/blob/main/src/App.jsx): app shell · Top-level composition point for routing and global layout. · `src/App.jsx`
- [AuthContext](https://github.com/rsayyed591/hacktrack-client/blob/main/src/contexts/AuthContext.jsx): session state · Central client-side auth state for user, token, role, and session hydration. · `src/contexts/AuthContext.jsx`
- [ProtectedRoute](https://github.com/rsayyed591/hacktrack-client/blob/main/src/components/ProtectedRoute.jsx): route guard · Authorization gate for protected role-specific routes. · `src/components/ProtectedRoute.jsx`
- [API service](https://github.com/rsayyed591/hacktrack-client/blob/main/src/services/api.js): backend client · Single HTTP integration layer used by the feature pages. · `src/services/api.js`
- [Shared UI](https://github.com/rsayyed591/hacktrack-client/tree/main/src/components): reusable components · Common UI helpers used across workflows and forms. · `src/components`
- [Loader](https://github.com/rsayyed591/hacktrack-client/blob/main/src/components/Loader.jsx): loading state · Reusable async/loading indicator. · `src/components/Loader.jsx`
- [GoBackButton](https://github.com/rsayyed591/hacktrack-client/blob/main/src/components/GoBackButton.jsx): navigation helper · Shared back-navigation control. · `src/components/GoBackButton.jsx`
- [AutoComplete](https://github.com/rsayyed591/hacktrack-client/blob/main/src/components/AutoComplete.jsx): form helper · Shared selection component for search or picking entities. · `src/components/AutoComplete.jsx`

### Role workspaces

Role-specific page trees for participant, judge, admin, and super admin.

- [Auth pages](https://github.com/rsayyed591/hacktrack-client/tree/main/src/pages/auth): auth workspace · Login and role selection screens. · `src/pages/auth`
- [Participant](https://github.com/rsayyed591/hacktrack-client/blob/main/src/pages/participant/Participant.jsx): participant workspace · Participant-facing dashboard and workflows. · `src/pages/participant/Participant.jsx`
- [Judge](https://github.com/rsayyed591/hacktrack-client/blob/main/src/pages/judge/Judge.jsx): judge workspace · Judge-facing evaluation and feedback workspace. · `src/pages/judge/Judge.jsx`
- [Admin](https://github.com/rsayyed591/hacktrack-client/blob/main/src/pages/admin/AdminDashboard.jsx): admin workspace · Operational admin workspace for event management and check-in. · `src/pages/admin/AdminDashboard.jsx`
- [Super Admin](https://github.com/rsayyed591/hacktrack-client/blob/main/src/pages/superadmin/SuperAdminDashboard.jsx): control workspace · Highest-privilege workspace for cross-event administration. · `src/pages/superadmin/SuperAdminDashboard.jsx`

### Build & deploy

Frontend build, styling, linting, and hosting configuration.

- [Styles](https://github.com/rsayyed591/hacktrack-client/blob/main/src/index.css): css/tailwind · Global CSS and utility styling pipeline. · `src/index.css`
- [Build config](https://github.com/rsayyed591/hacktrack-client/blob/main/vite.config.js): tooling · Vite, Tailwind, PostCSS, ESLint, and deployment configuration. · `vite.config.js`

### Other components

- **Backend API**: external server · Separate Node.js/Express service providing authentication and event data.

## Connections

- index.html → main.jsx: loads · The HTML entry point loads the React bootstrap.
- main.jsx → App.jsx: mounts · Bootstraps the top-level app composition.
- App.jsx → AuthContext: provides session · App wiring exposes authentication state to the tree.
- App.jsx → ProtectedRoute: wraps routes · Routes are protected by the authorization gate.
- ProtectedRoute → Auth pages: allows · Unauthenticated users are sent to auth screens.
- ProtectedRoute → Participant: allows · Participant routes are gated by role checks.
- ProtectedRoute → Judge: allows · Judge routes are gated by role checks.
- ProtectedRoute → Admin: allows · Admin routes are gated by role checks.
- ProtectedRoute → Super Admin: allows · Super admin routes are gated by role checks.
- Auth pages → AuthContext: login state · Login and role selection update the auth context.
- Participant → API service: fetches data · Participant workflows read and update backend records.
- Judge → API service: submits marks · Judge workflows request assignments and persist feedback.
- Admin → API service: operates events · Admin workflows manage users, teams, check-ins, and problem statements.
- Super Admin → API service: controls platform · Super admin workflows manage judges, teams, and leaderboard data.
- API service → Backend API: HTTP · Central client-side service talks to the external backend.
- Shared UI → Loader: includes · Shared UI contains the loading indicator.
- Shared UI → GoBackButton: includes · Shared UI contains navigation helpers.
- Shared UI → AutoComplete: includes · Shared UI contains form-selection helpers.
- App.jsx → Styles: uses · Global application styling is applied at the shell level.
- Build config → App.jsx: builds · Vite and related tooling build the frontend app.
- Build config → Styles: processes · Tailwind and PostCSS participate in the styling pipeline.