# kmsumanth23/nitrr-clubs architecture

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

- Interactive diagram: https://gitdiagram.com/kmsumanth23/nitrr-clubs
- Repository: https://github.com/kmsumanth23/nitrr-clubs

## Overview

1. **Overall shape**
   - This is a **Next.js 16 App Router** application with a mostly monolithic architecture: UI, server rendering, server actions, and API route handlers all live in the same repo.
   - The system is organized around three user-facing domains: **marketing/public browsing**, **student self-service**, and **admin/sysadmin operations**.

2. **Route boundaries in `app/`**
   - `app/(marketing)` contains the public site: homepage, club listings, event listings, gallery, and detail pages.
   - `app/(student)` contains authenticated student flows: profile, profile completion, and club application.
   - `app/(admin)` contains the admin console, split into per-club management and sysadmin governance.
   - `app/auth` handles the auth callback and sign-out routes.
   - These route groups are the main architectural boundary for permissions and UX separation.

3. **Auth and session flow**
   - Authentication is built on **Supabase Auth**.
   - The sign-in lifecycle flows through `app/auth/callback/route.ts`, with sign-out in `app/auth/signout/route.ts`.
   - `proxy.ts` acts as the middleware layer for request-time session handling and route protection.
   - The repo also has multiple Supabase client variants in `lib/supabase/` for **server**, **client**, **middleware**, and **static** contexts.

4. **Data access pattern**
   - Read paths are concentrated in `lib/queries/`, which provides server-side data fetching for each domain.
   - Write paths are concentrated in `lib/actions/`, which contains server actions for mutations such as applications, clubs, members, events, gallery, categories, profile, recruitment, and sysadmin tasks.
   - This creates a clear split: **queries for reads**, **actions for writes**.
   - Most business rules are enforced through **Supabase RLS** rather than a separate backend service.

5. **Database and authority model**
   - The database is managed directly through SQL migrations in `supabase/`.
   - The schema is split into numbered migration files for roles, deadlines, review phases, recruitments, gallery, audit, recompute logic, and deletion behavior.
   - The architecture depends heavily on **Postgres + RLS** as the authority boundary; the app is designed so authenticated queries operate under the current user’s permissions.

6. **Admin and sysadmin subsystems**
   - The admin area is further divided into:
     - **club-level administration** under `app/(admin)/admin/clubs/[slug]`
     - **system administration** under `app/(admin)/admin/sysadmin`
   - Club admins manage applications, members, events, gallery, admins, recruitment, and audit logs for a single club.
   - Sysadmins manage cross-system concerns like club creation, categories, FAQs, storage, exports, bulk import, archived clubs, diagnostics, and super-admins.
   - This is the clearest “two-tier” operational boundary in the repo.

7. **Student workflow**
   - Student-side flows center on profile management and club applications.
   - `components/profile/` and `lib/actions/profile.ts` support profile completion and editing.
   - `components/clubs/apply-form.tsx` and `lib/actions/application.ts` handle applications into clubs.
   - The student profile also serves as the aggregation point for application history and club membership visibility.

8. **Public discovery layer**
   - The marketing area exposes club discovery, event browsing, gallery browsing, and homepage sections such as hero, stats, FAQ, socials, and call-to-action.
   - `components/sections/` contains the homepage composition pieces, while `components/clubs/`, `components/events`, and `components/gallery/` provide list/detail UI.
   - Public pages are likely fed from read-only query modules and are optimized for anonymous access.

9. **Media and storage**
   - Gallery images are handled through `lib/storage/gallery.ts` and image resizing utilities in `lib/image/resize.ts`.
   - The presence of storage usage queries and sysadmin storage pages indicates that media is treated as a first-class operational concern.
   - Supabase Storage is the likely backing store for uploaded media, with metadata surfaced in gallery and admin tools.

10. **Export/import and bulk ops**
   - The system supports operational data movement through dedicated route handlers under `app/(admin)/admin/api/export/*` and `.../import/template`.
   - CSV formatting/parsing lives in `lib/csv/`, which supports exports like admins, members, and club rosters.
   - There is also a bulk-import flow in both sysadmin UI and server actions, suggesting the app is designed for institutional onboarding and migration tasks.

