How kmsumanth23/nitrr-clubs works
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: queries Queries · actions Actions · supabase Supabase clients · (student) Student
Components 19
App routes
Next.js App Router boundaries for public, student, admin, and auth flows.
- Marketing · Public browsing experience for clubs, events, gallery, and homepage content.
app/(marketing) - Student · Authenticated student flows for profile and applications.
app/(student) - Admin · Administrative console split into club-level and sysadmin operations.
app/(admin) - Auth routes · Auth callback and sign-out handlers.
app/auth - Proxy · Request-time session handling and route protection.
proxy.ts
UI components
Feature-oriented React components used by the route tree.
- Discovery UI · Homepage sections plus club, event, and gallery browsing components.
components/sections - Student UI · Profile completion, edit, application history, and apply form components.
components/profile - Admin UI · Shared admin shell, tables, modals, forms, bulk tools, and operational widgets.
components/admin - Club UI · Club cards, filters, and application form used across public and student flows.
components/clubs - 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 · Server-side read layer for marketing, profile, admin, export, and diagnostics data.
lib/queries - Actions · Mutation layer for applications, clubs, members, events, gallery, sysadmin, and recompute flows.
lib/actions - Validation · Input and workflow validation across the mutation surface.
lib/validation - Supabase clients · Server, client, middleware, and static Supabase access variants.
lib/supabase - Storage · Gallery upload and image processing support.
lib/storage - Audit · Categorization and formatting for audit history views.
lib/audit
Database & ops
Supabase schema, RLS, and deployment/automation assets.
- Schema & RLS · Canonical schema, row-level security, roles, deadlines, recruitments, gallery, audit, and repair logic.
supabase - Preflight SQL · Deployment-time database setup and checks.
scripts/preflight.sql - CI/CD · GitHub Actions and deployment guidance for verification and release.
.github/workflows/ci.yml
Connections 23
- 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.