# vishwassharma28/incridea-client-v2 architecture

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

- Interactive diagram: https://gitdiagram.com/vishwassharma28/incridea-client-v2
- Repository: https://github.com/vishwassharma28/incridea-client-v2

## Overview

1. **Overall shape**
   - This is a **single-page React frontend** built with **TypeScript**, **Vite**, and **Tailwind CSS**.
   - The architecture is route-driven: UI is composed from **page-level screens** under `src/pages`, which assemble reusable components from `src/components`.

2. **Application shell**
   - `src/main.tsx` bootstraps the app, and `src/App.tsx` likely wires global providers, layout, and route rendering.
   - `src/routes/AppRoutes.tsx` is the central routing boundary, mapping URL paths to pages such as Home, Events, Profile, Register, Accommodation, Merch, Quiz, and policy/help pages.
   - Shared chrome lives in components like `Navbar`, `Footer`, `Sidebar`, `MobileMenu`, and `Layout`.

3. **Primary user-facing domains**
   - The UI is organized around fest-specific domains:
     - **Marketing/content pages**: Home, About, Contact, Guidelines, Rules, Privacy, Refund.
     - **Events**: event listing, search, event detail, registration, team creation/joining.
     - **User/account flows**: Register, Reset Password, Profile.
     - **Commerce/fulfillment**: Merch and Accommodation.
     - **Interactive modules**: Quiz.
   - There are also fallback states like `ComingSoon` and `NotFoundPage`.

4. **Backend integration boundary**
   - All server communication is centralized under `src/api`.
   - The API layer is split by domain: `auth`, `registration`, `events/public`, `payment`, `accommodation`, `quiz`, `judging`, `admin`, `organiser`, `branchRep`, `colleges`, `documentation`.
   - `src/api/client.ts` is the shared HTTP client layer, and `src/api/types.ts` provides typed contracts for backend responses and payloads.
   - This separation keeps network logic out of pages/components and makes the backend a clear boundary.

5. **State and session handling**
   - Shared application state appears to be split between:
     - `src/store/index.ts` for global client state
     - `src/context/SocketContext.tsx` for websocket/session-scoped real-time state
     - `src/hooks/useAuth.ts` and `src/hooks/useSocket.ts` as the main consumption layer
   - The architecture suggests a mix of global store + hook-based domain state, rather than heavy local prop drilling.

6. **Real-time subsystem**
   - Websocket support is explicitly modeled through `SocketContext` and `src/api/socket.ts`.
   - This is especially relevant for live dashboard experiences such as judging, leaderboard updates, or operational/admin views.
   - The socket layer is a separate channel from REST, indicating the app has both request/response and push-based data flows.

7. **Forms, validation, and user actions**
   - Input-heavy flows are supported by schema files in `src/schemas`:
     - contact forms
     - merch purchase forms
     - registration forms
   - User actions like booking, payment initiation, event enrollment, and account recovery are likely handled through page-specific forms plus shared modal components.
   - `PaymentProcessingModal` and `QrScanner` indicate important transactional and verification flows.

8. **Feature-specific UI subsystems**
   - The `src/components/events` folder encapsulates event browsing and registration UX, including team creation and joining.
   - The `src/components/dashboard/judge` folder contains a dedicated judge workflow: criteria input, team selection, team members modal, and leaderboard.
   - `src/components/accommodation` and `src/components/merch` isolate their own transaction flows.
   - This indicates the app is modular by business domain, not just by generic UI primitives.

9. **Presentation layer and visual system**
   - Reusable presentation components like `GlassSurface`, `LiquidGlassCard`, `AnimatedGlassCard`, `TechCard`, `TargetCursor`, `LightRays`, and `MovieCredits` suggest a strong branded visual system.
   - The app relies on a shared design language rather than page-specific styling.
   - `src/styles/global.css`, `src/App.css`, Tailwind config, and component-scoped CSS files support a mix of utility styling and custom effects.

10. **Static assets and media**
   - `public/` contains static assets used directly by the app, including event imagery, coming-soon/not-found assets, and a 3D model (`public/models/shirt.glb`).
   - The merch area has a dedicated 3D model component, implying the frontend renders product visualization locally rather than delegating it to a separate service.

11. **Cross-cutting utilities**
   - `src/utils` contains shared helpers for dates, IDs, roles, toast notifications, and upload integration.
   - `src/utils/uploadthing.ts` suggests the app integrates with a file-upload service for media or document uploads.
   - `src/types/models.d.ts` provides app-specific typing for assets or model imports.

12. **Deployment/runtime characteristics**
   - The repo is frontend-only and intended to be deployed as static assets, with the README calling out **Vercel/VPS**.
   - Environment-based configuration is handled through `.env` and `.env.example`.
   - CI/security tooling is present via GitHub Actions and CodeQL, but those are supporting concerns rather than runtime subsystems.