11. **Audit, compliance, and recomputation**
   - Audit logging is a distinct subsystem in `lib/audit/` with dedicated admin views and query modules.
   - Recompute actions and counter-drift queries indicate the app maintains some denormalized or derived state that can be repaired from source data.
   - This suggests a design where operational correctness is important enough to expose repair, review, and history tooling.

12. **UI composition and implementation style**
   - The UI is componentized by feature area: `components/admin`, `components/profile`, `components/sections`, `components/layout`, and `components/ui`.
   - Many admin screens are form-and-table driven, with modal-based editing and bulk actions.
   - The project uses **React 19**, **TypeScript**, and **Tailwind CSS**, with server components and `useActionState`-style patterns implied by the stack.

13. **Operational tooling**
   - CI is handled by **GitHub Actions**.
   - Deployment targets **Vercel**, with `DEPLOY.md` documenting release steps and smoke testing.
   - `scripts/preflight.sql` and the numbered SQL files indicate database setup is part of the deployment story, not an afterthought.

14. **Key architectural takeaway**
   - The repo is a **Supabase-backed Next.js monolith** with strong domain separation in the route tree and clear read/write boundaries in `lib/queries` and `lib/actions`.
   - Authorization is primarily enforced by **Supabase RLS**, while the app layer provides workflow orchestration, validation, UI, exports, and admin tooling.

