# thesachinyyadav/sociomobilev2 architecture

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

- Interactive diagram: https://gitdiagram.com/thesachinyyadav/sociomobilev2
- Repository: https://github.com/thesachinyyadav/sociomobilev2

## Overview

SOCIO is a mobile-first campus events and student-life app, delivered as a Next.js PWA and Capacitor hybrid app. Users sign in, discover events and festivals, view details, register, and access tickets; volunteers scan tickets online or queue scans for later synchronization. The graph also captures clubs, catering, feedback, notifications, wallet passes, offline support, and native startup. Source excerpts establish key calls; other subsystem relationships are included only where the README documents them.

Main entry points: [`lib/apiClient.ts`](https://github.com/thesachinyyadav/sociomobilev2/blob/main/lib/apiClient.ts) (API client), [`context/AuthContext.tsx`](https://github.com/thesachinyyadav/sociomobilev2/blob/main/context/AuthContext.tsx) (Authentication state), [`app/events/page.tsx`](https://github.com/thesachinyyadav/sociomobilev2/blob/main/app/events/page.tsx) (Event and fest browsing), [`app/volunteer/scanner/[eventId]/ScannerClient.tsx`](https://github.com/thesachinyyadav/sociomobilev2/blob/main/app/volunteer/scanner/%5BeventId%5D/ScannerClient.tsx) (QR ticket scanner)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["App experience"]
  node_dashboard["Dashboard and discovery<br/>[page.tsx]"]
  node_event_browse["Event and fest browsing<br/>[page.tsx]"]
  node_event_detail["Event details"]
  node_fest_detail["Festival details"]
  node_clubs["Clubs and catering<br/>[page.tsx]"]
  node_profile["Profile and tickets<br/>[page.tsx]"]
  node_ui_components["Shared interface components<br/>[EventCard.tsx]"]
  node_ui_primitives["Buttons and empty states<br/>[Button.tsx]"]
  node_date_utils["Date formatting<br/>[dateUtils.ts]"]
  node_debounce["Search debounce<br/>[useDebounce.ts]"]
end

subgraph group_identity["Identity and data"]
  node_auth["Authentication state<br/>[AuthContext.tsx]"]
  node_event_state["Event state and cache<br/>[EventContext.tsx]"]
  node_api["API client<br/>[apiClient.ts]"]
  node_backend["SOCIO API gateway"]
  node_supabase["Supabase client<br/>[supabaseClient.ts]"]
  node_cache_policy["Cache policy<br/>[policy.ts]"]
end

subgraph group_attendance["Registration and attendance"]
  node_registration["Event registration<br/>[RegisterClient.tsx]"]
  node_volunteer["Volunteer event access<br/>[page.tsx]"]
  node_scanner["QR ticket scanner<br/>[ScannerClient.tsx]"]
  node_scan_service["Scanner service<br/>[ScannerService.ts]"]
  node_volunteer_access["Volunteer authorization<br/>[volunteerAccess.ts]"]
end

subgraph group_platform["Offline and native"]
  node_offline_db[("Offline IndexedDB<br/>[db.ts]")]
  node_sync["Queued scan sync<br/>[syncEngine.ts]"]
  node_trusted_time["Trusted time checks<br/>[index.ts]"]
  node_service_worker["Offline asset fallback<br/>[sw.js]"]
  node_native["Capacitor native runtime"]
end

subgraph group_engagement["Engagement and extras"]
  node_notifications["Notifications"]
  node_push_service["Push provider"]
  node_wallet["Wallet pass routes<br/>[route.ts]"]
  node_wallet_crypto["Wallet signing<br/>[walletCrypto.ts]"]
  node_feedback["Event feedback<br/>[FeedbackClient.tsx]"]
  node_clubs_apply["Club applications<br/>[route.ts]"]
  node_share["Share links<br/>[share.ts]"]
end

node_user(("Student or volunteer"))

node_user -->|"opens app"| node_dashboard
node_dashboard -->|"reads session"| node_auth
node_dashboard -->|"reads events"| node_event_state
node_event_browse -->|"reads events"| node_event_state
node_event_detail -->|"fetches event"| node_api
node_fest_detail -->|"fetches festival"| node_api
node_event_detail -.->|"links to signup"| node_registration
node_registration -->|"submits signup"| node_api
node_clubs -->|"loads club data"| node_api
node_clubs_apply -.->|"handles application"| node_backend
node_profile -->|"reads session"| node_auth
node_profile -->|"loads ticket data"| node_api
node_auth -->|"requests user data"| node_api
node_auth -->|"uses client"| node_supabase
node_event_state -->|"fetches events"| node_api
node_event_state -->|"loads cached events"| node_offline_db
node_api -->|"applies policy"| node_cache_policy
node_api -.->|"sends requests"| node_backend
node_volunteer -.->|"checks role"| node_auth
node_volunteer -.->|"opens scanner"| node_scanner
node_scanner -->|"checks permission"| node_volunteer_access
node_scanner -->|"verifies ticket"| node_api
node_scanner -->|"uses scanner"| node_scan_service
node_scanner -.->|"queues offline scan"| node_sync
node_sync -->|"reads and deletes queue"| node_offline_db
node_sync -->|"posts scan"| node_api
node_sync -->|"builds provenance"| node_trusted_time
node_service_worker -.->|"serves cached assets"| node_user
node_native -->|"observes session"| node_auth
node_native -->|"observes events"| node_event_state
node_notifications -->|"uses user state"| node_auth
node_notifications -->|"calls API"| node_api
node_notifications -.->|"registers push"| node_push_service
node_wallet -->|"signs pass data"| node_wallet_crypto
node_feedback -->|"posts feedback"| node_api
node_event_browse -->|"renders cards"| node_ui_components
node_event_browse -->|"renders controls"| node_ui_primitives
node_event_browse -->|"formats dates"| node_date_utils
node_event_browse -->|"debounces search"| node_debounce
node_event_detail -->|"creates share link"| node_share
node_fest_detail -->|"creates share link"| node_share

click node_dashboard "https://github.com/thesachinyyadav/sociomobilev2/blob/main/app/page.tsx"
click node_event_browse "https://github.com/thesachinyyadav/sociomobilev2/blob/main/app/events/page.tsx"
click node_event_detail "https://github.com/thesachinyyadav/sociomobilev2/blob/main/app/event/%5Bid%5D/EventDetailClient.tsx"
click node_fest_detail "https://github.com/thesachinyyadav/sociomobilev2/blob/main/app/fest/%5Bid%5D/FestDetailClient.tsx"
click node_clubs "https://github.com/thesachinyyadav/sociomobilev2/blob/main/app/clubs/page.tsx"
click node_profile "https://github.com/thesachinyyadav/sociomobilev2/blob/main/app/profile/page.tsx"
click node_auth "https://github.com/thesachinyyadav/sociomobilev2/blob/main/context/AuthContext.tsx"
click node_event_state "https://github.com/thesachinyyadav/sociomobilev2/blob/main/context/EventContext.tsx"
click node_api "https://github.com/thesachinyyadav/sociomobilev2/blob/main/lib/apiClient.ts"
click node_supabase "https://github.com/thesachinyyadav/sociomobilev2/blob/main/lib/supabaseClient.ts"
click node_registration "https://github.com/thesachinyyadav/sociomobilev2/blob/main/app/event/%5Bid%5D/register/RegisterClient.tsx"
click node_volunteer "https://github.com/thesachinyyadav/sociomobilev2/blob/main/app/volunteer/page.tsx"
click node_scanner "https://github.com/thesachinyyadav/sociomobilev2/blob/main/app/volunteer/scanner/%5BeventId%5D/ScannerClient.tsx"
click node_scan_service "https://github.com/thesachinyyadav/sociomobilev2/blob/main/lib/ScannerService.ts"
click node_offline_db "https://github.com/thesachinyyadav/sociomobilev2/blob/main/lib/offline/db.ts"
click node_sync "https://github.com/thesachinyyadav/sociomobilev2/blob/main/lib/offline/syncEngine.ts"
click node_trusted_time "https://github.com/thesachinyyadav/sociomobilev2/blob/main/lib/offlineTime/index.ts"
click node_service_worker "https://github.com/thesachinyyadav/sociomobilev2/blob/main/public/sw.js"
click node_native "https://github.com/thesachinyyadav/sociomobilev2/blob/main/components/native/NativeLaunchController.tsx"
click node_notifications "https://github.com/thesachinyyadav/sociomobilev2/blob/main/context/NotificationContext.tsx"
click node_wallet "https://github.com/thesachinyyadav/sociomobilev2/blob/main/app/api/wallet/apple/route.ts"
click node_wallet_crypto "https://github.com/thesachinyyadav/sociomobilev2/blob/main/lib/walletCrypto.ts"
click node_feedback "https://github.com/thesachinyyadav/sociomobilev2/blob/main/app/feedback/%5BeventId%5D/FeedbackClient.tsx"
click node_clubs_apply "https://github.com/thesachinyyadav/sociomobilev2/blob/main/app/api/clubs/apply/route.ts"
click node_ui_components "https://github.com/thesachinyyadav/sociomobilev2/blob/main/components/EventCard.tsx"
click node_ui_primitives "https://github.com/thesachinyyadav/sociomobilev2/blob/main/components/Button.tsx"
click node_cache_policy "https://github.com/thesachinyyadav/sociomobilev2/blob/main/lib/cache/policy.ts"
click node_date_utils "https://github.com/thesachinyyadav/sociomobilev2/blob/main/lib/dateUtils.ts"
click node_share "https://github.com/thesachinyyadav/sociomobilev2/blob/main/lib/share.ts"
click node_debounce "https://github.com/thesachinyyadav/sociomobilev2/blob/main/lib/useDebounce.ts"
click node_volunteer_access "https://github.com/thesachinyyadav/sociomobilev2/blob/main/lib/volunteerAccess.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_dashboard,node_event_browse,node_event_detail,node_fest_detail,node_clubs,node_profile,node_ui_components,node_ui_primitives,node_date_utils,node_debounce toneBlue
class node_auth,node_event_state,node_api,node_backend,node_supabase,node_cache_policy toneAmber
class node_registration,node_volunteer,node_scanner,node_scan_service,node_volunteer_access toneMint
class node_offline_db,node_sync,node_trusted_time,node_service_worker,node_native toneRose
class node_notifications,node_push_service,node_wallet,node_wallet_crypto,node_feedback,node_clubs_apply,node_share,node_user toneIndigo
```

## Components

### App experience

- [Dashboard and discovery](https://github.com/thesachinyyadav/sociomobilev2/blob/main/app/page.tsx): `app/page.tsx`
- [Event and fest browsing](https://github.com/thesachinyyadav/sociomobilev2/blob/main/app/events/page.tsx): `app/events/page.tsx`
- [Event details](https://github.com/thesachinyyadav/sociomobilev2/blob/main/app/event/%5Bid%5D/EventDetailClient.tsx): `app/event/[id]/EventDetailClient.tsx`
- [Festival details](https://github.com/thesachinyyadav/sociomobilev2/blob/main/app/fest/%5Bid%5D/FestDetailClient.tsx): `app/fest/[id]/FestDetailClient.tsx`
- [Clubs and catering](https://github.com/thesachinyyadav/sociomobilev2/blob/main/app/clubs/page.tsx): `app/clubs/page.tsx`
- [Profile and tickets](https://github.com/thesachinyyadav/sociomobilev2/blob/main/app/profile/page.tsx): `app/profile/page.tsx`
- [Shared interface components](https://github.com/thesachinyyadav/sociomobilev2/blob/main/components/EventCard.tsx): `components/EventCard.tsx`
- [Buttons and empty states](https://github.com/thesachinyyadav/sociomobilev2/blob/main/components/Button.tsx): `components/Button.tsx`
- [Date formatting](https://github.com/thesachinyyadav/sociomobilev2/blob/main/lib/dateUtils.ts): `lib/dateUtils.ts`
- [Search debounce](https://github.com/thesachinyyadav/sociomobilev2/blob/main/lib/useDebounce.ts): `lib/useDebounce.ts`

### Identity and data

- [Authentication state](https://github.com/thesachinyyadav/sociomobilev2/blob/main/context/AuthContext.tsx): `context/AuthContext.tsx`
- [Event state and cache](https://github.com/thesachinyyadav/sociomobilev2/blob/main/context/EventContext.tsx): `context/EventContext.tsx`
- [API client](https://github.com/thesachinyyadav/sociomobilev2/blob/main/lib/apiClient.ts): `lib/apiClient.ts`
- **SOCIO API gateway**
- [Supabase client](https://github.com/thesachinyyadav/sociomobilev2/blob/main/lib/supabaseClient.ts): `lib/supabaseClient.ts`
- [Cache policy](https://github.com/thesachinyyadav/sociomobilev2/blob/main/lib/cache/policy.ts): `lib/cache/policy.ts`

### Registration and attendance

- [Event registration](https://github.com/thesachinyyadav/sociomobilev2/blob/main/app/event/%5Bid%5D/register/RegisterClient.tsx): `app/event/[id]/register/RegisterClient.tsx`
- [Volunteer event access](https://github.com/thesachinyyadav/sociomobilev2/blob/main/app/volunteer/page.tsx): `app/volunteer/page.tsx`
- [QR ticket scanner](https://github.com/thesachinyyadav/sociomobilev2/blob/main/app/volunteer/scanner/%5BeventId%5D/ScannerClient.tsx): `app/volunteer/scanner/[eventId]/ScannerClient.tsx`
- [Scanner service](https://github.com/thesachinyyadav/sociomobilev2/blob/main/lib/ScannerService.ts): `lib/ScannerService.ts`
- [Volunteer authorization](https://github.com/thesachinyyadav/sociomobilev2/blob/main/lib/volunteerAccess.ts): `lib/volunteerAccess.ts`

### Offline and native

- [Offline IndexedDB](https://github.com/thesachinyyadav/sociomobilev2/blob/main/lib/offline/db.ts): `lib/offline/db.ts`
- [Queued scan sync](https://github.com/thesachinyyadav/sociomobilev2/blob/main/lib/offline/syncEngine.ts): `lib/offline/syncEngine.ts`
- [Trusted time checks](https://github.com/thesachinyyadav/sociomobilev2/blob/main/lib/offlineTime/index.ts): `lib/offlineTime/index.ts`
- [Offline asset fallback](https://github.com/thesachinyyadav/sociomobilev2/blob/main/public/sw.js): `public/sw.js`
- [Capacitor native runtime](https://github.com/thesachinyyadav/sociomobilev2/blob/main/components/native/NativeLaunchController.tsx): `components/native/NativeLaunchController.tsx`

### Engagement and extras

- [Notifications](https://github.com/thesachinyyadav/sociomobilev2/blob/main/context/NotificationContext.tsx): `context/NotificationContext.tsx`
- **Push provider**
- [Wallet pass routes](https://github.com/thesachinyyadav/sociomobilev2/blob/main/app/api/wallet/apple/route.ts): `app/api/wallet/apple/route.ts`
- [Wallet signing](https://github.com/thesachinyyadav/sociomobilev2/blob/main/lib/walletCrypto.ts): `lib/walletCrypto.ts`
- [Event feedback](https://github.com/thesachinyyadav/sociomobilev2/blob/main/app/feedback/%5BeventId%5D/FeedbackClient.tsx): `app/feedback/[eventId]/FeedbackClient.tsx`
- [Club applications](https://github.com/thesachinyyadav/sociomobilev2/blob/main/app/api/clubs/apply/route.ts): `app/api/clubs/apply/route.ts`
- [Share links](https://github.com/thesachinyyadav/sociomobilev2/blob/main/lib/share.ts): `lib/share.ts`

### Other components

- **Student or volunteer**

## Connections

- Student or volunteer → Dashboard and discovery: opens app
- Dashboard and discovery → Authentication state: reads session (evidence: `app/page.tsx`)
- Dashboard and discovery → Event state and cache: reads events (evidence: `app/page.tsx`)
- Event and fest browsing → Event state and cache: reads events (evidence: `app/events/page.tsx`)
- Event details → API client: fetches event (evidence: `app/event/[id]/EventDetailClient.tsx`)
- Festival details → API client: fetches festival (evidence: `app/fest/[id]/FestDetailClient.tsx`)
- Event details → Event registration: links to signup
- Event registration → API client: submits signup (evidence: `app/event/[id]/register/RegisterClient.tsx`)
- Clubs and catering → API client: loads club data (evidence: `app/clubs/page.tsx`)
- Club applications → SOCIO API gateway: handles application
- Profile and tickets → Authentication state: reads session (evidence: `app/profile/page.tsx`)
- Profile and tickets → API client: loads ticket data (evidence: `app/profile/page.tsx`)
- Authentication state → API client: requests user data (evidence: `context/AuthContext.tsx`)
- Authentication state → Supabase client: uses client (evidence: `context/AuthContext.tsx`)
- Event state and cache → API client: fetches events (evidence: `context/EventContext.tsx`)
- Event state and cache → Offline IndexedDB: loads cached events (evidence: `context/EventContext.tsx`)
- API client → Cache policy: applies policy (evidence: `lib/apiClient.ts`)
- API client → SOCIO API gateway: sends requests
- Volunteer event access → Authentication state: checks role
- Volunteer event access → QR ticket scanner: opens scanner
- QR ticket scanner → Volunteer authorization: checks permission (evidence: `app/volunteer/scanner/[eventId]/ScannerClient.tsx`)
- QR ticket scanner → API client: verifies ticket (evidence: `app/volunteer/scanner/[eventId]/ScannerClient.tsx`)
- QR ticket scanner → Scanner service: uses scanner (evidence: `app/volunteer/scanner/[eventId]/ScannerClient.tsx`)
- QR ticket scanner → Queued scan sync: queues offline scan
- Queued scan sync → Offline IndexedDB: reads and deletes queue (evidence: `lib/offline/syncEngine.ts`)
- Queued scan sync → API client: posts scan (evidence: `lib/offline/syncEngine.ts`)
- Queued scan sync → Trusted time checks: builds provenance (evidence: `lib/offline/syncEngine.ts`)
- Offline asset fallback → Student or volunteer: serves cached assets
- Capacitor native runtime → Authentication state: observes session (evidence: `components/native/NativeLaunchController.tsx`)
- Capacitor native runtime → Event state and cache: observes events (evidence: `components/native/NativeLaunchController.tsx`)
- Notifications → Authentication state: uses user state (evidence: `context/NotificationContext.tsx`)
- Notifications → API client: calls API (evidence: `context/NotificationContext.tsx`)
- Notifications → Push provider: registers push
- Wallet pass routes → Wallet signing: signs pass data (evidence: `app/api/wallet/apple/route.ts`)
- Event feedback → API client: posts feedback (evidence: `app/feedback/[eventId]/FeedbackClient.tsx`)
- Event and fest browsing → Shared interface components: renders cards (evidence: `app/events/page.tsx`)
- Event and fest browsing → Buttons and empty states: renders controls (evidence: `app/events/page.tsx`)
- Event and fest browsing → Date formatting: formats dates (evidence: `app/events/page.tsx`)
- Event and fest browsing → Search debounce: debounces search (evidence: `app/events/page.tsx`)
- Event details → Share links: creates share link (evidence: `app/event/[id]/EventDetailClient.tsx`)
- Festival details → Share links: creates share link (evidence: `app/fest/[id]/FestDetailClient.tsx`)