13. **How data flows through the app**
   - Typical flow: **route → page → feature component → hook → API module / socket context → backend**.
   - The backend returns typed data into the page, which then renders domain-specific components and modals.
   - Validation and role utilities gate what the user can submit or see, especially in admin/judge/organiser areas.

14. **What to emphasize in an architecture diagram**
   - Draw a clear boundary between:
     - **Presentation**: pages, reusable UI, branded effects
     - **Client state/session**: auth hook, store, socket context
     - **Network layer**: domain API modules over Axios
     - **Domain features**: events, registration, judging, accommodation, merch, quiz
     - **Static assets**: public media and 3D resources
   - The most important integration points are the REST API backend and the websocket channel.

Main entry points: [`src/pages/HomePage.tsx`](https://github.com/vishwassharma28/incridea-client-v2/blob/main/src/pages/HomePage.tsx) (Pages), [`src/api/client.ts`](https://github.com/vishwassharma28/incridea-client-v2/blob/main/src/api/client.ts) (API modules), [`src/components/Layout.tsx`](https://github.com/vishwassharma28/incridea-client-v2/blob/main/src/components/Layout.tsx) (Layout), [`src/routes/AppRoutes.tsx`](https://github.com/vishwassharma28/incridea-client-v2/blob/main/src/routes/AppRoutes.tsx) (Routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_grp_app["App shell"]
  node_n_main(("main<br/>bootstrap<br/>[main.tsx]"))
  node_n_app["App<br/>root component<br/>[App.tsx]"]
  node_n_routes["Routes<br/>routing<br/>[AppRoutes.tsx]"]
end

subgraph group_grp_ui["UI system"]
  node_n_layout["Layout<br/>shell<br/>[Layout.tsx]"]
  node_n_nav["Nav<br/>[Navbar.tsx]"]
  node_n_footer["Footer<br/>chrome<br/>[Footer.tsx]"]
  node_n_visuals["Visuals<br/>brand UI<br/>[GlassSurface.tsx]"]
end

subgraph group_grp_domains["Feature domains"]
  node_n_pages["Pages<br/>screens<br/>[HomePage.tsx]"]
  node_n_events["Events<br/>event flow<br/>[EventDetails.tsx]"]
  node_n_accom["Accommodation<br/>booking flow<br/>[BookingForms.tsx]"]
  node_n_merch["Merch<br/>commerce flow<br/>[MerchBuyModal.tsx]"]
  node_n_quiz["Quiz<br/>interactive flow<br/>[QuizPage.tsx]"]
  node_n_judge["Judge tools<br/>dashboard flow"]
  node_n_account["Account<br/>auth flow<br/>[RegisterPage.tsx]"]
end

subgraph group_grp_data["Data layer"]
  node_n_state["State<br/>[index.ts]"]
  node_n_socket["Socket<br/>realtime channel<br/>[SocketContext.tsx]"]
  node_n_hooks["Hooks<br/>consumption layer<br/>[useAuth.ts]"]
  node_n_api["API modules<br/>rest boundary<br/>[client.ts]"]
  node_n_schemas["Schemas<br/>validation"]
end

subgraph group_grp_assets["Assets"]
  node_n_public["Public media<br/>static assets<br/>[shirt.glb]"]
end

node_n_main -->|"mounts"| node_n_app
node_n_app -->|"renders"| node_n_routes
node_n_routes -->|"wraps"| node_n_layout
node_n_layout -->|"includes"| node_n_nav
node_n_layout -->|"includes"| node_n_footer
node_n_routes -->|"maps to"| node_n_pages
node_n_pages -->|"assembles"| node_n_events
node_n_pages -->|"assembles"| node_n_accom
node_n_pages -->|"assembles"| node_n_merch
node_n_pages -->|"assembles"| node_n_quiz
node_n_pages -->|"assembles"| node_n_judge
node_n_pages -->|"assembles"| node_n_account
node_n_layout -->|"uses"| node_n_visuals
node_n_events -->|"loads data"| node_n_api
node_n_accom -->|"books via"| node_n_api
node_n_merch -->|"purchases via"| node_n_api
node_n_quiz -->|"queries"| node_n_api
node_n_judge -->|"subscribes"| node_n_socket
node_n_judge -->|"updates"| node_n_api
node_n_account -->|"auth flow"| node_n_hooks
node_n_hooks -->|"reads"| node_n_state
node_n_hooks -->|"consumes"| node_n_socket
node_n_api -.->|"pairs with"| node_n_socket
node_n_pages -->|"validates"| node_n_schemas
node_n_pages -->|"references"| node_n_public

click node_n_main "https://github.com/vishwassharma28/incridea-client-v2/blob/main/src/main.tsx"
click node_n_app "https://github.com/vishwassharma28/incridea-client-v2/blob/main/src/App.tsx"
click node_n_routes "https://github.com/vishwassharma28/incridea-client-v2/blob/main/src/routes/AppRoutes.tsx"
click node_n_layout "https://github.com/vishwassharma28/incridea-client-v2/blob/main/src/components/Layout.tsx"
click node_n_nav "https://github.com/vishwassharma28/incridea-client-v2/blob/main/src/components/Navbar.tsx"
click node_n_footer "https://github.com/vishwassharma28/incridea-client-v2/blob/main/src/components/Footer.tsx"
click node_n_visuals "https://github.com/vishwassharma28/incridea-client-v2/blob/main/src/components/GlassSurface.tsx"
click node_n_pages "https://github.com/vishwassharma28/incridea-client-v2/blob/main/src/pages/HomePage.tsx"
click node_n_events "https://github.com/vishwassharma28/incridea-client-v2/blob/main/src/components/events/EventDetails.tsx"
click node_n_accom "https://github.com/vishwassharma28/incridea-client-v2/blob/main/src/components/accommodation/BookingForms.tsx"
click node_n_merch "https://github.com/vishwassharma28/incridea-client-v2/blob/main/src/components/merch/MerchBuyModal.tsx"
click node_n_quiz "https://github.com/vishwassharma28/incridea-client-v2/blob/main/src/pages/QuizPage.tsx"
click node_n_judge "https://github.com/vishwassharma28/incridea-client-v2/blob/main/src/components/dashboard/judge/JudgeLeaderboard.tsx"
click node_n_account "https://github.com/vishwassharma28/incridea-client-v2/blob/main/src/pages/RegisterPage.tsx"
click node_n_state "https://github.com/vishwassharma28/incridea-client-v2/blob/main/src/store/index.ts"
click node_n_socket "https://github.com/vishwassharma28/incridea-client-v2/blob/main/src/context/SocketContext.tsx"
click node_n_hooks "https://github.com/vishwassharma28/incridea-client-v2/blob/main/src/hooks/useAuth.ts"
click node_n_api "https://github.com/vishwassharma28/incridea-client-v2/blob/main/src/api/client.ts"
click node_n_public "https://github.com/vishwassharma28/incridea-client-v2/blob/main/public/models/shirt.glb"
click node_n_schemas "https://github.com/vishwassharma28/incridea-client-v2/blob/main/src/schemas/registrationSchema.ts"

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_main,node_n_app,node_n_routes toneBlue
class node_n_layout,node_n_nav,node_n_footer,node_n_visuals toneAmber
class node_n_pages,node_n_events,node_n_accom,node_n_merch,node_n_quiz,node_n_judge,node_n_account toneMint
class node_n_state,node_n_socket,node_n_hooks,node_n_api,node_n_schemas toneRose
class node_n_public toneIndigo
```

## Components

### App shell

Bootstraps routing, layout, and global presentation.

- [main](https://github.com/vishwassharma28/incridea-client-v2/blob/main/src/main.tsx): bootstrap · Vite entry that mounts the React app. · `src/main.tsx`
- [App](https://github.com/vishwassharma28/incridea-client-v2/blob/main/src/App.tsx): root component · Top-level app composition and provider boundary. · `src/App.tsx`
- [Routes](https://github.com/vishwassharma28/incridea-client-v2/blob/main/src/routes/AppRoutes.tsx): routing · Central route map from URLs to pages. · `src/routes/AppRoutes.tsx`

### UI system

Shared chrome and reusable visual components.

- [Layout](https://github.com/vishwassharma28/incridea-client-v2/blob/main/src/components/Layout.tsx): shell · Shared page chrome and structural wrapper. · `src/components/Layout.tsx`
- [Nav](https://github.com/vishwassharma28/incridea-client-v2/blob/main/src/components/Navbar.tsx): navigation UI · Primary navigation and mobile menu surfaces. · `src/components/Navbar.tsx`
- [Footer](https://github.com/vishwassharma28/incridea-client-v2/blob/main/src/components/Footer.tsx): chrome · Global footer and site-ending content. · `src/components/Footer.tsx`
- [Visuals](https://github.com/vishwassharma28/incridea-client-v2/blob/main/src/components/GlassSurface.tsx): brand UI · Branded presentation components and effects. · `src/components/GlassSurface.tsx`

### Feature domains

Page-level user journeys organized by business area.

- [Pages](https://github.com/vishwassharma28/incridea-client-v2/blob/main/src/pages/HomePage.tsx): screens · Route-level screens for content, accounts, and fallback states. · `src/pages/HomePage.tsx`
- [Events](https://github.com/vishwassharma28/incridea-client-v2/blob/main/src/components/events/EventDetails.tsx): event flow · Event discovery, detail, registration, and team actions. · `src/components/events/EventDetails.tsx`
- [Accommodation](https://github.com/vishwassharma28/incridea-client-v2/blob/main/src/components/accommodation/BookingForms.tsx): booking flow · Accommodation booking and related forms. · `src/components/accommodation/BookingForms.tsx`
- [Merch](https://github.com/vishwassharma28/incridea-client-v2/blob/main/src/components/merch/MerchBuyModal.tsx): commerce flow · Merch purchase flow and product visualization. · `src/components/merch/MerchBuyModal.tsx`
- [Quiz](https://github.com/vishwassharma28/incridea-client-v2/blob/main/src/pages/QuizPage.tsx): interactive flow · Quiz participation and interaction screen. · `src/pages/QuizPage.tsx`
- [Judge tools](https://github.com/vishwassharma28/incridea-client-v2/blob/main/src/components/dashboard/judge/JudgeLeaderboard.tsx): dashboard flow · Judge workflow for criteria, teams, and leaderboard. · `src/components/dashboard/judge/JudgeLeaderboard.tsx`
- [Account](https://github.com/vishwassharma28/incridea-client-v2/blob/main/src/pages/RegisterPage.tsx): auth flow · Registration, password reset, and profile management. · `src/pages/RegisterPage.tsx`

### Data layer

Client state, hooks, API clients, and realtime channel.

- [State](https://github.com/vishwassharma28/incridea-client-v2/blob/main/src/store/index.ts): client state · Global store and auth/session consumption hooks. · `src/store/index.ts`
- [Socket](https://github.com/vishwassharma28/incridea-client-v2/blob/main/src/context/SocketContext.tsx): realtime channel · WebSocket context and client socket integration. · `src/context/SocketContext.tsx`
- [Hooks](https://github.com/vishwassharma28/incridea-client-v2/blob/main/src/hooks/useAuth.ts): consumption layer · Shared hooks for auth, socket, and data access. · `src/hooks/useAuth.ts`
- [API modules](https://github.com/vishwassharma28/incridea-client-v2/blob/main/src/api/client.ts): rest boundary · Domain API clients over the shared HTTP client and typed contracts. · `src/api/client.ts`
- [Schemas](https://github.com/vishwassharma28/incridea-client-v2/blob/main/src/schemas/registrationSchema.ts): validation · Form validation schemas for contact, merch, and registration flows. · `src/schemas/registrationSchema.ts`

### Assets

Static media and runtime resources served from public.

- [Public media](https://github.com/vishwassharma28/incridea-client-v2/blob/main/public/models/shirt.glb): static assets · Directly served imagery, coming-soon/not-found assets, and 3D model files. · `public/models/shirt.glb`

## Connections

- main → App: mounts · Entry point initializes the root React application.
- App → Routes: renders · App delegates screen selection to the route map.
- Routes → Layout: wraps · Routes are presented inside the shared layout shell.
- Layout → Nav: includes · Layout composes the primary navigation chrome.
- Layout → Footer: includes · Layout composes the global footer.
- Routes → Pages: maps to · Route definitions resolve to page-level screens.
- Pages → Events: assembles · Event pages compose event feature components.
- Pages → Accommodation: assembles · Accommodation pages compose booking UI.
- Pages → Merch: assembles · Merch pages compose commerce UI.
- Pages → Quiz: assembles · Quiz pages provide the interactive quiz surface.
- Pages → Judge tools: assembles · Judge and dashboard pages use the judging workflow components.
- Pages → Account: assembles · Auth and profile pages handle user account flows.
- Layout → Visuals: uses · Shared chrome relies on branded presentation components.
- Events → API modules: loads data · Event browsing and registration depend on REST endpoints.
- Accommodation → API modules: books via · Booking flow uses the accommodation API.
- Merch → API modules: purchases via · Merch checkout uses the payment and merch API boundary.
- Quiz → API modules: queries · Quiz interactions are backed by API calls.
- Judge tools → Socket: subscribes · Judge tools consume realtime updates.
- Judge tools → API modules: updates · Judging actions are persisted through API modules.
- Account → Hooks: auth flow · Account screens use shared auth/session hooks.
- Hooks → State: reads · Hooks consume global client state.
- Hooks → Socket: consumes · Hooks connect components to websocket session state.
- API modules → Socket: pairs with · REST and websocket channels jointly serve live features.
- Pages → Schemas: validates · Form-heavy pages use shared validation schemas.
- Pages → Public media: references · Pages and feature components use direct public assets.
