How rsayyed591/hacktrack-client works
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: ProtectedRoute.jsx ProtectedRoute · App.jsx App.jsx · api.js API service · components Shared UI
Components 18
Core app
Browser SPA shell, bootstrapping, auth, routing, and shared UI.
- index.html · HTML entry point for the frontend bundle.
index.html - main.jsx · Mounts the React application into the page.
src/main.jsx - App.jsx · Top-level composition point for routing and global layout.
src/App.jsx - AuthContext · Central client-side auth state for user, token, role, and session hydration.
src/contexts/AuthContext.jsx - ProtectedRoute · Authorization gate for protected role-specific routes.
src/components/ProtectedRoute.jsx - API service · Single HTTP integration layer used by the feature pages.
src/services/api.js - Shared UI · Common UI helpers used across workflows and forms.
src/components - Loader · Reusable async/loading indicator.
src/components/Loader.jsx - GoBackButton · Shared back-navigation control.
src/components/GoBackButton.jsx - AutoComplete · 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 · Login and role selection screens.
src/pages/auth - Participant · Participant-facing dashboard and workflows.
src/pages/participant/Participant.jsx - Judge · Judge-facing evaluation and feedback workspace.
src/pages/judge/Judge.jsx - Admin · Operational admin workspace for event management and check-in.
src/pages/admin/AdminDashboard.jsx - Super Admin · Highest-privilege workspace for cross-event administration.
src/pages/superadmin/SuperAdminDashboard.jsx
Build & deploy
Frontend build, styling, linting, and hosting configuration.
- Styles · Global CSS and utility styling pipeline.
src/index.css - Build config · Vite, Tailwind, PostCSS, ESLint, and deployment configuration.
vite.config.js
Other components
- Backend API · Separate Node.js/Express service providing authentication and event data.
Connections 21
- 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.