# dewanshakib/uu-unifile-v1 architecture

> Architecture diagram of the GitHub repository dewanshakib/uu-unifile-v1, 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/dewanshakib/uu-unifile-v1
- Repository: https://github.com/dewanshakib/uu-unifile-v1

## Overview

1. **Overall shape**
   - This is a **Next.js 16 App Router** application with three clear surfaces:
     - **Public browsing** for files and Google Classroom metadata
     - **Auth flows** for sign-in/sign-up/password reset
     - **Protected dashboard** for admin management

2. **Route organization**
   - The `app/` tree is the main composition boundary.
   - Route groups split the app into:
     - `app/(auth)` for authentication pages
     - `app/(private)` for the role-protected dashboard
   - Public content lives outside those groups in `app/files` and `app/google-classrooms`.

3. **Core data hierarchy**
   - The entire browsing model is built around an academic path:
     - **year → semester (`semister` in routes) → section**
   - From there it branches into:
     - **category → files**
     - **subject → classroom files**
   - This hierarchy is the main data-shaping boundary for both public browsing and admin entry forms.

4. **Two domain tracks**
   - There are two content domains with similar navigation patterns:
     - **Files**: categorized academic resources
     - **Google Classrooms**: course/classroom entries tied to subjects
   - Both share the same academic filters, but diverge at the final entity level (`category` vs `subject`).

5. **Authentication subsystem**
   - Auth is handled by **Better Auth** through `app/api/auth/[...all]/route.ts`.
   - Client/server auth setup is split between `lib/auth-client.ts` and `lib/auth.ts`.
   - Auth pages in `components/auth/*` back the sign-in, sign-up, and password reset flows.
   - Session cookies are part of the auth boundary, and the app uses roles from the user record.

