# maybeanushka/nexus architecture

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

- Interactive diagram: https://gitdiagram.com/maybeanushka/nexus
- Repository: https://github.com/maybeanushka/nexus

## Overview

1. This is a Next.js App Router application for a student clearance workflow. The repository is organized around a public entry/auth flow, an authenticated dashboard area, and a set of backend utilities for MongoDB, file storage, email nudges, and admin seeding.

2. The main product boundary is the `app/` tree. Public routes cover landing, login, registration, and certificate verification. Authenticated work lives under `app/(dashboard)`, which is a route group for the logged-in experience and separates student-facing and admin-facing screens.

3. The student workflow is centered on application submission and status consumption. Key screens include `submit-application`, `profile`, `fees`, `library`, `receipt/[id]`, `certificate`, and `student-dashboard`. Together these represent the path from registration and document upload to payment, dues handling, and final clearance outputs.

4. The admin workflow is split into distinct operational areas. `admin-portal` supports staged review, including per-record review pages and zip downloads. `admin/library` appears to handle library-specific administration, while the broader dashboard likely gives admins tools to inspect student records and mark clearance progress.

5. Authentication and session handling are centralized in `lib/auth.ts`, with logout exposed through `app/api/logout/route.ts`. The architecture implies role-based access across the dashboard, with public registration intentionally limited to student accounts only and admin accounts created separately.

6. Data access is backed by MongoDB, configured through `MONGODB_URI` and accessed through `lib/db.ts` plus `lib/models.ts`. The presence of `lib/schema.sql` suggests some schema documentation or migration history, but the runtime datastore is MongoDB, not a relational database.

7. File/document handling is a major subsystem. Uploads are stored either in S3 via `lib/s3.ts` or, if AWS settings are absent, fall back to local files under `public/uploads`. The stored artifacts are grouped by document type such as `id_cards`, `lab_records`, `library_receipts`, and `profiles`, which maps directly to clearance evidence and receipts.

8. The application has a public verification surface at `app/verify/[id]`. That route likely exposes a read-only lookup for certificates or clearance status, making verification a distinct public boundary separate from the authenticated dashboard.

9. A lightweight backend automation path exists for reminders. `app/api/cron/nudge/route.ts` and `scripts/email_nudge.js` indicate a scheduled or manually triggered nudge worker, using the email credentials described in the README. This is part of the operational layer rather than the core user workflow.

10. Admin provisioning is intentionally out-of-band. `scripts/seed_admin.js` creates privileged accounts from the command line, with role constraints like `lab_admin`, `hod_admin`, and `principal_admin`, and branch assignment only for HOD admins. That keeps admin bootstrap separate from public registration.

11. The UI is built from server-rendered route pages plus client components for interactive actions. Shared shell components like `Sidebar` and `TopNav` frame the dashboard, while leaf components such as `SubmitForm`, `ProfileForm`, `ReviewForm`, `PaymentButton`, `DownloadDocsButton`, `ReceiptQR`, and `CopyLinkButton` handle form submission, downloads, QR display, and user actions.

12. In diagram terms, the important flows are: public registration → MongoDB user record; authenticated dashboard → document upload/storage + record updates; admin review → status changes and downloadable bundles; receipt/certificate views → generated artifacts and verification links; and cron/email nudges → outbound reminders based on database state. The key external dependencies are MongoDB, optional AWS S3, and email delivery credentials.

