# poz659312-afk/version_3_testing architecture

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

- Interactive diagram: https://gitdiagram.com/poz659312-afk/version_3_testing
- Repository: https://github.com/poz659312-afk/version_3_testing

## Overview

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: [`src/lib/supabase`](https://github.com/poz659312-afk/version_3_testing/tree/main/src/lib/supabase) (Supabase layer), [`src/app/quiz/[department]/[subject]/[quizId]/page.tsx`](https://github.com/poz659312-afk/version_3_testing/blob/main/src/app/quiz/[department]/[subject]/[quizId]/page.tsx) (Quiz route), [`src/app/api/google-drive`](https://github.com/poz659312-afk/version_3_testing/tree/main/src/app/api/google-drive) (Drive API), [`src/app/api/quiz`](https://github.com/poz659312-afk/version_3_testing/tree/main/src/app/api/quiz) (Quiz API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["App routes"]
  node_app_home["Home<br/>route page<br/>[page.tsx]"]
  node_app_journeys["Journeys<br/>route pages"]
  node_app_quiz["Quiz route<br/>dynamic route<br/>[page.tsx]"]
  node_app_drive["Drive route<br/>dynamic route<br/>[page.tsx]"]
  node_app_specialization["Specialization<br/>dynamic route<br/>[page.tsx]"]
  node_app_admin["Admin dashboard<br/>admin page<br/>[page.tsx]"]
end

subgraph group_api["API boundary"]
  node_api_auth["Auth API<br/>auth endpoints"]
  node_api_quiz["Quiz API<br/>quiz endpoints"]
  node_api_drive["Drive API<br/>drive endpoints"]
  node_api_ai["AI API<br/>ai endpoints"]
  node_api_ops["Ops API<br/>system endpoints"]
end

subgraph group_ui["Shared UI"]
  node_ui_shell["UI shell<br/>shared components"]
  node_ui_quiz["Quiz UI<br/>experience components<br/>[quiz-interface.tsx]"]
  node_ui_drive["Drive UI<br/>experience components"]
  node_ui_admin["Admin UI<br/>ops components<br/>[AdminAuthGuard.tsx]"]
end

subgraph group_lib["Core logic"]
  node_lib_auth["Auth core<br/>session/security<br/>[auth.ts]"]
  node_lib_supabase[("Supabase layer<br/>database access")]
  node_lib_integrations["Integrations<br/>external services<br/>[google-oauth.ts]"]
  node_lib_domain["Domain data<br/>quiz/content logic<br/>[department-data.ts]"]
end

subgraph group_content["Content & storage"]
  node_content_quizzes["Quiz assets<br/>static content"]
  node_content_media["Public media<br/>static assets"]
  node_content_supabase["DB bootstrap<br/>migrations and seed"]
end

node_app_home -->|"renders"| node_ui_shell
node_app_journeys -->|"uses"| node_ui_shell
node_app_quiz -->|"renders"| node_ui_quiz
node_app_quiz -->|"loads metadata"| node_lib_domain
node_app_quiz -->|"fetches"| node_api_quiz
node_app_quiz -->|"reads"| node_content_quizzes
node_app_drive -->|"renders"| node_ui_drive
node_app_drive -->|"calls"| node_api_drive
node_app_specialization -->|"uses"| node_lib_domain
node_app_admin -->|"renders"| node_ui_admin
node_app_admin -->|"operates on"| node_api_ops
node_api_auth -->|"enforces"| node_lib_auth
node_api_auth -->|"persists"| node_lib_supabase
node_api_quiz -->|"reads"| node_content_quizzes
node_api_quiz -->|"scores to"| node_lib_supabase
node_api_drive -->|"proxies"| node_lib_integrations
node_api_drive -->|"stores tokens"| node_lib_supabase
node_api_ai -->|"forwards to"| node_lib_integrations
node_api_ops -->|"reads/writes"| node_lib_supabase
node_api_ops -->|"protects"| node_lib_auth
node_ui_shell -->|"uses"| node_content_media
node_lib_supabase -->|"bootstrapped by"| node_content_supabase
node_lib_domain -->|"derives from"| node_content_quizzes
node_lib_integrations -.->|"supports"| node_api_drive

click node_app_home "https://github.com/poz659312-afk/version_3_testing/blob/main/src/app/page.tsx"
click node_app_journeys "https://github.com/poz659312-afk/version_3_testing/tree/main/src/app"
click node_app_quiz "https://github.com/poz659312-afk/version_3_testing/blob/main/src/app/quiz/[department]/[subject]/[quizId]/page.tsx"
click node_app_drive "https://github.com/poz659312-afk/version_3_testing/blob/main/src/app/drive/[driveId]/[...folderPath]/page.tsx"
click node_app_specialization "https://github.com/poz659312-afk/version_3_testing/blob/main/src/app/specialization/[department]/[level]/[subject]/page.tsx"
click node_app_admin "https://github.com/poz659312-afk/version_3_testing/blob/main/src/app/admin/page.tsx"
click node_api_auth "https://github.com/poz659312-afk/version_3_testing/tree/main/src/app/api/auth"
click node_api_quiz "https://github.com/poz659312-afk/version_3_testing/tree/main/src/app/api/quiz"
click node_api_drive "https://github.com/poz659312-afk/version_3_testing/tree/main/src/app/api/google-drive"
click node_api_ai "https://github.com/poz659312-afk/version_3_testing/tree/main/src/app/api/ai"
click node_api_ops "https://github.com/poz659312-afk/version_3_testing/tree/main/src/app/api"
click node_ui_shell "https://github.com/poz659312-afk/version_3_testing/tree/main/src/components"
click node_ui_quiz "https://github.com/poz659312-afk/version_3_testing/blob/main/src/components/quiz-system/quiz-interface.tsx"
click node_ui_drive "https://github.com/poz659312-afk/version_3_testing/blob/main/src/components/GoogleDriveManager.tsx"
click node_ui_admin "https://github.com/poz659312-afk/version_3_testing/blob/main/src/components/AdminAuthGuard.tsx"
click node_lib_auth "https://github.com/poz659312-afk/version_3_testing/blob/main/src/lib/auth.ts"
click node_lib_supabase "https://github.com/poz659312-afk/version_3_testing/tree/main/src/lib/supabase"
click node_lib_integrations "https://github.com/poz659312-afk/version_3_testing/blob/main/src/lib/google-oauth.ts"
click node_lib_domain "https://github.com/poz659312-afk/version_3_testing/blob/main/src/lib/department-data.ts"
click node_content_quizzes "https://github.com/poz659312-afk/version_3_testing/tree/main/public/quizzes"
click node_content_media "https://github.com/poz659312-afk/version_3_testing/tree/main/public"
click node_content_supabase "https://github.com/poz659312-afk/version_3_testing/blob/main/supabase/migrations/20260629_create_quiz_department.sql"

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_home,node_app_journeys,node_app_quiz,node_app_drive,node_app_specialization,node_app_admin toneBlue
class node_api_auth,node_api_quiz,node_api_drive,node_api_ai,node_api_ops toneAmber
class node_ui_shell,node_ui_quiz,node_ui_drive,node_ui_admin toneMint
class node_lib_auth,node_lib_supabase,node_lib_integrations,node_lib_domain toneRose
class node_content_quizzes,node_content_media,node_content_supabase toneIndigo
```

## Components

### App routes

Next.js App Router pages, dynamic routes, and route handlers.

- [Home](https://github.com/poz659312-afk/version_3_testing/blob/main/src/app/page.tsx): route page · Landing page and primary entry point. · `src/app/page.tsx`
- [Journeys](https://github.com/poz659312-afk/version_3_testing/tree/main/src/app): route pages · Primary user-facing routes for courses, quiz, profile, store, survey, calculator, certifications, youtube, ai, and static policy pages. · `src/app`
- [Quiz route](https://github.com/poz659312-afk/version_3_testing/blob/main/src/app/quiz/[department]/[subject]/[quizId]/page.tsx): dynamic route · Department/subject/quizId-driven quiz experience. · `src/app/quiz/[department]/[subject]/[quizId]/page.tsx`
- [Drive route](https://github.com/poz659312-afk/version_3_testing/blob/main/src/app/drive/[driveId]/[...folderPath]/page.tsx): dynamic route · Drive browser with nested folder navigation by driveId and path. · `src/app/drive/[driveId]/[...folderPath]/page.tsx`
- [Specialization](https://github.com/poz659312-afk/version_3_testing/blob/main/src/app/specialization/[department]/[level]/[subject]/page.tsx): dynamic route · Department/level/subject specialization flow. · `src/app/specialization/[department]/[level]/[subject]/page.tsx`
- [Admin dashboard](https://github.com/poz659312-afk/version_3_testing/blob/main/src/app/admin/page.tsx): admin page · Operational dashboard and admin actions layer. · `src/app/admin/page.tsx`

### API boundary

Serverless endpoints and background-triggered HTTP jobs.

- [Auth API](https://github.com/poz659312-afk/version_3_testing/tree/main/src/app/api/auth): auth endpoints · Login, OTP, token generation, password reset, and callback completion. · `src/app/api/auth`
- [Quiz API](https://github.com/poz659312-afk/version_3_testing/tree/main/src/app/api/quiz): quiz endpoints · Question retrieval and score computation for content-driven quizzes. · `src/app/api/quiz`
- [Drive API](https://github.com/poz659312-afk/version_3_testing/tree/main/src/app/api/google-drive): drive endpoints · Google Drive file access, public files, and secure upload/download flows. · `src/app/api/google-drive`
- [AI API](https://github.com/poz659312-afk/version_3_testing/tree/main/src/app/api/ai): ai endpoints · Chat, PDF extraction, image-to-text, and related AI document services. · `src/app/api/ai`
- [Ops API](https://github.com/poz659312-afk/version_3_testing/tree/main/src/app/api): system endpoints · 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](https://github.com/poz659312-afk/version_3_testing/tree/main/src/components): shared components · Navigation, layout, theme, providers, notifications, and global interaction wrappers. · `src/components`
- [Quiz UI](https://github.com/poz659312-afk/version_3_testing/blob/main/src/components/quiz-system/quiz-interface.tsx): experience components · Quiz interface and quiz-specific presentation logic. · `src/components/quiz-system/quiz-interface.tsx`
- [Drive UI](https://github.com/poz659312-afk/version_3_testing/blob/main/src/components/GoogleDriveManager.tsx): experience components · Drive manager, auth gate, and token/status overlays for Google Drive workflows. · `src/components/GoogleDriveManager.tsx`
- [Admin UI](https://github.com/poz659312-afk/version_3_testing/blob/main/src/components/AdminAuthGuard.tsx): ops components · Admin guards, monitoring, and dashboard controls. · `src/components/AdminAuthGuard.tsx`

### Core logic

Shared auth, storage, integration, and domain helpers.

- [Auth core](https://github.com/poz659312-afk/version_3_testing/blob/main/src/lib/auth.ts): session/security · JWT, cookie, auth helpers, middleware, and route protection. · `src/lib/auth.ts`
- [Supabase layer](https://github.com/poz659312-afk/version_3_testing/tree/main/src/lib/supabase): database access · Client/server/admin Supabase access for persistent platform state. · `src/lib/supabase`
- [Integrations](https://github.com/poz659312-afk/version_3_testing/blob/main/src/lib/google-oauth.ts): external services · Google Drive, Gemini, Python backend, document/file processing, and secure drive URLs. · `src/lib/google-oauth.ts`
- [Domain data](https://github.com/poz659312-afk/version_3_testing/blob/main/src/lib/department-data.ts): quiz/content logic · 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](https://github.com/poz659312-afk/version_3_testing/tree/main/public/quizzes): static content · Static quiz definitions and quiz media shipped in public assets. · `public/quizzes`
- [Public media](https://github.com/poz659312-afk/version_3_testing/tree/main/public): static assets · Audio, video, Lottie, and drive-tree snapshot assets served statically. · `public`
- [DB bootstrap](https://github.com/poz659312-afk/version_3_testing/blob/main/supabase/migrations/20260629_create_quiz_department.sql): migrations and seed · Supabase migrations and seed SQL for schema and initial data. · `supabase/migrations/20260629_create_quiz_department.sql`

## Connections

- 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.
