eniamza/boracle

1. Top-level shape

- This is a Next.js 15 App Router application with a large client-facing product surface, an authenticated dashboard, and a substantial API layer.

- The backend is not separate in a traditional monolith sense; instead, the app mixes React server components, client components, route handlers, and server actions around a shared database.

2. Primary user-facing areas

- src/app/(main) contains the public/product experience: home page, changelog, contributors, and the core student tools.

- src/app/(dashboard) contains the authenticated workspace: user dashboard plus admin views for managing users, swaps, materials, and data import.

- This split is an important boundary for diagrams: public tooling vs signed-in operational/admin tooling.

3. Core product modules

- The main product features map cleanly to dedicated subsystems:

- PrePreReg for routine planning

- Routine / Merged Routine for viewing and combining schedules

- Course Swap for publishing and requesting swaps

- Gradesheet for academic planning/analysis

- Course Materials for sharing and browsing study resources

- ChickenCoop for live seat/status-style course info

- Most of these have both a route page and reusable feature components under src/components/....

4. API layer as the backend boundary

- All client/server data exchange flows through src/app/api/*.

- The API is grouped by domain: faculty, materials, routine, merged-routine, swap, reviews, gradesheet, home/stats, dashboard/*, and services.

- Admin-specific operations are isolated under api/admin/*, which is where imports and moderation actions likely terminate.

5. Authentication and access control

- Authentication is handled through NextAuth at src/app/api/[...nextauth]/route.js, with auth configuration in src/auth.js.

- src/app/middleware.js suggests route protection and/or session-based gating at the edge.

- The README notes Google OAuth and a restriction to BRACU emails, which is a meaningful policy boundary for the architecture.

6. Database and persistence

- The persistent system of record is Supabase PostgreSQL, with schema managed through Drizzle ORM.

- Database schema definitions live in src/lib/db/schema/*, and the repo also includes supabase/migrations/*, showing a migration-driven persistence model.

- The schema covers entities such as users, faculty, reviews, course materials, swap requests, votes, targets, saved routines, merged routines, services, and moderation tables.

7. File/material storage path

- Course materials appear to involve object storage rather than only relational data.

- src/lib/r2.js, the materials/presign API route, and the separate r2-worker/ package indicate a Cloudflare R2-backed upload/download flow.

- In architecture terms, this is a distinct storage subsystem: metadata in Postgres, binary content in R2.

8. Dashboard and analytics data

- The dashboard is fed by dedicated read endpoints like dashboard/recentActivity, dashboard/userStatCount, and home/stats.

- Components like recentActivity, userStats, and welcome show the dashboard is a summary/ops layer rather than just navigation.

- This suggests a pattern of server-fetched summary data rendered into dashboard widgets.

9. Shared UI and composition

- The app uses a shared component library in src/components/ui/*, built around Radix UI / shadcn-style primitives.

- Feature-specific UI is organized by domain, while cross-cutting chrome lives in navbar, sidebar, theme provider, sign-in/out buttons, and shared prompts.

- Route-level layouts under src/app/(main) and src/app/(dashboard) define the shell composition for those two major experiences.

10. Client/server interaction model

- Many page folders contain page.jsx plus ClientPage.jsx or similarly named client-only entry points, implying a hybrid rendering model.

- Server components likely fetch initial data and pass it to client islands for interactivity such as selectors, modal flows, voting, uploads, and schedule manipulation.

- This boundary is important: heavy interactivity is localized in feature components, while route pages stay as thin composition layers.

11. Context and shared state

- FacultyContext and utility providers under src/app/util/providers.jsx suggest shared app state for globally useful reference data.

- This supports features that need consistent faculty/course lookup data across multiple tools without duplicating fetch logic.

12. Data import, maintenance, and scripts

- The repo includes operational scripts for cleaning and transforming source data: faculty CSV conversion, missing faculty detection, semester formatting fixes, seeding, deletion, and publish workflows.

- src/app/api/admin/import/faculty and the admin dashboard pages show that data ingestion is a first-class system concern, not just a one-off setup step.

13. Infrastructure boundaries

- The architecture spans three main runtimes/services: Next.js app hosting, Supabase Postgres, and Cloudflare R2/Workers for object storage flows.

- r2-worker/wrangler.toml makes the R2 integration explicit, while supabase/migrations shows the database is managed separately from the app code.

- For a diagram, these should be drawn as distinct external services connected to the Next.js application through APIs and storage-presign flows.