Main entry points: [`lib/db.ts`](https://github.com/maybeanushka/nexus/blob/main/lib/db.ts) (MongoDB), [`lib/actions.ts`](https://github.com/maybeanushka/nexus/blob/main/lib/actions.ts) (Actions), [`lib/s3.ts`](https://github.com/maybeanushka/nexus/blob/main/lib/s3.ts) (Storage), [`app/page.tsx`](https://github.com/maybeanushka/nexus/blob/main/app/page.tsx) (Landing)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_public["Public entry"]
  node_node_home["Landing<br/>public page<br/>[page.tsx]"]
  node_node_login["Login<br/>auth page<br/>[page.tsx]"]
  node_node_register["Register<br/>student signup<br/>[page.tsx]"]
  node_node_verify["Verify<br/>public lookup<br/>[page.tsx]"]
end

subgraph group_group_dashboard["Dashboard app"]
  node_node_dashboard_layout["Dashboard shell<br/>route layout<br/>[layout.tsx]"]
  node_node_student_dash["Student hub<br/>student dashboard<br/>[page.tsx]"]
  node_node_submit["Submit app<br/>submission form<br/>[page.tsx]"]
  node_node_profile["Profile<br/>[page.tsx]"]
  node_node_fees["Fees<br/>fee status<br/>[page.tsx]"]
  node_node_library["Library<br/>dues screen<br/>[page.tsx]"]
  node_node_receipt["Receipt<br/>[page.tsx]"]
  node_node_certificate["Certificate<br/>clearance output<br/>[page.tsx]"]
  node_node_admin_portal["Admin portal<br/>admin review<br/>[page.tsx]"]
  node_node_admin_review["Review case<br/>admin workflow<br/>[page.tsx]"]
  node_node_admin_library["Lib admin<br/>admin area<br/>[page.tsx]"]
end

subgraph group_group_backend["Backend core"]
  node_node_auth["Auth<br/>session control<br/>[auth.ts]"]
  node_node_db[("MongoDB<br/>data access<br/>[db.ts]")]
  node_node_models["Models<br/>domain schema<br/>[models.ts]"]
  node_node_storage["Storage<br/>[s3.ts]"]
  node_node_actions["Actions<br/>[actions.ts]"]
  node_node_logout_api["Logout API<br/>route handler<br/>[route.ts]"]
end

subgraph group_group_ops["Operations"]
  node_node_nudge_api["Nudge API<br/>cron handler<br/>[route.ts]"]
  node_node_email_script["Email nudge<br/>worker script<br/>[email_nudge.js]"]
  node_node_seed_admin["Seed admin<br/>bootstrap script<br/>[seed_admin.js]"]
end

subgraph group_group_ui["Shared UI"]
  node_node_sidebar["Sidebar<br/>navigation shell<br/>[Sidebar.tsx]"]
  node_node_topnav["Top nav<br/>navigation shell<br/>[TopNav.tsx]"]
end

node_node_home -->|"auth entry"| node_node_login
node_node_home -->|"new student"| node_node_register
node_node_home -->|"verify"| node_node_verify
node_node_register -->|"create user"| node_node_db
node_node_login -->|"session"| node_node_auth
node_node_dashboard_layout -->|"shell"| node_node_sidebar
node_node_dashboard_layout -->|"shell"| node_node_topnav
node_node_auth -->|"users"| node_node_db
node_node_auth -->|"sign out"| node_node_logout_api
node_node_submit -->|"submit"| node_node_actions
node_node_submit -->|"uploads"| node_node_storage
node_node_profile -->|"save"| node_node_actions
node_node_fees -->|"status"| node_node_db
node_node_library -->|"dues"| node_node_db
node_node_student_dash -->|"workflow"| node_node_actions
node_node_receipt -->|"receipt"| node_node_db
node_node_receipt -->|"docs"| node_node_storage
node_node_receipt -->|"qr/share"| node_node_actions
node_node_certificate -->|"clearance"| node_node_db
node_node_certificate -->|"share link"| node_node_actions
node_node_admin_portal -->|"review queue"| node_node_db
node_node_admin_portal -->|"open case"| node_node_admin_review
node_node_admin_review -->|"approve"| node_node_actions
node_node_admin_review -->|"bundle"| node_node_storage
node_node_admin_library -->|"library admin"| node_node_db
node_node_nudge_api -->|"due lookup"| node_node_db
node_node_nudge_api -->|"trigger"| node_node_email_script
node_node_email_script -->|"recipients"| node_node_db
node_node_seed_admin -->|"provision"| node_node_db
node_node_storage -->|"metadata"| node_node_db

click node_node_home "https://github.com/maybeanushka/nexus/blob/main/app/page.tsx"
click node_node_login "https://github.com/maybeanushka/nexus/blob/main/app/login/page.tsx"
click node_node_register "https://github.com/maybeanushka/nexus/blob/main/app/register/page.tsx"
click node_node_verify "https://github.com/maybeanushka/nexus/blob/main/app/verify/[id]/page.tsx"
click node_node_dashboard_layout "https://github.com/maybeanushka/nexus/blob/main/app/(dashboard)/layout.tsx"
click node_node_student_dash "https://github.com/maybeanushka/nexus/blob/main/app/(dashboard)/student-dashboard/page.tsx"
click node_node_submit "https://github.com/maybeanushka/nexus/blob/main/app/(dashboard)/submit-application/page.tsx"
click node_node_profile "https://github.com/maybeanushka/nexus/blob/main/app/(dashboard)/profile/page.tsx"
click node_node_fees "https://github.com/maybeanushka/nexus/blob/main/app/(dashboard)/fees/page.tsx"
click node_node_library "https://github.com/maybeanushka/nexus/blob/main/app/(dashboard)/library/page.tsx"
click node_node_receipt "https://github.com/maybeanushka/nexus/blob/main/app/(dashboard)/receipt/[id]/page.tsx"
click node_node_certificate "https://github.com/maybeanushka/nexus/blob/main/app/(dashboard)/certificate/page.tsx"
click node_node_admin_portal "https://github.com/maybeanushka/nexus/blob/main/app/(dashboard)/admin-portal/page.tsx"
click node_node_admin_review "https://github.com/maybeanushka/nexus/blob/main/app/(dashboard)/admin-portal/review/[id]/page.tsx"
click node_node_admin_library "https://github.com/maybeanushka/nexus/blob/main/app/(dashboard)/admin/library/page.tsx"
click node_node_sidebar "https://github.com/maybeanushka/nexus/blob/main/components/Sidebar.tsx"
click node_node_topnav "https://github.com/maybeanushka/nexus/blob/main/components/TopNav.tsx"
click node_node_auth "https://github.com/maybeanushka/nexus/blob/main/lib/auth.ts"
click node_node_db "https://github.com/maybeanushka/nexus/blob/main/lib/db.ts"
click node_node_models "https://github.com/maybeanushka/nexus/blob/main/lib/models.ts"
click node_node_storage "https://github.com/maybeanushka/nexus/blob/main/lib/s3.ts"
click node_node_actions "https://github.com/maybeanushka/nexus/blob/main/lib/actions.ts"
click node_node_logout_api "https://github.com/maybeanushka/nexus/blob/main/app/api/logout/route.ts"
click node_node_nudge_api "https://github.com/maybeanushka/nexus/blob/main/app/api/cron/nudge/route.ts"
click node_node_email_script "https://github.com/maybeanushka/nexus/blob/main/scripts/email_nudge.js"
click node_node_seed_admin "https://github.com/maybeanushka/nexus/blob/main/scripts/seed_admin.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_node_home,node_node_login,node_node_register,node_node_verify toneBlue
class node_node_dashboard_layout,node_node_student_dash,node_node_submit,node_node_profile,node_node_fees,node_node_library,node_node_receipt,node_node_certificate,node_node_admin_portal,node_node_admin_review,node_node_admin_library toneAmber
class node_node_auth,node_node_db,node_node_models,node_node_storage,node_node_actions,node_node_logout_api toneMint
class node_node_nudge_api,node_node_email_script,node_node_seed_admin toneRose
class node_node_sidebar,node_node_topnav toneIndigo
```

## Components

### Public entry

Landing, auth, and verification routes for unauthenticated users.

- [Landing](https://github.com/maybeanushka/nexus/blob/main/app/page.tsx): public page · Top-level entry page for the site. · `app/page.tsx`
- [Login](https://github.com/maybeanushka/nexus/blob/main/app/login/page.tsx): auth page · Public sign-in screen. · `app/login/page.tsx`
- [Register](https://github.com/maybeanushka/nexus/blob/main/app/register/page.tsx): student signup · Public student registration flow. · `app/register/page.tsx`
- [Verify](https://github.com/maybeanushka/nexus/blob/main/app/verify/[id]/page.tsx): public lookup · Read-only public certificate or clearance verification. · `app/verify/[id]/page.tsx`

### Dashboard app

Authenticated student and admin experience under the App Router dashboard.

- [Dashboard shell](https://github.com/maybeanushka/nexus/blob/main/app/(dashboard)/layout.tsx): route layout · Authenticated layout wrapping dashboard routes. · `app/(dashboard)/layout.tsx`
- [Student hub](https://github.com/maybeanushka/nexus/blob/main/app/(dashboard)/student-dashboard/page.tsx): student dashboard · Overview and action center for student clearance progress. · `app/(dashboard)/student-dashboard/page.tsx`
- [Submit app](https://github.com/maybeanushka/nexus/blob/main/app/(dashboard)/submit-application/page.tsx): submission form · Application intake and document upload entry. · `app/(dashboard)/submit-application/page.tsx`
- [Profile](https://github.com/maybeanushka/nexus/blob/main/app/(dashboard)/profile/page.tsx): profile form · Student profile editing and persistence. · `app/(dashboard)/profile/page.tsx`
- [Fees](https://github.com/maybeanushka/nexus/blob/main/app/(dashboard)/fees/page.tsx): fee status · Payment and dues-related student screen. · `app/(dashboard)/fees/page.tsx`
- [Library](https://github.com/maybeanushka/nexus/blob/main/app/(dashboard)/library/page.tsx): dues screen · Library dues and clearance status view. · `app/(dashboard)/library/page.tsx`
- [Receipt](https://github.com/maybeanushka/nexus/blob/main/app/(dashboard)/receipt/[id]/page.tsx): receipt view · Receipt detail page with QR-based sharing. · `app/(dashboard)/receipt/[id]/page.tsx`
- [Certificate](https://github.com/maybeanushka/nexus/blob/main/app/(dashboard)/certificate/page.tsx): clearance output · Certificate display and share-link generation. · `app/(dashboard)/certificate/page.tsx`
- [Admin portal](https://github.com/maybeanushka/nexus/blob/main/app/(dashboard)/admin-portal/page.tsx): admin review · Central admin queue and record management. · `app/(dashboard)/admin-portal/page.tsx`
- [Review case](https://github.com/maybeanushka/nexus/blob/main/app/(dashboard)/admin-portal/review/[id]/page.tsx): admin workflow · Per-record review, status update, and zip export. · `app/(dashboard)/admin-portal/review/[id]/page.tsx`
- [Lib admin](https://github.com/maybeanushka/nexus/blob/main/app/(dashboard)/admin/library/page.tsx): admin area · Library-specific administrative screen. · `app/(dashboard)/admin/library/page.tsx`

### Backend core

Shared server-side logic for auth, database, storage, and models.

- [Auth](https://github.com/maybeanushka/nexus/blob/main/lib/auth.ts): session control · Authentication and session helpers. · `lib/auth.ts`
- [MongoDB](https://github.com/maybeanushka/nexus/blob/main/lib/db.ts): data access · Database connection and persistence entrypoint. · `lib/db.ts`
- [Models](https://github.com/maybeanushka/nexus/blob/main/lib/models.ts): domain schema · Mongo-backed model definitions. · `lib/models.ts`
- [Storage](https://github.com/maybeanushka/nexus/blob/main/lib/s3.ts): file storage · S3 integration with local upload fallback. · `lib/s3.ts`
- [Actions](https://github.com/maybeanushka/nexus/blob/main/lib/actions.ts): server actions · Shared mutation and workflow helpers. · `lib/actions.ts`
- [Logout API](https://github.com/maybeanushka/nexus/blob/main/app/api/logout/route.ts): route handler · Sign-out endpoint used by authenticated UI. · `app/api/logout/route.ts`

### Operations

Automation and bootstrap scripts for reminders and admin provisioning.

- [Nudge API](https://github.com/maybeanushka/nexus/blob/main/app/api/cron/nudge/route.ts): cron handler · Scheduled reminder endpoint for outstanding actions. · `app/api/cron/nudge/route.ts`
- [Email nudge](https://github.com/maybeanushka/nexus/blob/main/scripts/email_nudge.js): worker script · Manual or scheduled reminder sender. · `scripts/email_nudge.js`
- [Seed admin](https://github.com/maybeanushka/nexus/blob/main/scripts/seed_admin.js): bootstrap script · Creates privileged admin accounts out of band. · `scripts/seed_admin.js`

### Shared UI

Reusable dashboard shell and action components.

- [Sidebar](https://github.com/maybeanushka/nexus/blob/main/components/Sidebar.tsx): navigation shell · Dashboard navigation scaffold. · `components/Sidebar.tsx`
- [Top nav](https://github.com/maybeanushka/nexus/blob/main/components/TopNav.tsx): navigation shell · Top-level dashboard header and controls. · `components/TopNav.tsx`

## Connections

- Landing → Login: auth entry · Public users move from landing to sign-in.
- Landing → Register: new student · Landing page can route to registration.
- Landing → Verify: verify · Public verification surface is reachable from the site.
- Register → MongoDB: create user · Registration writes student records to MongoDB.
- Login → Auth: session · Login uses shared authentication/session logic.
- Dashboard shell → Sidebar: shell · Authenticated routes are wrapped with shared navigation.
- Dashboard shell → Top nav: shell · Authenticated routes use the top navigation shell.
- Auth → MongoDB: users · Auth reads and writes user/session state through the database.
- Auth → Logout API: sign out · Logout endpoint delegates session invalidation to auth logic.
- Submit app → Actions: submit · Application submission is handled by shared server actions.
- Submit app → Storage: uploads · Documents are stored through the file storage layer.
- Profile → Actions: save · Profile edits persist through shared mutation helpers.
- Fees → MongoDB: status · Fee status is read from persisted student records.
- Library → MongoDB: dues · Library dues screen consumes database state.
- Student hub → Actions: workflow · Student hub launches clearance-related actions.
- Receipt → MongoDB: receipt · Receipt views are populated from stored records.
- Receipt → Storage: docs · Receipt pages can reference stored artifacts.
- Receipt → Actions: qr/share · Receipt utilities rely on shared action helpers.
- Certificate → MongoDB: clearance · Certificate output is derived from persisted clearance state.
- Certificate → Actions: share link · Certificate page uses shared helpers for link generation.
- Admin portal → MongoDB: review queue · Admin portal reads records for staged review.
- Admin portal → Review case: open case · Admin portal routes into per-record review pages.
- Review case → Actions: approve · Review pages execute status updates through shared actions.
- Review case → Storage: bundle · Review pages can assemble downloadable document bundles.
- Lib admin → MongoDB: library admin · Library admin screen manages library-related records.
- Nudge API → MongoDB: due lookup · Cron endpoint selects records needing reminders.
- Nudge API → Email nudge: trigger · Cron endpoint drives outbound reminder sending.
- Email nudge → MongoDB: recipients · Reminder script queries database state for recipients.
- Seed admin → MongoDB: provision · Admin bootstrap writes privileged accounts into MongoDB.
- Storage → MongoDB: metadata · Uploads are associated with persisted records.
