dewanshakib/uu-unifile-v1

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