How poz659312-afk/version_3_testing works
1. This is a single Next.js 14 App Router monorepo-style web app: the same codebase contains the user-facing site, serverless API routes, auth flows, admin tools, and static educational content. The main architectural boundary is between src/app pages/routes, src/components UI, src/lib shared server/client logic, and public static assets/content.
2. The front-end is route-driven and mostly page-centric. Major user journeys live under src/app: home, about, courses, specializations, quiz, drive, profile, store, survey, calculator, certifications, youtube, ai, auth, and admin. Dynamic routes such as /quiz/[department]/[subject]/[quizId], /drive/[driveId]/[...folderPath], and /specialization/[department]/[level]/[subject] indicate that the UI is assembled from URL parameters rather than a central SPA state machine.
3. The quiz system is content-driven, not database-driven. Quiz definitions live in public/quizzes/** as JSON files (and a few JS files for operating system quizzes), so the browser and server can read standardized quiz payloads directly from static assets. The quiz page and src/components/quiz-system/quiz-interface.tsx render the experience, while API routes like src/app/api/quiz/questions, get-score, and compute-score support question retrieval and scoring.
4. Persistent platform data is handled by Supabase/PostgreSQL. The src/lib/supabase/{client,server,admin}.ts files show separate access layers for browser, server-side, and privileged operations. This database backs user accounts, stats, tournament/score state, token storage, deletion workflows, and likely quiz department metadata; the supabase/migrations and seed SQL files define the schema bootstrap.
5. Authentication is a custom flow layered on top of Supabase and JWT/cookie helpers. Public auth pages are under src/app/auth, while API routes cover login, OTP sending, token generation, password reset, and Google callback completion. middleware.ts, src/lib/auth*.ts, jwt-utils.ts, token-utils.ts, and security-middleware.ts indicate that route protection, session handling, and security checks are enforced at the edge/server boundary rather than inside individual pages.
6. Google Drive integration is one of the main backend subsystems. The flow starts with OAuth routes under src/app/api/google-drive/auth and callback, then continues through file operations (files, upload, delete, rename, create-folder, search-folders, get-upload-url, check-access, token-refresh). The browser uses the Drive pages/components, while the server stores and refreshes tokens and exposes secure, time-limited access through secure-drive-urls.ts and related helpers.
7. AI and document-processing features form a separate service boundary. The app exposes AI pages plus routes for chat, PDF extraction, and image-to-text, and document routes for upload/query. Supporting libraries such as gemini-client.ts, document-processor.ts, file-processor.ts, and python-backend-client.ts show that requests may be forwarded to external AI/processing services and then normalized before returning to the UI.
8. Admin and operational tooling are first-class parts of the backend. src/app/admin has a dedicated dashboard client and actions layer, backed by src/lib/admin-operations.ts and audit-log.ts. There are also debug, health, and token-monitoring routes/components, which suggests admins can inspect auth state, drive tokens, and system health without going through normal user flows.
9. Background automation is implemented with cron-triggered API routes, not a separate worker service. The important jobs are token refresh (/api/cron/token-refresh) and deletion processing (/api/cron/process-deletions), with scripts/check-env.js and the README implying external scheduling via cron-job.org. This means recurring work still enters the system through HTTP route handlers.
10. Static content and media are packaged directly in public/. That includes audio cues, background videos, a Lottie file, a drive tree HTML snapshot, and many course/quiz assets. This is a key architectural boundary: learning content is shipped with the repo and served as static files, while dynamic platform state lives in Supabase and API routes.
11. Shared UI and interaction logic are concentrated in src/components and src/hooks. The repo uses a large shadcn/ui/Radix component set, plus custom animation, theme, notification, scroll, and mobile hooks. These components are mostly presentation or cross-cutting concerns; they do not own business data, but they strongly shape the app shell and user experience.
12. Build-time and maintenance scripts support content ingestion and database bootstrapping. scripts/extract-quizzes.ts, scripts/resolveConflicts.js, and scripts/seed-supabase.ts indicate an offline pipeline for preparing quiz content and seeding Supabase. In an architecture diagram, these belong outside the runtime request path, alongside the Supabase migration/seed layer.
13. If you draw the system, the clearest flow is: browser pages in src/app → shared UI/components → API routes in src/app/api → either static quiz assets in public, Supabase/Postgres, Google APIs, or external AI services. The platform is therefore a hybrid of static educational content, serverless application logic, and third-party integrations, with Supabase acting as the main stateful backend.
Main entry points: supabase Supabase layer · page.tsx Quiz route · google-drive Drive API · quiz Quiz API
Components 22
App routes
Next.js App Router pages, dynamic routes, and route handlers.
- Home · Landing page and primary entry point.
src/app/page.tsx - Journeys · Primary user-facing routes for courses, quiz, profile, store, survey, calculator, certifications, youtube, ai, and static policy pages.
src/app - Quiz route · Department/subject/quizId-driven quiz experience.
src/app/quiz/[department]/[subject]/[quizId]/page.tsx - Drive route · Drive browser with nested folder navigation by driveId and path.
src/app/drive/[driveId]/[...folderPath]/page.tsx - Specialization · Department/level/subject specialization flow.
src/app/specialization/[department]/[level]/[subject]/page.tsx - Admin dashboard · Operational dashboard and admin actions layer.
src/app/admin/page.tsx
API boundary
Serverless endpoints and background-triggered HTTP jobs.
- Auth API · Login, OTP, token generation, password reset, and callback completion.
src/app/api/auth - Quiz API · Question retrieval and score computation for content-driven quizzes.
src/app/api/quiz - Drive API · Google Drive file access, public files, and secure upload/download flows.
src/app/api/google-drive - AI API · Chat, PDF extraction, image-to-text, and related AI document services.
src/app/api/ai - Ops API · Health, debug, stats, recap, delete-account, cron jobs, calculator, survey, store, and user creation routes.
src/app/api
Shared UI
Reusable components and interaction shells used across routes.
- UI shell · Navigation, layout, theme, providers, notifications, and global interaction wrappers.
src/components - Quiz UI · Quiz interface and quiz-specific presentation logic.
src/components/quiz-system/quiz-interface.tsx - Drive UI · Drive manager, auth gate, and token/status overlays for Google Drive workflows.
src/components/GoogleDriveManager.tsx - Admin UI · Admin guards, monitoring, and dashboard controls.
src/components/AdminAuthGuard.tsx
Core logic
Shared auth, storage, integration, and domain helpers.
- Auth core · JWT, cookie, auth helpers, middleware, and route protection.
src/lib/auth.ts - Supabase layer · Client/server/admin Supabase access for persistent platform state.
src/lib/supabase - Integrations · Google Drive, Gemini, Python backend, document/file processing, and secure drive URLs.
src/lib/google-oauth.ts - Domain data · Department data, quiz levels, metadata, mapping, and tournament/recap support.
src/lib/department-data.ts
Content & storage
Static learning assets and database bootstrap.
- Quiz assets · Static quiz definitions and quiz media shipped in public assets.
public/quizzes - Public media · Audio, video, Lottie, and drive-tree snapshot assets served statically.
public - DB bootstrap · Supabase migrations and seed SQL for schema and initial data.
supabase/migrations/20260629_create_quiz_department.sql
Connections 24
- Home → UI shell: renders · Home page is built from the shared app shell.
- Journeys → UI shell: uses · Most route pages use the shared UI and providers.
- Quiz route → Quiz UI: renders · Quiz pages mount the dedicated quiz experience.
- Quiz route → Domain data: loads metadata · Quiz routing depends on department and quiz metadata helpers.
- Quiz route → Quiz API: fetches · Questions and scoring can be mediated by API routes.
- Quiz route → Quiz assets: reads · Quiz payloads come from static JSON/JS assets.
- Drive route → Drive UI: renders · Drive pages use the drive manager and auth gating UI.
- Drive route → Drive API: calls · Drive browsing and file actions go through secure APIs.
- Specialization → Domain data: uses · Specialization pages are driven by department hierarchy data.
- Admin dashboard → Admin UI: renders · Admin dashboard is wrapped with admin-specific UI and guards.
- Admin dashboard → Ops API: operates on · Admin actions and monitoring depend on operational APIs.
- Auth API → Auth core: enforces · Auth endpoints rely on JWT, cookies, and security helpers.
- Auth API → Supabase layer: persists · Session and account state are stored in Supabase.
- Quiz API → Quiz assets: reads · Quiz question endpoints serve static quiz content.
- Quiz API → Supabase layer: scores to · Score/state endpoints can persist user and tournament data.
- Drive API → Integrations: proxies · Google Drive operations are backed by OAuth and service helpers.
- Drive API → Supabase layer: stores tokens · Drive token state and access metadata live in Supabase.
- AI API → Integrations: forwards to · AI/document requests are normalized through external service clients.
- Ops API → Supabase layer: reads/writes · Stats, users, deletes, recap, and cron jobs work on platform state.
- Ops API → Auth core: protects · Operational endpoints depend on auth and middleware checks.
- UI shell → Public media: uses · Shared UI consumes static images, video, audio, and Lottie assets.
- Supabase layer → DB bootstrap: bootstrapped by · Supabase schema and seed files define the database foundation.
- Domain data → Quiz assets: derives from · Domain helpers interpret the packaged quiz corpus.
- Integrations → Drive API: supports · Integration helpers back the drive API surface.