6. **Authorization and protected access**
   - `app/(private)/dashboard/layout.tsx` is the key server-side guard for admin areas.
   - The dashboard redirects:
     - unauthenticated users to **/sign-in**
     - non-admin users back to **/**
   - Role access is hierarchical:
     - `ADMIN` can manage files and Google Classrooms
     - `SUPER_ADMIN` can additionally manage categories and subjects

7. **Admin management flow**
   - Dashboard pages under `app/(private)/dashboard/*` are thin route shells.
   - Most CRUD UI is in `components/sections/dashboard/*`.
   - `actions/*.ts` contains server actions for create/update operations across:
     - files
     - categories
     - subjects
     - Google Classroom entries
   - This keeps the route layer separate from mutation logic and form UI.

8. **Public browsing flow**
   - Public pages under `app/files/*` and `app/google-classrooms/*` progressively narrow the dataset by URL params.
   - The navigation is hierarchical rather than search-based: each page refines the academic scope until the final list page.
   - The leaf pages are where the actual resource lists are rendered.

9. **Database and schema layer**
   - Persistence is PostgreSQL via **Drizzle ORM**.
   - The DB boundary is centralized in:
     - `drizzle/db.ts`
     - `drizzle/schema.ts`
     - `drizzle/migrations/*`
   - The schema includes auth tables (`user`, `session`, `account`, `verification`) plus domain tables for files, categories, subjects, and Google Classrooms.
   - The README indicates the app is designed for **Supabase-compatible Postgres**.

10. **Password reset and email**
   - Password reset is implemented as a separate auth flow and sends mail through **Nodemailer** with Gmail SMTP.
   - `lib/send-mail.ts` and the reset-password auth components form the mail flow boundary.
   - The reset redirect depends on the public Better Auth URL env vars.

11. **Operational endpoint**
   - `app/api/cron/keep-alive/route.ts` is a small operational API used to keep the database warm.
   - It is protected by `CRON_SECRET` and performs a simple DB ping (`SELECT 1`).
   - `vercel.json` schedules this endpoint, so deployment/runtime concerns are part of the architecture.

12. **Shared UI layer**
   - `components/ui/*` is the reusable design-system layer built from shadcn/Radix-style primitives.
   - `components/layout/*`, `components/nav-main.tsx`, and `components/app-sidebar.tsx` provide the global shell.
   - Feature-specific pages compose these primitives rather than owning low-level UI themselves.

13. **Important repo-specific note**
   - The codebase intentionally uses the spelling **`semister`** in route paths and folder names.
   - Google Classroom route nesting has some hard-coded intermediate segments in one path, but the deeper pages still resolve dynamic params from the URL.

14. **Architecture summary for a diagram**
   - Think of the repo as four main layers:
     - **Presentation**: App Router pages + reusable UI components
     - **Business/UI workflows**: dashboard section components and forms
     - **Mutation/data access**: server actions + Drizzle schema/DB client
     - **Platform services**: Better Auth, PostgreSQL, Gmail SMTP, and scheduled cron keep-alive

Main entry points: [`components/sections/dashboard`](https://github.com/dewanshakib/uu-unifile-v1/tree/main/components/sections/dashboard) (Admin Sections), [`app`](https://github.com/dewanshakib/uu-unifile-v1/tree/main/app) (App Router), [`app/(private)/dashboard`](https://github.com/dewanshakib/uu-unifile-v1/tree/main/app/(private)/dashboard) (Dashboard), [`drizzle/schema.ts`](https://github.com/dewanshakib/uu-unifile-v1/blob/main/drizzle/schema.ts) (Schema)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_presentation["Presentation"]
  node_app_root["App Router<br/>nextjs routes"]
  node_public_files["Files Browse<br/>public route tree"]
  node_public_classrooms["Classrooms Browse<br/>public route tree"]
  node_auth_routes["Auth Pages<br/>auth route tree"]
  node_private_dashboard["Dashboard<br/>protected route tree"]
  node_dashboard_layout["Guard Layout<br/>server layout<br/>[layout.tsx]"]
  node_dashboard_shell["Dashboard Shell<br/>page shell"]
  node_global_ui["UI Kit<br/>shared components"]
  node_auth_ui["Auth UI<br/>auth components"]
end

subgraph group_workflows["Workflows"]
  node_dashboard_sections["Admin Sections<br/>feature components"]
  node_file_section["File Admin<br/>crud section"]
  node_category_section["Category Admin<br/>crud section"]
  node_subject_section["Subject Admin<br/>crud section"]
  node_classroom_section["Classroom Admin<br/>crud section"]
end

subgraph group_data["Data & Auth"]
  node_actions["Server Actions<br/>mutation layer"]
  node_auth_lib["Auth Setup<br/>auth config<br/>[auth.ts]"]
  node_auth_client["Auth Client<br/>client auth<br/>[auth-client.ts]"]
  node_db_layer[("Database<br/>drizzle db<br/>[db.ts]")]
  node_schema["Schema<br/>[schema.ts]"]
end

subgraph group_platform["Platform"]
  node_auth_api["Auth API<br/>better-auth route<br/>[route.ts]"]
  node_mail["Mail Sender<br/>smtp mailer<br/>[send-mail.ts]"]
  node_cron["Keep-Alive<br/>cron api<br/>[route.ts]"]
end

node_app_root -->|"routes"| node_public_files
node_app_root -->|"routes"| node_public_classrooms
node_app_root -->|"routes"| node_auth_routes
node_app_root -->|"routes"| node_private_dashboard
node_private_dashboard -->|"guards"| node_dashboard_layout
node_private_dashboard -->|"uses"| node_dashboard_shell
node_app_root -->|"composes"| node_global_ui
node_auth_routes -->|"renders"| node_auth_ui
node_private_dashboard -->|"renders"| node_dashboard_sections
node_dashboard_sections -->|"includes"| node_file_section
node_dashboard_sections -->|"includes"| node_category_section
node_dashboard_sections -->|"includes"| node_subject_section
node_dashboard_sections -->|"includes"| node_classroom_section
node_dashboard_sections -->|"mutates via"| node_actions
node_public_files -->|"filters by"| node_schema
node_public_classrooms -->|"filters by"| node_schema
node_actions -->|"writes"| node_db_layer
node_auth_api -->|"configures"| node_auth_lib
node_auth_lib -->|"pairs with"| node_auth_client
node_auth_lib -->|"uses"| node_schema
node_schema -->|"loads"| node_db_layer
node_mail -->|"supports"| node_auth_routes
node_cron -->|"pings"| node_db_layer

click node_app_root "https://github.com/dewanshakib/uu-unifile-v1/tree/main/app"
click node_public_files "https://github.com/dewanshakib/uu-unifile-v1/tree/main/app/files"
click node_public_classrooms "https://github.com/dewanshakib/uu-unifile-v1/tree/main/app/google-classrooms"
click node_auth_routes "https://github.com/dewanshakib/uu-unifile-v1/tree/main/app/(auth)"
click node_private_dashboard "https://github.com/dewanshakib/uu-unifile-v1/tree/main/app/(private)/dashboard"
click node_dashboard_layout "https://github.com/dewanshakib/uu-unifile-v1/blob/main/app/(private)/dashboard/layout.tsx"
click node_dashboard_shell "https://github.com/dewanshakib/uu-unifile-v1/blob/main/components/layout/dashboard-wrapper.tsx"
click node_global_ui "https://github.com/dewanshakib/uu-unifile-v1/tree/main/components/ui"
click node_auth_ui "https://github.com/dewanshakib/uu-unifile-v1/tree/main/components/auth"
click node_dashboard_sections "https://github.com/dewanshakib/uu-unifile-v1/tree/main/components/sections/dashboard"
click node_file_section "https://github.com/dewanshakib/uu-unifile-v1/tree/main/components/sections/dashboard/file"
click node_category_section "https://github.com/dewanshakib/uu-unifile-v1/tree/main/components/sections/dashboard/category"
click node_subject_section "https://github.com/dewanshakib/uu-unifile-v1/tree/main/components/sections/dashboard/subject"
click node_classroom_section "https://github.com/dewanshakib/uu-unifile-v1/tree/main/components/sections/dashboard/goolgeClassroom"
click node_actions "https://github.com/dewanshakib/uu-unifile-v1/tree/main/actions"
click node_auth_api "https://github.com/dewanshakib/uu-unifile-v1/blob/main/app/api/auth/[...all]/route.ts"
click node_auth_lib "https://github.com/dewanshakib/uu-unifile-v1/blob/main/lib/auth.ts"
click node_auth_client "https://github.com/dewanshakib/uu-unifile-v1/blob/main/lib/auth-client.ts"
click node_db_layer "https://github.com/dewanshakib/uu-unifile-v1/blob/main/drizzle/db.ts"
click node_schema "https://github.com/dewanshakib/uu-unifile-v1/blob/main/drizzle/schema.ts"
click node_mail "https://github.com/dewanshakib/uu-unifile-v1/blob/main/lib/send-mail.ts"
click node_cron "https://github.com/dewanshakib/uu-unifile-v1/blob/main/app/api/cron/keep-alive/route.ts"

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_root,node_public_files,node_public_classrooms,node_auth_routes,node_private_dashboard,node_dashboard_layout,node_dashboard_shell,node_global_ui,node_auth_ui toneBlue
class node_dashboard_sections,node_file_section,node_category_section,node_subject_section,node_classroom_section toneAmber
class node_actions,node_auth_lib,node_auth_client,node_db_layer,node_schema toneMint
class node_auth_api,node_mail,node_cron toneRose
```

## Components

### Presentation

Next.js App Router pages and shared UI shell

- [App Router](https://github.com/dewanshakib/uu-unifile-v1/tree/main/app): nextjs routes · Root app shell and top-level routing · `app`
- [Files Browse](https://github.com/dewanshakib/uu-unifile-v1/tree/main/app/files): public route tree · Hierarchical public browsing for academic files · `app/files`
- [Classrooms Browse](https://github.com/dewanshakib/uu-unifile-v1/tree/main/app/google-classrooms): public route tree · Hierarchical public browsing for classroom resources · `app/google-classrooms`
- [Auth Pages](https://github.com/dewanshakib/uu-unifile-v1/tree/main/app/(auth)): auth route tree · Sign-in, sign-up, and password reset pages · `app/(auth)`
- [Dashboard](https://github.com/dewanshakib/uu-unifile-v1/tree/main/app/(private)/dashboard): protected route tree · Admin area guarded by role checks · `app/(private)/dashboard`
- [Guard Layout](https://github.com/dewanshakib/uu-unifile-v1/blob/main/app/(private)/dashboard/layout.tsx): server layout · Redirects unauthenticated and non-admin users · `app/(private)/dashboard/layout.tsx`
- [Dashboard Shell](https://github.com/dewanshakib/uu-unifile-v1/blob/main/components/layout/dashboard-wrapper.tsx): page shell · Dashboard landing and shared admin navigation · `components/layout/dashboard-wrapper.tsx`
- [UI Kit](https://github.com/dewanshakib/uu-unifile-v1/tree/main/components/ui): shared components · Reusable primitives and global layout pieces · `components/ui`
- [Auth UI](https://github.com/dewanshakib/uu-unifile-v1/tree/main/components/auth): auth components · Sign-in, sign-up, sign-out, and reset forms · `components/auth`

### Workflows

Dashboard section components and forms

- [Admin Sections](https://github.com/dewanshakib/uu-unifile-v1/tree/main/components/sections/dashboard): feature components · CRUD screens for files, categories, subjects, and classrooms · `components/sections/dashboard`
- [File Admin](https://github.com/dewanshakib/uu-unifile-v1/tree/main/components/sections/dashboard/file): crud section · List and edit flows for files · `components/sections/dashboard/file`
- [Category Admin](https://github.com/dewanshakib/uu-unifile-v1/tree/main/components/sections/dashboard/category): crud section · Admin UI for category management · `components/sections/dashboard/category`
- [Subject Admin](https://github.com/dewanshakib/uu-unifile-v1/tree/main/components/sections/dashboard/subject): crud section · Admin UI for subject management · `components/sections/dashboard/subject`
- [Classroom Admin](https://github.com/dewanshakib/uu-unifile-v1/tree/main/components/sections/dashboard/goolgeClassroom): crud section · Admin UI for Google Classroom entries · `components/sections/dashboard/goolgeClassroom`

### Data & Auth

Server actions, auth setup, and database schema

- [Server Actions](https://github.com/dewanshakib/uu-unifile-v1/tree/main/actions): mutation layer · Create and update operations for domain entities · `actions`
- [Auth Setup](https://github.com/dewanshakib/uu-unifile-v1/blob/main/lib/auth.ts): auth config · Server and client auth configuration · `lib/auth.ts`
- [Auth Client](https://github.com/dewanshakib/uu-unifile-v1/blob/main/lib/auth-client.ts): client auth · Client-side auth helper · `lib/auth-client.ts`
- [Database](https://github.com/dewanshakib/uu-unifile-v1/blob/main/drizzle/db.ts): drizzle db · Central PostgreSQL connection and schema access · `drizzle/db.ts`
- [Schema](https://github.com/dewanshakib/uu-unifile-v1/blob/main/drizzle/schema.ts): drizzle schema · Auth and domain tables for files, categories, subjects, and classrooms · `drizzle/schema.ts`

### Platform

External services and operational endpoints

- [Auth API](https://github.com/dewanshakib/uu-unifile-v1/blob/main/app/api/auth/[...all]/route.ts): better-auth route · Better Auth catch-all API handler · `app/api/auth/[...all]/route.ts`
- [Mail Sender](https://github.com/dewanshakib/uu-unifile-v1/blob/main/lib/send-mail.ts): smtp mailer · Gmail SMTP password reset delivery · `lib/send-mail.ts`
- [Keep-Alive](https://github.com/dewanshakib/uu-unifile-v1/blob/main/app/api/cron/keep-alive/route.ts): cron api · Protected DB ping endpoint for deployment warmup · `app/api/cron/keep-alive/route.ts`

## Connections

- App Router → Files Browse: routes · App Router exposes the public files browsing tree
- App Router → Classrooms Browse: routes · App Router exposes the public classroom browsing tree
- App Router → Auth Pages: routes · App Router exposes authentication pages
- App Router → Dashboard: routes · App Router exposes protected dashboard routes
- Dashboard → Guard Layout: guards · Layout enforces session and role access
- Dashboard → Dashboard Shell: uses · Dashboard routes render through the shared shell
- App Router → UI Kit: composes · App-wide pages share reusable UI primitives
- Auth Pages → Auth UI: renders · Auth pages are backed by dedicated auth forms
- Dashboard → Admin Sections: renders · Route shells delegate CRUD screens to section components
- Admin Sections → File Admin: includes · Files management UI
- Admin Sections → Category Admin: includes · Category management UI
- Admin Sections → Subject Admin: includes · Subject management UI
- Admin Sections → Classroom Admin: includes · Google Classroom management UI
- Admin Sections → Server Actions: mutates via · Admin forms call server actions for CRUD changes
- Files Browse → Schema: filters by · Academic browsing narrows by year, semister, section, category, and files data
- Classrooms Browse → Schema: filters by · Academic browsing narrows by year, semister, section, subject, and classroom files data
- Server Actions → Database: writes · Server actions persist through the database layer
- Auth API → Auth Setup: configures · Auth API is driven by shared Better Auth setup
- Auth Setup → Auth Client: pairs with · Server and client auth helpers form one boundary
- Auth Setup → Schema: uses · Auth depends on user and session tables
- Schema → Database: loads · Database client operates over the application schema
- Mail Sender → Auth Pages: supports · Password reset flow sends email from auth pages
- Keep-Alive → Database: pings · Keep-alive endpoint runs a simple database check