Main entry points: [`lib/queries`](https://github.com/kmsumanth23/nitrr-clubs/tree/master/lib/queries) (Queries), [`lib/actions`](https://github.com/kmsumanth23/nitrr-clubs/tree/master/lib/actions) (Actions), [`lib/supabase`](https://github.com/kmsumanth23/nitrr-clubs/tree/master/lib/supabase) (Supabase clients), [`app/(student)`](https://github.com/kmsumanth23/nitrr-clubs/tree/master/app/(student)) (Student)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_routes["App routes"]
  node_app_marketing["Marketing<br/>route group"]
  node_app_student["Student<br/>route group"]
  node_app_admin["Admin<br/>route group"]
  node_app_auth["Auth routes"]
  node_proxy{{"Proxy<br/>middleware<br/>[proxy.ts]"}}
end

subgraph group_ui["UI components"]
  node_marketing_ui["Discovery UI<br/>public UI"]
  node_student_ui["Student UI"]
  node_admin_ui["Admin UI"]
  node_club_ui["Club UI"]
  node_gallery_ui["Gallery UI"]
end

subgraph group_domain["Domain logic"]
  node_queries[("Queries<br/>read models")]
  node_actions[("Actions")]
  node_validation["Validation<br/>schemas"]
  node_supabase[("Supabase clients<br/>client adapters")]
  node_storage[("Storage<br/>media layer")]
  node_audit["Audit"]
end

subgraph group_data["Database & ops"]
  node_supabase_sql[("Schema & RLS<br/>sql migrations")]
  node_scripts["Preflight SQL<br/>deployment sql<br/>[preflight.sql]"]
  node_ci["CI/CD<br/>automation<br/>[ci.yml]"]
end

node_proxy -->|"session"| node_supabase
node_app_auth -->|"auth"| node_supabase
node_app_marketing -->|"reads"| node_queries
node_app_student -->|"reads"| node_queries
node_app_student -->|"writes"| node_actions
node_app_admin -->|"reads"| node_queries
node_app_admin -->|"writes"| node_actions
node_actions -->|"checks"| node_validation
node_queries -->|"data access"| node_supabase
node_actions -->|"mutations"| node_supabase
node_queries -->|"schema"| node_supabase_sql
node_actions -->|"authority"| node_supabase_sql
node_storage -->|"files"| node_supabase
node_audit -->|"views"| node_queries
node_marketing_ui -->|"renders"| node_app_marketing
node_student_ui -->|"renders"| node_app_student
node_admin_ui -->|"renders"| node_app_admin
node_club_ui -.->|"supports"| node_app_marketing
node_club_ui -.->|"supports"| node_app_student
node_gallery_ui -.->|"supports"| node_app_marketing
node_admin_ui -.->|"shows"| node_audit
node_supabase_sql -.->|"setup"| node_scripts
node_ci -.->|"verifies"| node_supabase_sql

click node_app_marketing "https://github.com/kmsumanth23/nitrr-clubs/tree/master/app/(marketing)"
click node_app_student "https://github.com/kmsumanth23/nitrr-clubs/tree/master/app/(student)"
click node_app_admin "https://github.com/kmsumanth23/nitrr-clubs/tree/master/app/(admin)"
click node_app_auth "https://github.com/kmsumanth23/nitrr-clubs/tree/master/app/auth"
click node_proxy "https://github.com/kmsumanth23/nitrr-clubs/blob/master/proxy.ts"
click node_queries "https://github.com/kmsumanth23/nitrr-clubs/tree/master/lib/queries"
click node_actions "https://github.com/kmsumanth23/nitrr-clubs/tree/master/lib/actions"
click node_validation "https://github.com/kmsumanth23/nitrr-clubs/tree/master/lib/validation"
click node_supabase "https://github.com/kmsumanth23/nitrr-clubs/tree/master/lib/supabase"
click node_storage "https://github.com/kmsumanth23/nitrr-clubs/tree/master/lib/storage"
click node_audit "https://github.com/kmsumanth23/nitrr-clubs/tree/master/lib/audit"
click node_marketing_ui "https://github.com/kmsumanth23/nitrr-clubs/tree/master/components/sections"
click node_student_ui "https://github.com/kmsumanth23/nitrr-clubs/tree/master/components/profile"
click node_admin_ui "https://github.com/kmsumanth23/nitrr-clubs/tree/master/components/admin"
click node_club_ui "https://github.com/kmsumanth23/nitrr-clubs/tree/master/components/clubs"
click node_gallery_ui "https://github.com/kmsumanth23/nitrr-clubs/tree/master/components/gallery"
click node_supabase_sql "https://github.com/kmsumanth23/nitrr-clubs/tree/master/supabase"
click node_scripts "https://github.com/kmsumanth23/nitrr-clubs/blob/master/scripts/preflight.sql"
click node_ci "https://github.com/kmsumanth23/nitrr-clubs/blob/master/.github/workflows/ci.yml"

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_app_marketing,node_app_student,node_app_admin,node_app_auth,node_proxy toneBlue
class node_marketing_ui,node_student_ui,node_admin_ui,node_club_ui,node_gallery_ui toneAmber
class node_queries,node_actions,node_validation,node_supabase,node_storage,node_audit toneMint
class node_supabase_sql,node_scripts,node_ci toneRose
```

## Components

### App routes

Next.js App Router boundaries for public, student, admin, and auth flows.

- [Marketing](https://github.com/kmsumanth23/nitrr-clubs/tree/master/app/(marketing)): route group · Public browsing experience for clubs, events, gallery, and homepage content. · `app/(marketing)`
- [Student](https://github.com/kmsumanth23/nitrr-clubs/tree/master/app/(student)): route group · Authenticated student flows for profile and applications. · `app/(student)`
- [Admin](https://github.com/kmsumanth23/nitrr-clubs/tree/master/app/(admin)): route group · Administrative console split into club-level and sysadmin operations. · `app/(admin)`
- [Auth routes](https://github.com/kmsumanth23/nitrr-clubs/tree/master/app/auth): auth routes · Auth callback and sign-out handlers. · `app/auth`
- [Proxy](https://github.com/kmsumanth23/nitrr-clubs/blob/master/proxy.ts): middleware · Request-time session handling and route protection. · `proxy.ts`

### UI components

Feature-oriented React components used by the route tree.

- [Discovery UI](https://github.com/kmsumanth23/nitrr-clubs/tree/master/components/sections): public UI · Homepage sections plus club, event, and gallery browsing components. · `components/sections`
- [Student UI](https://github.com/kmsumanth23/nitrr-clubs/tree/master/components/profile): student UI · Profile completion, edit, application history, and apply form components. · `components/profile`
- [Admin UI](https://github.com/kmsumanth23/nitrr-clubs/tree/master/components/admin): admin UI · Shared admin shell, tables, modals, forms, bulk tools, and operational widgets. · `components/admin`
- [Club UI](https://github.com/kmsumanth23/nitrr-clubs/tree/master/components/clubs): club UI · Club cards, filters, and application form used across public and student flows. · `components/clubs`
- [Gallery UI](https://github.com/kmsumanth23/nitrr-clubs/tree/master/components/gallery): gallery UI · Gallery grid used by public browsing and admin management. · `components/gallery`

### Domain logic

Server-side reads, writes, validation, storage, and auth/session helpers.

- [Queries](https://github.com/kmsumanth23/nitrr-clubs/tree/master/lib/queries): read models · Server-side read layer for marketing, profile, admin, export, and diagnostics data. · `lib/queries`
- [Actions](https://github.com/kmsumanth23/nitrr-clubs/tree/master/lib/actions): server actions · Mutation layer for applications, clubs, members, events, gallery, sysadmin, and recompute flows. · `lib/actions`
- [Validation](https://github.com/kmsumanth23/nitrr-clubs/tree/master/lib/validation): schemas · Input and workflow validation across the mutation surface. · `lib/validation`
- [Supabase clients](https://github.com/kmsumanth23/nitrr-clubs/tree/master/lib/supabase): client adapters · Server, client, middleware, and static Supabase access variants. · `lib/supabase`
- [Storage](https://github.com/kmsumanth23/nitrr-clubs/tree/master/lib/storage): media layer · Gallery upload and image processing support. · `lib/storage`
- [Audit](https://github.com/kmsumanth23/nitrr-clubs/tree/master/lib/audit): audit helpers · Categorization and formatting for audit history views. · `lib/audit`

### Database & ops

Supabase schema, RLS, and deployment/automation assets.

- [Schema & RLS](https://github.com/kmsumanth23/nitrr-clubs/tree/master/supabase): sql migrations · Canonical schema, row-level security, roles, deadlines, recruitments, gallery, audit, and repair logic. · `supabase`
- [Preflight SQL](https://github.com/kmsumanth23/nitrr-clubs/blob/master/scripts/preflight.sql): deployment sql · Deployment-time database setup and checks. · `scripts/preflight.sql`
- [CI/CD](https://github.com/kmsumanth23/nitrr-clubs/blob/master/.github/workflows/ci.yml): automation · GitHub Actions and deployment guidance for verification and release. · `.github/workflows/ci.yml`

## Connections

- Proxy → Supabase clients: session · Middleware uses the Supabase middleware client to resolve user context.
- Auth routes → Supabase clients: auth · Callback and sign-out routes complete Supabase Auth flows.
- Marketing → Queries: reads · Public pages are powered by read-only query modules.
- Student → Queries: reads · Student screens load profile and application state through queries.
- Student → Actions: writes · Profile completion and club applications submit server actions.
- Admin → Queries: reads · Admin dashboards consume club, sysadmin, audit, and export views.
- Admin → Actions: writes · Admin screens trigger club operations, sysadmin tasks, and bulk actions.
- Actions → Validation: checks · Mutations validate inputs and workflow constraints before persisting.
- Queries → Supabase clients: data access · Read paths query Supabase/Postgres under the current permission model.
- Actions → Supabase clients: mutations · Server actions persist changes through Supabase clients.
- Queries → Schema & RLS: schema · Query shapes depend on the migration-defined database schema and RLS.
- Actions → Schema & RLS: authority · Writes are constrained by RLS and database-side rules.
- Storage → Supabase clients: files · Gallery storage operations are backed by Supabase storage access.
- Audit → Queries: views · Audit formatting and categorization feed dedicated read models.
- Discovery UI → Marketing: renders · Homepage and discovery components compose public route pages.
- Student UI → Student: renders · Profile and application components compose student pages.
- Admin UI → Admin: renders · Admin shells, tables, forms, and actions compose console pages.
- Club UI → Marketing: supports · Club discovery UI is reused by public browsing routes.
- Club UI → Student: supports · Club application UI supports authenticated student flows.
- Gallery UI → Marketing: supports · Gallery browsing components back the public gallery route.
- Admin UI → Audit: shows · Admin views surface audit logs and anomaly diagnostics.
- Schema & RLS → Preflight SQL: setup · Preflight SQL complements the migration-based database setup.
- CI/CD → Schema & RLS: verifies · CI and deployment process depend on schema and migration correctness.