# eniamza/boracle architecture

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

- Interactive diagram: https://gitdiagram.com/eniamza/boracle
- Repository: https://github.com/eniamza/boracle

## Overview

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.

Main entry points: [`src/lib/db/schema/index.js`](https://github.com/eniamza/boracle/blob/master/src/lib/db/schema/index.js) (DB Schema), [`src/app/(main)/preprereg/page.jsx`](https://github.com/eniamza/boracle/blob/master/src/app/(main)/preprereg/page.jsx) (Student Tools), [`src/components/routine/RoutineView.jsx`](https://github.com/eniamza/boracle/blob/master/src/components/routine/RoutineView.jsx) (Feature Components), [`src/app/(main)`](https://github.com/eniamza/boracle/tree/master/src/app/(main)) (Main App)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app_surface["App Surface"]
  node_main_shell["Main App<br/>next app router"]
  node_dashboard_shell["Dashboard App<br/>next app router"]
  node_home_pages["Home Pages<br/>public routes<br/>[page.jsx]"]
  node_student_tools["Student Tools<br/>product routes<br/>[page.jsx]"]
  node_dashboard_pages["Workspace Pages<br/>dashboard routes<br/>[page.jsx]"]
  node_admin_pages["Admin Pages<br/>admin routes<br/>[page.jsx]"]
end

subgraph group_api_backend["API Layer"]
  node_auth_route["Auth Route<br/>nextauth<br/>[route.js]"]
  node_api_faculty["Faculty API<br/>lookup api<br/>[route.js]"]
  node_api_materials["Materials API<br/>storage api<br/>[route.js]"]
  node_api_routine_swap["Routine & Swap API<br/>domain api<br/>[route.js]"]
  node_api_gradesheet["Gradesheet API<br/>analysis api<br/>[route.js]"]
  node_api_dashboard["Dashboard API<br/>summary api<br/>[route.js]"]
  node_api_admin["Admin API<br/>moderation api<br/>[route.js]"]
end

subgraph group_data_storage["Data & Storage"]
  node_db_schema[("DB Schema<br/>drizzle schema<br/>[index.js]")]
  node_migrations["Migrations"]
  node_r2_storage["R2 Worker<br/>object storage<br/>[index.js]"]
end

subgraph group_shared_ui["Shared UI"]
  node_faculty_context["Faculty Context<br/>shared state<br/>[FacultyContext.jsx]"]
  node_shared_features["Feature Components<br/>ui modules<br/>[RoutineView.jsx]"]
  node_design_system["UI Primitives<br/>component library<br/>[button.jsx]"]
  node_app_providers["App Providers<br/>shell providers<br/>[providers.jsx]"]
end

subgraph group_ops_tools["Ops & Scripts"]
  node_scripts["Maintenance Scripts<br/>data ops"]
end

node_main_shell -->|"renders"| node_home_pages
node_main_shell -->|"hosts"| node_student_tools
node_dashboard_shell -->|"renders"| node_dashboard_pages
node_dashboard_shell -->|"renders"| node_admin_pages
node_main_shell -->|"wraps"| node_app_providers
node_dashboard_shell -->|"wraps"| node_app_providers
node_student_tools -->|"uses"| node_shared_features
node_dashboard_pages -->|"uses"| node_shared_features
node_admin_pages -->|"uses"| node_shared_features
node_shared_features -->|"built on"| node_design_system
node_shared_features -->|"reads"| node_faculty_context
node_auth_route -->|"sessions"| node_app_providers
node_api_faculty -->|"queries"| node_db_schema
node_api_materials -->|"queries"| node_db_schema
node_api_materials -->|"uploads"| node_r2_storage
node_api_routine_swap -->|"queries"| node_db_schema
node_api_gradesheet -->|"queries"| node_db_schema
node_api_dashboard -->|"reads"| node_db_schema
node_api_admin -->|"mutates"| node_db_schema
node_db_schema -->|"managed by"| node_migrations
node_scripts -->|"seeds/cleans"| node_db_schema
node_scripts -->|"supports"| node_migrations
node_main_shell -.->|"sign-in"| node_auth_route
node_dashboard_shell -.->|"protects"| node_auth_route
node_admin_pages -.->|"calls"| node_api_admin
node_dashboard_pages -.->|"fetches"| node_api_dashboard
node_student_tools -.->|"calls"| node_api_routine_swap
node_student_tools -.->|"calls"| node_api_materials
node_student_tools -.->|"calls"| node_api_gradesheet
node_student_tools -.->|"calls"| node_api_faculty
node_shared_features -.->|"interacts"| node_api_materials

click node_main_shell "https://github.com/eniamza/boracle/tree/master/src/app/(main)"
click node_dashboard_shell "https://github.com/eniamza/boracle/tree/master/src/app/(dashboard)"
click node_home_pages "https://github.com/eniamza/boracle/blob/master/src/app/(main)/page.jsx"
click node_student_tools "https://github.com/eniamza/boracle/blob/master/src/app/(main)/preprereg/page.jsx"
click node_dashboard_pages "https://github.com/eniamza/boracle/blob/master/src/app/(dashboard)/dashboard/page.jsx"
click node_admin_pages "https://github.com/eniamza/boracle/blob/master/src/app/(dashboard)/dashboard/(admin)/manage-users/page.jsx"
click node_auth_route "https://github.com/eniamza/boracle/blob/master/src/app/api/[...nextauth]/route.js"
click node_api_faculty "https://github.com/eniamza/boracle/blob/master/src/app/api/faculty/lookup/route.js"
click node_api_materials "https://github.com/eniamza/boracle/blob/master/src/app/api/materials/route.js"
click node_api_routine_swap "https://github.com/eniamza/boracle/blob/master/src/app/api/routine/route.js"
click node_api_gradesheet "https://github.com/eniamza/boracle/blob/master/src/app/api/gradesheet/route.js"
click node_api_dashboard "https://github.com/eniamza/boracle/blob/master/src/app/api/dashboard/recentActivity/route.js"
click node_api_admin "https://github.com/eniamza/boracle/blob/master/src/app/api/admin/import/faculty/route.js"
click node_db_schema "https://github.com/eniamza/boracle/blob/master/src/lib/db/schema/index.js"
click node_migrations "https://github.com/eniamza/boracle/blob/master/supabase/migrations/20250829151427_createUserTable.sql"
click node_r2_storage "https://github.com/eniamza/boracle/blob/master/r2-worker/src/index.js"
click node_faculty_context "https://github.com/eniamza/boracle/blob/master/src/app/contexts/FacultyContext.jsx"
click node_shared_features "https://github.com/eniamza/boracle/blob/master/src/components/routine/RoutineView.jsx"
click node_design_system "https://github.com/eniamza/boracle/blob/master/src/components/ui/button.jsx"
click node_app_providers "https://github.com/eniamza/boracle/blob/master/src/app/util/providers.jsx"
click node_scripts "https://github.com/eniamza/boracle/blob/master/scripts/convertFacultyJsonToCsv.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_main_shell,node_dashboard_shell,node_home_pages,node_student_tools,node_dashboard_pages,node_admin_pages toneBlue
class node_auth_route,node_api_faculty,node_api_materials,node_api_routine_swap,node_api_gradesheet,node_api_dashboard,node_api_admin toneAmber
class node_db_schema,node_migrations,node_r2_storage toneMint
class node_faculty_context,node_shared_features,node_design_system,node_app_providers toneRose
class node_scripts toneIndigo
```

## Components

### App Surface

Public and authenticated Next.js route trees.

- [Main App](https://github.com/eniamza/boracle/tree/master/src/app/(main)): next app router · Public product experience and landing pages. · `src/app/(main)`
- [Dashboard App](https://github.com/eniamza/boracle/tree/master/src/app/(dashboard)): next app router · Authenticated workspace and admin surface. · `src/app/(dashboard)`
- [Home Pages](https://github.com/eniamza/boracle/blob/master/src/app/(main)/page.jsx): public routes · Homepage, changelog, contributors, and public entry points. · `src/app/(main)/page.jsx`
- [Student Tools](https://github.com/eniamza/boracle/blob/master/src/app/(main)/preprereg/page.jsx): product routes · Public tools for routines, swaps, gradesheet, chicken coop, and materials. · `src/app/(main)/preprereg/page.jsx`
- [Workspace Pages](https://github.com/eniamza/boracle/blob/master/src/app/(dashboard)/dashboard/page.jsx): dashboard routes · User dashboard and feature pages for signed-in users. · `src/app/(dashboard)/dashboard/page.jsx`
- [Admin Pages](https://github.com/eniamza/boracle/blob/master/src/app/(dashboard)/dashboard/(admin)/manage-users/page.jsx): admin routes · User, swap, material, and import management views. · `src/app/(dashboard)/dashboard/(admin)/manage-users/page.jsx`

### API Layer

Domain route handlers and auth boundary.

- [Auth Route](https://github.com/eniamza/boracle/blob/master/src/app/api/[...nextauth]/route.js): nextauth · Authentication endpoint for session handling. · `src/app/api/[...nextauth]/route.js`
- [Faculty API](https://github.com/eniamza/boracle/blob/master/src/app/api/faculty/lookup/route.js): lookup api · Faculty lookup and detail endpoints used across tools. · `src/app/api/faculty/lookup/route.js`
- [Materials API](https://github.com/eniamza/boracle/blob/master/src/app/api/materials/route.js): storage api · Material browsing, details, votes, moderation, and presigned upload flow. · `src/app/api/materials/route.js`
- [Routine & Swap API](https://github.com/eniamza/boracle/blob/master/src/app/api/routine/route.js): domain api · Routine, merged routine, course swap, requests, and public swap endpoints. · `src/app/api/routine/route.js`
- [Gradesheet API](https://github.com/eniamza/boracle/blob/master/src/app/api/gradesheet/route.js): analysis api · Gradesheet planning and analytics endpoint. · `src/app/api/gradesheet/route.js`
- [Dashboard API](https://github.com/eniamza/boracle/blob/master/src/app/api/dashboard/recentActivity/route.js): summary api · Recent activity, user counts, and home stats feeds. · `src/app/api/dashboard/recentActivity/route.js`
- [Admin API](https://github.com/eniamza/boracle/blob/master/src/app/api/admin/import/faculty/route.js): moderation api · Import, user management, and swap moderation endpoints. · `src/app/api/admin/import/faculty/route.js`

### Data & Storage

Database schema, migrations, and object storage.

- [DB Schema](https://github.com/eniamza/boracle/blob/master/src/lib/db/schema/index.js): drizzle schema · Postgres tables and relations for users, faculty, routines, swaps, materials, reviews, and moderation. · `src/lib/db/schema/index.js`
- [Migrations](https://github.com/eniamza/boracle/blob/master/supabase/migrations/20250829151427_createUserTable.sql): sql migrations · Supabase migration history for the database model. · `supabase/migrations/20250829151427_createUserTable.sql`
- [R2 Worker](https://github.com/eniamza/boracle/blob/master/r2-worker/src/index.js): object storage · Cloudflare R2 worker for material file handling. · `r2-worker/src/index.js`

### Shared UI

Reusable feature components and design system.

- [Faculty Context](https://github.com/eniamza/boracle/blob/master/src/app/contexts/FacultyContext.jsx): shared state · App-wide faculty reference data for feature screens. · `src/app/contexts/FacultyContext.jsx`
- [Feature Components](https://github.com/eniamza/boracle/blob/master/src/components/routine/RoutineView.jsx): ui modules · Domain components for routines, swaps, materials, gradesheet, chicken coop, and dashboard. · `src/components/routine/RoutineView.jsx`
- [UI Primitives](https://github.com/eniamza/boracle/blob/master/src/components/ui/button.jsx): component library · Shared shadcn/Radix-style primitives and app chrome. · `src/components/ui/button.jsx`
- [App Providers](https://github.com/eniamza/boracle/blob/master/src/app/util/providers.jsx): shell providers · Global providers, theme, and session-ready app composition. · `src/app/util/providers.jsx`

### Ops & Scripts

Maintenance and data preparation scripts.

- [Maintenance Scripts](https://github.com/eniamza/boracle/blob/master/scripts/convertFacultyJsonToCsv.js): data ops · Seed, cleanup, publish, and transformation scripts. · `scripts/convertFacultyJsonToCsv.js`

## Connections

- Main App → Home Pages: renders · Public route tree contains landing and content pages.
- Main App → Student Tools: hosts · Main app routes expose the product tools.
- Dashboard App → Workspace Pages: renders · Authenticated dashboard surface.
- Dashboard App → Admin Pages: renders · Admin workspace pages live under the dashboard shell.
- Main App → App Providers: wraps · Shared app composition for main routes.
- Dashboard App → App Providers: wraps · Shared providers and theme for signed-in workspace.
- Student Tools → Feature Components: uses · Pages compose feature-specific client components.
- Workspace Pages → Feature Components: uses · Dashboard widgets and feature panels reuse shared components.
- Admin Pages → Feature Components: uses · Admin screens reuse domain UI and tables.
- Feature Components → UI Primitives: built on · Feature UI is composed from shared primitives.
- Feature Components → Faculty Context: reads · Cross-feature faculty data is provided through shared context.
- Auth Route → App Providers: sessions · Auth state is consumed through app-level providers.
- Faculty API → DB Schema: queries · Faculty lookup endpoints read persistent records.
- Materials API → DB Schema: queries · Materials metadata, votes, and moderation are persisted in Postgres.
- Materials API → R2 Worker: uploads · Presigned and worker-backed file flow for course materials.
- Routine & Swap API → DB Schema: queries · Routine and swap endpoints operate on shared relational state.
- Gradesheet API → DB Schema: queries · Gradesheet analysis depends on stored academic data.
- Dashboard API → DB Schema: reads · Dashboard summaries are assembled from stored operational data.
- Admin API → DB Schema: mutates · Admin imports and moderation actions update the system of record.
- DB Schema → Migrations: managed by · Schema evolution is tracked through Supabase migrations.
- Maintenance Scripts → DB Schema: seeds/cleans · Operational scripts prepare and reconcile data.
- Maintenance Scripts → Migrations: supports · Maintenance tooling complements the migration-driven database.
- Main App → Auth Route: sign-in · Public app includes authentication entry points.
- Dashboard App → Auth Route: protects · Dashboard access depends on authenticated sessions.
- Admin Pages → Admin API: calls · Admin actions terminate in dedicated admin endpoints.
- Workspace Pages → Dashboard API: fetches · Dashboard widgets are populated from summary endpoints.
- Student Tools → Routine & Swap API: calls · Core student tools rely on routine and swap APIs.
- Student Tools → Materials API: calls · Materials browsing and uploads use the materials API.
- Student Tools → Gradesheet API: calls · Gradesheet analysis is served by the gradesheet API.
- Student Tools → Faculty API: calls · Tools share faculty lookup services.
- Feature Components → Materials API: interacts · Material cards, modals, and voting components talk to the materials API.