# cognisphere-aiml-club/club_cognisphere architecture

> Architecture diagram of the GitHub repository cognisphere-aiml-club/club_cognisphere, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/cognisphere-aiml-club/club_cognisphere
- Repository: https://github.com/cognisphere-aiml-club/club_cognisphere

## Overview

This is a club-games event management web app. Participants sign in, complete a profile, browse activities, register or request passes, and use a participant pass for attendance; coordinators administer events, attendance, scores, timers, and announcements. The app also provides leaderboards, certificates, a big-screen display, and Google Sheets synchronization. Firebase/Firestore is the shared backend. Connections reflect the supplied source index and excerpts; several listed capabilities are unsampled, so their internal wiring is not inferred.

Main entry points: [`src/App.jsx`](https://github.com/cognisphere-aiml-club/club_cognisphere/blob/master/src/App.jsx) (App shell), [`src/services/passApprovalService.js`](https://github.com/cognisphere-aiml-club/club_cognisphere/blob/master/src/services/passApprovalService.js) (Pass approvals), [`src/components/BigScreenView.jsx`](https://github.com/cognisphere-aiml-club/club_cognisphere/blob/master/src/components/BigScreenView.jsx) (Big-screen display), [`src/components/RegistrationsHub.jsx`](https://github.com/cognisphere-aiml-club/club_cognisphere/blob/master/src/components/RegistrationsHub.jsx) (Registration oversight)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_access["Access and profiles"]
  node_auth["Sign-in and roles<br/>[AuthContext.jsx]"]
  node_profile["Participant profile"]
  node_profileui["Profile management"]
end

subgraph group_events["Activities and participation"]
  node_activities["Activity catalog<br/>[activities.js]"]
  node_guides["Game guides<br/>[gameGuides.js]"]
  node_activityfeed["Activity updates<br/>[useActivities.js]"]
  node_landing["Event landing"]
  node_gamedetail["Game details<br/>[GameDetailPage.jsx]"]
  node_registration["Registration"]
  node_pass["Participant pass"]
end

subgraph group_operations["Event operations"]
  node_scanner["Attendance scanner"]
  node_attendance["Attendance records"]
  node_passes["Pass approvals"]
  node_registrations["Registration oversight"]
  node_scores["Scoring service<br/>[scoreService.js]"]
  node_leaderboard["Leaderboard"]
  node_timers["Shared timers<br/>[useSharedTimer.js]"]
  node_bigscreen["Big-screen display<br/>[BigScreenView.jsx]"]
  node_announcements["Announcement feed"]
  node_certificates["Certificates"]
  node_sheetsbatch["Sheet batch sync"]
  node_sheets["Google Sheets sync"]
end

subgraph group_platform["Shared platform"]
  node_app["App shell<br/>[App.jsx]"]
  node_firebase["Firebase setup<br/>[firebase.js]"]
  node_firestore[("Firestore")]
end

node_participant(("Participant"))
node_coordinator(("Coordinator"))

node_participant -->|"uses"| node_app
node_coordinator -->|"uses"| node_app
node_app -->|"reads auth state"| node_auth
node_app -->|"loads profile"| node_profile
node_app -->|"loads activities"| node_activityfeed
node_app -->|"opens"| node_registration
node_app -->|"shows"| node_pass
node_app -->|"routes to"| node_scanner
node_app -->|"routes to"| node_landing
node_app -->|"routes to"| node_gamedetail
node_app -->|"routes to"| node_registrations
node_app -->|"routes to"| node_timers
node_app -->|"routes to"| node_bigscreen
node_app -->|"routes to"| node_certificates
node_app -->|"routes to"| node_profileui
node_profileui -->|"uses"| node_profile
node_activityfeed -->|"falls back to"| node_activities
node_activities -->|"uses guide data"| node_guides
node_landing -->|"uses"| node_passes
node_gamedetail -->|"uses"| node_passes
node_pass -->|"uses"| node_passes
node_pass -->|"checks attendance"| node_attendance
node_scanner -->|"records attendance"| node_attendance
node_registrations -->|"uses"| node_passes
node_registrations -->|"uses"| node_attendance
node_registrations -->|"syncs batches"| node_sheetsbatch
node_leaderboard -->|"loads scores"| node_scores
node_bigscreen -->|"uses"| node_scores
node_bigscreen -->|"uses"| node_passes
node_bigscreen -->|"uses"| node_timers
node_bigscreen -->|"uses"| node_announcements
node_certificates -->|"uses"| node_activities
node_sheetsbatch -->|"delegates to"| node_sheets
node_auth -->|"uses"| node_firebase
node_profile -->|"uses"| node_firebase
node_firebase -->|"initializes"| node_firestore
node_attendance -->|"reads and writes"| node_firestore
node_passes -->|"reads and writes"| node_firestore
node_scores -->|"uses"| node_firestore
node_timers -->|"reads and writes"| node_firestore
node_sheets -->|"reads and writes"| node_firestore

click node_app "https://github.com/cognisphere-aiml-club/club_cognisphere/blob/master/src/App.jsx"
click node_auth "https://github.com/cognisphere-aiml-club/club_cognisphere/blob/master/src/contexts/AuthContext.jsx"
click node_profile "https://github.com/cognisphere-aiml-club/club_cognisphere/blob/master/src/hooks/useParticipantProfile.js"
click node_profileui "https://github.com/cognisphere-aiml-club/club_cognisphere/blob/master/src/components/ProfileEditPage.jsx"
click node_activities "https://github.com/cognisphere-aiml-club/club_cognisphere/blob/master/src/data/activities.js"
click node_guides "https://github.com/cognisphere-aiml-club/club_cognisphere/blob/master/src/data/gameGuides.js"
click node_activityfeed "https://github.com/cognisphere-aiml-club/club_cognisphere/blob/master/src/hooks/useActivities.js"
click node_landing "https://github.com/cognisphere-aiml-club/club_cognisphere/blob/master/src/components/EventLandingPage.jsx"
click node_gamedetail "https://github.com/cognisphere-aiml-club/club_cognisphere/blob/master/src/components/GameDetailPage.jsx"
click node_registration "https://github.com/cognisphere-aiml-club/club_cognisphere/blob/master/src/components/RegistrationModal.jsx"
click node_pass "https://github.com/cognisphere-aiml-club/club_cognisphere/blob/master/src/components/ParticipantPass.jsx"
click node_scanner "https://github.com/cognisphere-aiml-club/club_cognisphere/blob/master/src/components/CoordinatorScanner.jsx"
click node_attendance "https://github.com/cognisphere-aiml-club/club_cognisphere/blob/master/src/services/attendanceService.js"
click node_passes "https://github.com/cognisphere-aiml-club/club_cognisphere/blob/master/src/services/passApprovalService.js"
click node_registrations "https://github.com/cognisphere-aiml-club/club_cognisphere/blob/master/src/components/RegistrationsHub.jsx"
click node_scores "https://github.com/cognisphere-aiml-club/club_cognisphere/blob/master/src/services/scoreService.js"
click node_leaderboard "https://github.com/cognisphere-aiml-club/club_cognisphere/blob/master/src/components/LeaderboardPage.jsx"
click node_timers "https://github.com/cognisphere-aiml-club/club_cognisphere/blob/master/src/hooks/useSharedTimer.js"
click node_bigscreen "https://github.com/cognisphere-aiml-club/club_cognisphere/blob/master/src/components/BigScreenView.jsx"
click node_announcements "https://github.com/cognisphere-aiml-club/club_cognisphere/blob/master/src/hooks/useAnnouncements.js"
click node_certificates "https://github.com/cognisphere-aiml-club/club_cognisphere/blob/master/src/components/CertificatesView.jsx"
click node_sheetsbatch "https://github.com/cognisphere-aiml-club/club_cognisphere/blob/master/src/services/sheetsBatchSyncService.js"
click node_sheets "https://github.com/cognisphere-aiml-club/club_cognisphere/blob/master/src/services/googleSheetsService.js"
click node_firebase "https://github.com/cognisphere-aiml-club/club_cognisphere/blob/master/src/firebase.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_auth,node_profile,node_profileui toneBlue
class node_activities,node_guides,node_activityfeed,node_landing,node_gamedetail,node_registration,node_pass toneAmber
class node_scanner,node_attendance,node_passes,node_registrations,node_scores,node_leaderboard,node_timers,node_bigscreen,node_announcements,node_certificates,node_sheetsbatch,node_sheets toneMint
class node_app,node_firebase,node_firestore toneRose
class node_participant,node_coordinator toneIndigo
```

## Components

### Access and profiles

- [Sign-in and roles](https://github.com/cognisphere-aiml-club/club_cognisphere/blob/master/src/contexts/AuthContext.jsx): `src/contexts/AuthContext.jsx`
- [Participant profile](https://github.com/cognisphere-aiml-club/club_cognisphere/blob/master/src/hooks/useParticipantProfile.js): `src/hooks/useParticipantProfile.js`
- [Profile management](https://github.com/cognisphere-aiml-club/club_cognisphere/blob/master/src/components/ProfileEditPage.jsx): `src/components/ProfileEditPage.jsx`

### Activities and participation

- [Activity catalog](https://github.com/cognisphere-aiml-club/club_cognisphere/blob/master/src/data/activities.js): `src/data/activities.js`
- [Game guides](https://github.com/cognisphere-aiml-club/club_cognisphere/blob/master/src/data/gameGuides.js): `src/data/gameGuides.js`
- [Activity updates](https://github.com/cognisphere-aiml-club/club_cognisphere/blob/master/src/hooks/useActivities.js): `src/hooks/useActivities.js`
- [Event landing](https://github.com/cognisphere-aiml-club/club_cognisphere/blob/master/src/components/EventLandingPage.jsx): `src/components/EventLandingPage.jsx`
- [Game details](https://github.com/cognisphere-aiml-club/club_cognisphere/blob/master/src/components/GameDetailPage.jsx): `src/components/GameDetailPage.jsx`
- [Registration](https://github.com/cognisphere-aiml-club/club_cognisphere/blob/master/src/components/RegistrationModal.jsx): `src/components/RegistrationModal.jsx`
- [Participant pass](https://github.com/cognisphere-aiml-club/club_cognisphere/blob/master/src/components/ParticipantPass.jsx): `src/components/ParticipantPass.jsx`

### Event operations

- [Attendance scanner](https://github.com/cognisphere-aiml-club/club_cognisphere/blob/master/src/components/CoordinatorScanner.jsx): `src/components/CoordinatorScanner.jsx`
- [Attendance records](https://github.com/cognisphere-aiml-club/club_cognisphere/blob/master/src/services/attendanceService.js): `src/services/attendanceService.js`
- [Pass approvals](https://github.com/cognisphere-aiml-club/club_cognisphere/blob/master/src/services/passApprovalService.js): `src/services/passApprovalService.js`
- [Registration oversight](https://github.com/cognisphere-aiml-club/club_cognisphere/blob/master/src/components/RegistrationsHub.jsx): `src/components/RegistrationsHub.jsx`
- [Scoring service](https://github.com/cognisphere-aiml-club/club_cognisphere/blob/master/src/services/scoreService.js): `src/services/scoreService.js`
- [Leaderboard](https://github.com/cognisphere-aiml-club/club_cognisphere/blob/master/src/components/LeaderboardPage.jsx): `src/components/LeaderboardPage.jsx`
- [Shared timers](https://github.com/cognisphere-aiml-club/club_cognisphere/blob/master/src/hooks/useSharedTimer.js): `src/hooks/useSharedTimer.js`
- [Big-screen display](https://github.com/cognisphere-aiml-club/club_cognisphere/blob/master/src/components/BigScreenView.jsx): `src/components/BigScreenView.jsx`
- [Announcement feed](https://github.com/cognisphere-aiml-club/club_cognisphere/blob/master/src/hooks/useAnnouncements.js): `src/hooks/useAnnouncements.js`
- [Certificates](https://github.com/cognisphere-aiml-club/club_cognisphere/blob/master/src/components/CertificatesView.jsx): `src/components/CertificatesView.jsx`
- [Sheet batch sync](https://github.com/cognisphere-aiml-club/club_cognisphere/blob/master/src/services/sheetsBatchSyncService.js): `src/services/sheetsBatchSyncService.js`
- [Google Sheets sync](https://github.com/cognisphere-aiml-club/club_cognisphere/blob/master/src/services/googleSheetsService.js): `src/services/googleSheetsService.js`

### Shared platform

- [App shell](https://github.com/cognisphere-aiml-club/club_cognisphere/blob/master/src/App.jsx): `src/App.jsx`
- [Firebase setup](https://github.com/cognisphere-aiml-club/club_cognisphere/blob/master/src/firebase.js): `src/firebase.js`
- **Firestore**

### Other components

- **Participant**
- **Coordinator**

## Connections

- Participant → App shell: uses (evidence: `src/App.jsx`)
- Coordinator → App shell: uses (evidence: `src/App.jsx`)
- App shell → Sign-in and roles: reads auth state (evidence: `src/App.jsx`)
- App shell → Participant profile: loads profile (evidence: `src/App.jsx`)
- App shell → Activity updates: loads activities (evidence: `src/App.jsx`)
- App shell → Registration: opens (evidence: `src/App.jsx`)
- App shell → Participant pass: shows (evidence: `src/App.jsx`)
- App shell → Attendance scanner: routes to (evidence: `src/App.jsx`)
- App shell → Event landing: routes to (evidence: `src/App.jsx`)
- App shell → Game details: routes to (evidence: `src/App.jsx`)
- App shell → Registration oversight: routes to (evidence: `src/App.jsx`)
- App shell → Shared timers: routes to (evidence: `src/App.jsx`)
- App shell → Big-screen display: routes to (evidence: `src/App.jsx`)
- App shell → Certificates: routes to (evidence: `src/App.jsx`)
- App shell → Profile management: routes to (evidence: `src/App.jsx`)
- Profile management → Participant profile: uses (evidence: `src/components/ProfileEditPage.jsx`)
- Activity updates → Activity catalog: falls back to (evidence: `src/hooks/useActivities.js`)
- Activity catalog → Game guides: uses guide data (evidence: `src/data/activities.js`)
- Event landing → Pass approvals: uses (evidence: `src/components/EventLandingPage.jsx`)
- Game details → Pass approvals: uses (evidence: `src/components/GameDetailPage.jsx`)
- Participant pass → Pass approvals: uses (evidence: `src/components/ParticipantPass.jsx`)
- Participant pass → Attendance records: checks attendance (evidence: `src/components/ParticipantPass.jsx`)
- Attendance scanner → Attendance records: records attendance (evidence: `src/components/CoordinatorScanner.jsx`)
- Registration oversight → Pass approvals: uses (evidence: `src/components/RegistrationsHub.jsx`)
- Registration oversight → Attendance records: uses (evidence: `src/components/RegistrationsHub.jsx`)
- Registration oversight → Sheet batch sync: syncs batches (evidence: `src/components/RegistrationsHub.jsx`)
- Leaderboard → Scoring service: loads scores (evidence: `src/components/LeaderboardPage.jsx`)
- Big-screen display → Scoring service: uses (evidence: `src/components/BigScreenView.jsx`)
- Big-screen display → Pass approvals: uses (evidence: `src/components/BigScreenView.jsx`)
- Big-screen display → Shared timers: uses (evidence: `src/components/BigScreenView.jsx`)
- Big-screen display → Announcement feed: uses (evidence: `src/components/BigScreenView.jsx`)
- Certificates → Activity catalog: uses (evidence: `src/components/CertificatesView.jsx`)
- Sheet batch sync → Google Sheets sync: delegates to (evidence: `src/services/sheetsBatchSyncService.js`)
- Sign-in and roles → Firebase setup: uses (evidence: `src/contexts/AuthContext.jsx`)
- Participant profile → Firebase setup: uses (evidence: `src/hooks/useParticipantProfile.js`)
- Firebase setup → Firestore: initializes (evidence: `src/firebase.js`)
- Attendance records → Firestore: reads and writes (evidence: `src/services/attendanceService.js`)
- Pass approvals → Firestore: reads and writes (evidence: `src/services/passApprovalService.js`)
- Scoring service → Firestore: uses (evidence: `src/services/scoreService.js`)
- Shared timers → Firestore: reads and writes (evidence: `src/hooks/useSharedTimer.js`)
- Google Sheets sync → Firestore: reads and writes (evidence: `src/services/googleSheetsService.js`)
