# codeshul/vit_clubs architecture

> Architecture diagram of the GitHub repository codeshul/vit_clubs, 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/codeshul/vit_clubs
- Repository: https://github.com/codeshul/vit_clubs

## Overview

VIT Clubs is a campus club and event management platform. Students discover clubs and events, register for events, and use a personal portal; club admins manage events and members; super admins review event approvals and manage the wider system. The main event flow runs from public event views through shared event state and server actions to persistence, with domain validation supporting business rules. Authentication, notifications, club discovery, calendars, and permission-letter verification are separate capabilities. Several portal and notification implementations were not sampled, so those branches reflect documented capabilities rather than inspected call details.

Main entry points: [`src/lib/events-context.tsx`](https://github.com/codeshul/vit_clubs/blob/main/src/lib/events-context.tsx) (Event state), [`src/app/actions/events.ts`](https://github.com/codeshul/vit_clubs/blob/main/src/app/actions/events.ts) (Event actions), [`src/lib/db.ts`](https://github.com/codeshul/vit_clubs/blob/main/src/lib/db.ts) (Prisma client), [`src/app/events/[id]/page.tsx`](https://github.com/codeshul/vit_clubs/blob/main/src/app/events/%5Bid%5D/page.tsx) (Event details)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Discovery and portals"]
  node_public_events["Event discovery<br/>[page.tsx]"]
  node_event_detail["Event details<br/>[page.tsx]"]
  node_calendar["Event calendar<br/>[page.tsx]"]
  node_student_portal["Student portal<br/>[page.tsx]"]
  node_admin_portal["Club admin portal<br/>[page.tsx]"]
  node_super_portal["Super admin portal<br/>[page.tsx]"]
end

subgraph group_event_ops["Event operations"]
  node_event_state["Event state<br/>[events-context.tsx]"]
  node_event_actions["Event actions<br/>[events.ts]"]
  node_approval_views["Approval workflows<br/>[page.tsx]"]
  node_verification["Letter verification<br/>[page.tsx]"]
end

subgraph group_identity["Identity and access"]
  node_login["Login modal<br/>[LoginModal.tsx]"]
  node_auth_state["Auth context<br/>[auth-context.tsx]"]
  node_auth_route["Credentials auth<br/>[route.ts]"]
  node_route_security["Route protection<br/>[middleware.ts]"]
end

subgraph group_domain_data["Domain and persistence"]
  node_domain_model["Domain model<br/>[domain.ts]"]
  node_database_client["Prisma client<br/>[db.ts]"]
  node_database[("PostgreSQL")]
end

subgraph group_support["Club and notifications"]
  node_club_explorer["Club discovery<br/>[ClubExplorer.tsx]"]
  node_club_actions["Club actions<br/>[clubs.ts]"]
  node_notifications["Notifications"]
  node_mock_data["Fallback data<br/>[mock-data.ts]"]
end

node_student(("Student"))
node_club_admin(("Club admin"))
node_super_admin(("Super admin"))

node_student -->|"browses"| node_public_events
node_student -->|"opens event"| node_event_detail
node_student -->|"views calendar"| node_calendar
node_student -->|"uses portal"| node_student_portal
node_club_admin -->|"manages club"| node_admin_portal
node_super_admin -->|"manages system"| node_super_portal
node_public_events -->|"reads events"| node_event_state
node_event_detail -->|"reads event"| node_event_state
node_event_detail -->|"registers"| node_event_actions
node_calendar -->|"reads events"| node_event_state
node_event_state -->|"loads and mutates"| node_event_actions
node_admin_portal -->|"uses events"| node_event_state
node_super_portal -->|"uses events"| node_event_state
node_approval_views -.->|"reviews events"| node_event_state
node_event_actions -->|"persists events"| node_database_client
node_event_actions -->|"validates entities"| node_domain_model
node_database_client -.->|"accesses"| node_database
node_login -->|"starts login"| node_auth_state
node_auth_state -.->|"credentials sign-in"| node_auth_route
node_auth_route -->|"looks up users"| node_database_client
node_auth_route -->|"validates user"| node_domain_model
node_route_security -->|"protects routes"| node_student_portal
node_club_explorer -->|"reads clubs"| node_mock_data
node_club_actions -->|"persists clubs"| node_database_client
node_club_actions -->|"uses entities"| node_domain_model
node_notifications -.->|"alerts users"| node_student_portal
node_event_actions -.->|"issues letter tokens"| node_verification

click node_public_events "https://github.com/codeshul/vit_clubs/blob/main/src/app/events/page.tsx"
click node_event_detail "https://github.com/codeshul/vit_clubs/blob/main/src/app/events/%5Bid%5D/page.tsx"
click node_calendar "https://github.com/codeshul/vit_clubs/blob/main/src/app/calendar/page.tsx"
click node_student_portal "https://github.com/codeshul/vit_clubs/blob/main/src/app/portal/user/page.tsx"
click node_admin_portal "https://github.com/codeshul/vit_clubs/blob/main/src/app/portal/admin/page.tsx"
click node_super_portal "https://github.com/codeshul/vit_clubs/blob/main/src/app/portal/super-admin/page.tsx"
click node_event_state "https://github.com/codeshul/vit_clubs/blob/main/src/lib/events-context.tsx"
click node_event_actions "https://github.com/codeshul/vit_clubs/blob/main/src/app/actions/events.ts"
click node_approval_views "https://github.com/codeshul/vit_clubs/blob/main/src/app/portal/super-admin/approvals/page.tsx"
click node_verification "https://github.com/codeshul/vit_clubs/blob/main/src/app/verify/%5Btoken%5D/page.tsx"
click node_login "https://github.com/codeshul/vit_clubs/blob/main/src/components/auth/LoginModal.tsx"
click node_auth_state "https://github.com/codeshul/vit_clubs/blob/main/src/lib/auth-context.tsx"
click node_auth_route "https://github.com/codeshul/vit_clubs/blob/main/src/app/api/auth/%5B...nextauth%5D/route.ts"
click node_route_security "https://github.com/codeshul/vit_clubs/blob/main/src/middleware.ts"
click node_domain_model "https://github.com/codeshul/vit_clubs/blob/main/src/lib/domain.ts"
click node_database_client "https://github.com/codeshul/vit_clubs/blob/main/src/lib/db.ts"
click node_club_explorer "https://github.com/codeshul/vit_clubs/blob/main/src/components/shared/ClubExplorer.tsx"
click node_club_actions "https://github.com/codeshul/vit_clubs/blob/main/src/app/actions/clubs.ts"
click node_notifications "https://github.com/codeshul/vit_clubs/blob/main/src/lib/notifications-context.tsx"
click node_mock_data "https://github.com/codeshul/vit_clubs/blob/main/src/lib/mock-data.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_public_events,node_event_detail,node_calendar,node_student_portal,node_admin_portal,node_super_portal toneBlue
class node_event_state,node_event_actions,node_approval_views,node_verification toneAmber
class node_login,node_auth_state,node_auth_route,node_route_security toneMint
class node_domain_model,node_database_client,node_database toneRose
class node_club_explorer,node_club_actions,node_notifications,node_mock_data,node_student,node_club_admin,node_super_admin toneIndigo
```

## Components

### Discovery and portals

- [Event discovery](https://github.com/codeshul/vit_clubs/blob/main/src/app/events/page.tsx): `src/app/events/page.tsx`
- [Event details](https://github.com/codeshul/vit_clubs/blob/main/src/app/events/%5Bid%5D/page.tsx): `src/app/events/[id]/page.tsx`
- [Event calendar](https://github.com/codeshul/vit_clubs/blob/main/src/app/calendar/page.tsx): `src/app/calendar/page.tsx`
- [Student portal](https://github.com/codeshul/vit_clubs/blob/main/src/app/portal/user/page.tsx): `src/app/portal/user/page.tsx`
- [Club admin portal](https://github.com/codeshul/vit_clubs/blob/main/src/app/portal/admin/page.tsx): `src/app/portal/admin/page.tsx`
- [Super admin portal](https://github.com/codeshul/vit_clubs/blob/main/src/app/portal/super-admin/page.tsx): `src/app/portal/super-admin/page.tsx`

### Event operations

- [Event state](https://github.com/codeshul/vit_clubs/blob/main/src/lib/events-context.tsx): `src/lib/events-context.tsx`
- [Event actions](https://github.com/codeshul/vit_clubs/blob/main/src/app/actions/events.ts): `src/app/actions/events.ts`
- [Approval workflows](https://github.com/codeshul/vit_clubs/blob/main/src/app/portal/super-admin/approvals/page.tsx): `src/app/portal/super-admin/approvals/page.tsx`
- [Letter verification](https://github.com/codeshul/vit_clubs/blob/main/src/app/verify/%5Btoken%5D/page.tsx): `src/app/verify/[token]/page.tsx`

### Identity and access

- [Login modal](https://github.com/codeshul/vit_clubs/blob/main/src/components/auth/LoginModal.tsx): `src/components/auth/LoginModal.tsx`
- [Auth context](https://github.com/codeshul/vit_clubs/blob/main/src/lib/auth-context.tsx): `src/lib/auth-context.tsx`
- [Credentials auth](https://github.com/codeshul/vit_clubs/blob/main/src/app/api/auth/%5B...nextauth%5D/route.ts): `src/app/api/auth/[...nextauth]/route.ts`
- [Route protection](https://github.com/codeshul/vit_clubs/blob/main/src/middleware.ts): `src/middleware.ts`

### Domain and persistence

- [Domain model](https://github.com/codeshul/vit_clubs/blob/main/src/lib/domain.ts): `src/lib/domain.ts`
- [Prisma client](https://github.com/codeshul/vit_clubs/blob/main/src/lib/db.ts): `src/lib/db.ts`
- **PostgreSQL**

### Club and notifications

- [Club discovery](https://github.com/codeshul/vit_clubs/blob/main/src/components/shared/ClubExplorer.tsx): `src/components/shared/ClubExplorer.tsx`
- [Club actions](https://github.com/codeshul/vit_clubs/blob/main/src/app/actions/clubs.ts): `src/app/actions/clubs.ts`
- [Notifications](https://github.com/codeshul/vit_clubs/blob/main/src/lib/notifications-context.tsx): `src/lib/notifications-context.tsx`
- [Fallback data](https://github.com/codeshul/vit_clubs/blob/main/src/lib/mock-data.ts): `src/lib/mock-data.ts`

### Other components

- **Student**
- **Club admin**
- **Super admin**

## Connections

- Student → Event discovery: browses (evidence: `README.md`)
- Student → Event details: opens event (evidence: `README.md`)
- Student → Event calendar: views calendar (evidence: `README.md`)
- Student → Student portal: uses portal (evidence: `README.md`)
- Club admin → Club admin portal: manages club (evidence: `README.md`)
- Super admin → Super admin portal: manages system (evidence: `README.md`)
- Event discovery → Event state: reads events (evidence: `src/app/events/page.tsx`)
- Event details → Event state: reads event (evidence: `src/app/events/[id]/page.tsx`)
- Event details → Event actions: registers (evidence: `src/app/events/[id]/page.tsx`)
- Event calendar → Event state: reads events (evidence: `src/lib/events-context.tsx`)
- Event state → Event actions: loads and mutates (evidence: `src/lib/events-context.tsx`)
- Club admin portal → Event state: uses events (evidence: `src/app/portal/admin/page.tsx`)
- Super admin portal → Event state: uses events (evidence: `src/app/portal/super-admin/page.tsx`)
- Approval workflows → Event state: reviews events (evidence: `README.md`)
- Event actions → Prisma client: persists events (evidence: `src/app/actions/events.ts`)
- Event actions → Domain model: validates entities (evidence: `src/app/actions/events.ts`)
- Prisma client → PostgreSQL: accesses (evidence: `README.md`)
- Login modal → Auth context: starts login (evidence: `src/components/auth/LoginModal.tsx`)
- Auth context → Credentials auth: credentials sign-in (evidence: `README.md`)
- Credentials auth → Prisma client: looks up users (evidence: `src/app/api/auth/[...nextauth]/route.ts`)
- Credentials auth → Domain model: validates user (evidence: `src/app/api/auth/[...nextauth]/route.ts`)
- Route protection → Student portal: protects routes (evidence: `README.md`)
- Club discovery → Fallback data: reads clubs (evidence: `src/components/shared/ClubExplorer.tsx`)
- Club actions → Prisma client: persists clubs (evidence: `src/app/actions/clubs.ts`)
- Club actions → Domain model: uses entities (evidence: `src/app/actions/clubs.ts`)
- Notifications → Student portal: alerts users (evidence: `README.md`)
- Event actions → Letter verification: issues letter tokens (evidence: `README.md`)
