# wangjacks/career-explorer architecture

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

- Interactive diagram: https://gitdiagram.com/wangjacks/career-explorer
- Repository: https://github.com/wangjacks/career-explorer

## Overview

Career Explorer is a three-role student career-interest product: students activate accounts, select tags and build a profile through a multi-step form, while teachers and admins manage classes and review data. Admin capabilities also include statistics, exports, audit, settings and media/storage administration. The graph connects only relationships visible in sampled source or README; unsampled feature routes are grouped at their exact existing directories, and unsupported internal call paths are omitted.

Main entry points: [`src/lib/db.ts`](https://github.com/wangjacks/career-explorer/blob/main/src/lib/db.ts) (Database adapter), [`src/lib/storage.ts`](https://github.com/wangjacks/career-explorer/blob/main/src/lib/storage.ts) (Storage abstraction), [`src/app/api/auth`](https://github.com/wangjacks/career-explorer/tree/main/src/app/api/auth) (Login and activation), [`src/app/api/manage/export/route.ts`](https://github.com/wangjacks/career-explorer/blob/main/src/app/api/manage/export/route.ts) (Data exports)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["User experience"]
  node_web["Pages and dashboards"]
end

subgraph group_identity["Identity and setup"]
  node_auth["Login and activation"]
  node_session["Session tokens<br/>[token.ts]"]
  node_account["Account verification<br/>[auth.ts]"]
  node_setup["Installation setup"]
end

subgraph group_profiles["Profiles and discovery"]
  node_profileform["Profile workflow"]
  node_drafts["Draft persistence<br/>[useProfileDraft.ts]"]
  node_profileapi["Profile submissions"]
  node_discovery["Tag and word cloud"]
  node_sharedapi["Shared profile API"]
end

subgraph group_management["Administration"]
  node_dashboards["Role dashboards"]
  node_classadmin["Class and people management"]
  node_tagadmin["Tag administration"]
  node_analytics["Statistics and overview"]
  node_exports["Data exports<br/>[route.ts]"]
  node_audit["Audit logging<br/>[audit.ts]"]
  node_settings["Settings and profile config"]
  node_mediaadmin["Media operations"]
  node_storageadmin["Storage management<br/>[route.ts]"]
end

subgraph group_platform["Data and media"]
  node_database[("Database adapter<br/>[db.ts]")]
  node_sqladapters[("MySQL and SQLite<br/>[db-mysql.ts]")]
  node_storage["Storage abstraction<br/>[storage.ts]"]
  node_local[("Local files<br/>[storage-local.ts]")]
  node_s3[("S3 object storage<br/>[storage-s3.ts]")]
  node_uploads["Image upload API<br/>[route.ts]"]
  node_images["Storage-aware images<br/>[StorageImage.tsx]"]
end

node_students(("Students"))
node_teachers(("Teachers"))
node_admins(("Administrators"))

node_students -->|"use"| node_web
node_teachers -->|"use"| node_web
node_admins -->|"use"| node_web
node_web -.->|"authenticate"| node_auth
node_auth -->|"verify password"| node_account
node_auth -->|"sign and verify"| node_session
node_auth -->|"look up users"| node_database
node_setup -->|"configure adapter"| node_database
node_students -->|"complete"| node_profileform
node_profileform -->|"save draft"| node_drafts
node_profileform -.->|"submit profile"| node_profileapi
node_students -->|"explore interests"| node_discovery
node_sharedapi -->|"read and write profiles"| node_database
node_dashboards -->|"view statistics"| node_analytics
node_admins -->|"manage classes"| node_classadmin
node_teachers -->|"manage class data"| node_classadmin
node_admins -->|"manage tags"| node_tagadmin
node_admins -->|"export data"| node_exports
node_exports -->|"read records"| node_database
node_exports -->|"read and sign images"| node_storage
node_exports -->|"record actions"| node_audit
node_admins -->|"review activity"| node_audit
node_admins -->|"configure system"| node_settings
node_admins -.->|"manage media"| node_mediaadmin
node_admins -->|"configure backends"| node_storageadmin
node_storageadmin -->|"manage backend records"| node_database
node_database -->|"select adapter"| node_sqladapters
node_uploads -->|"read storage config"| node_database
node_uploads -->|"store uploaded files"| node_storage
node_storage -->|"create local adapter"| node_local
node_storage -->|"create S3 adapter"| node_s3
node_images -->|"resolve file URL"| node_storage

click node_web "https://github.com/wangjacks/career-explorer/tree/main/src/app"
click node_auth "https://github.com/wangjacks/career-explorer/tree/main/src/app/api/auth"
click node_session "https://github.com/wangjacks/career-explorer/blob/main/src/lib/token.ts"
click node_account "https://github.com/wangjacks/career-explorer/blob/main/src/lib/auth.ts"
click node_setup "https://github.com/wangjacks/career-explorer/tree/main/src/app/api/setup"
click node_profileform "https://github.com/wangjacks/career-explorer/tree/main/src/app/form/create-profile"
click node_drafts "https://github.com/wangjacks/career-explorer/blob/main/src/hooks/useProfileDraft.ts"
click node_profileapi "https://github.com/wangjacks/career-explorer/tree/main/src/app/api/shared/profile"
click node_discovery "https://github.com/wangjacks/career-explorer/blob/main/src/components/WordCloudCanvas.tsx"
click node_sharedapi "https://github.com/wangjacks/career-explorer/tree/main/src/app/api/shared/profile"
click node_dashboards "https://github.com/wangjacks/career-explorer/tree/main/src/app/dashboard"
click node_classadmin "https://github.com/wangjacks/career-explorer/tree/main/src/app/api/manage/classes"
click node_tagadmin "https://github.com/wangjacks/career-explorer/tree/main/src/app/api/manage/tags"
click node_analytics "https://github.com/wangjacks/career-explorer/tree/main/src/app/api/manage/stats"
click node_exports "https://github.com/wangjacks/career-explorer/blob/main/src/app/api/manage/export/route.ts"
click node_audit "https://github.com/wangjacks/career-explorer/blob/main/src/lib/audit.ts"
click node_settings "https://github.com/wangjacks/career-explorer/tree/main/src/app/api/manage/settings"
click node_mediaadmin "https://github.com/wangjacks/career-explorer/tree/main/src/app/api/manage/media"
click node_storageadmin "https://github.com/wangjacks/career-explorer/blob/main/src/app/api/manage/storage/route.ts"
click node_database "https://github.com/wangjacks/career-explorer/blob/main/src/lib/db.ts"
click node_sqladapters "https://github.com/wangjacks/career-explorer/blob/main/src/lib/db-mysql.ts"
click node_storage "https://github.com/wangjacks/career-explorer/blob/main/src/lib/storage.ts"
click node_local "https://github.com/wangjacks/career-explorer/blob/main/src/lib/storage-local.ts"
click node_s3 "https://github.com/wangjacks/career-explorer/blob/main/src/lib/storage-s3.ts"
click node_uploads "https://github.com/wangjacks/career-explorer/blob/main/src/app/api/upload/route.ts"
click node_images "https://github.com/wangjacks/career-explorer/blob/main/src/components/StorageImage.tsx"

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_web toneBlue
class node_auth,node_session,node_account,node_setup toneAmber
class node_profileform,node_drafts,node_profileapi,node_discovery,node_sharedapi toneMint
class node_dashboards,node_classadmin,node_tagadmin,node_analytics,node_exports,node_audit,node_settings,node_mediaadmin,node_storageadmin toneRose
class node_database,node_sqladapters,node_storage,node_local,node_s3,node_uploads,node_images,node_students,node_teachers,node_admins toneIndigo
```

## Components

### User experience

- [Pages and dashboards](https://github.com/wangjacks/career-explorer/tree/main/src/app): `src/app`

### Identity and setup

- [Login and activation](https://github.com/wangjacks/career-explorer/tree/main/src/app/api/auth): `src/app/api/auth`
- [Session tokens](https://github.com/wangjacks/career-explorer/blob/main/src/lib/token.ts): `src/lib/token.ts`
- [Account verification](https://github.com/wangjacks/career-explorer/blob/main/src/lib/auth.ts): `src/lib/auth.ts`
- [Installation setup](https://github.com/wangjacks/career-explorer/tree/main/src/app/api/setup): `src/app/api/setup`

### Profiles and discovery

- [Profile workflow](https://github.com/wangjacks/career-explorer/tree/main/src/app/form/create-profile): `src/app/form/create-profile`
- [Draft persistence](https://github.com/wangjacks/career-explorer/blob/main/src/hooks/useProfileDraft.ts): `src/hooks/useProfileDraft.ts`
- [Profile submissions](https://github.com/wangjacks/career-explorer/tree/main/src/app/api/shared/profile): `src/app/api/shared/profile`
- [Tag and word cloud](https://github.com/wangjacks/career-explorer/blob/main/src/components/WordCloudCanvas.tsx): `src/components/WordCloudCanvas.tsx`
- [Shared profile API](https://github.com/wangjacks/career-explorer/tree/main/src/app/api/shared/profile): `src/app/api/shared/profile`

### Administration

- [Role dashboards](https://github.com/wangjacks/career-explorer/tree/main/src/app/dashboard): `src/app/dashboard`
- [Class and people management](https://github.com/wangjacks/career-explorer/tree/main/src/app/api/manage/classes): `src/app/api/manage/classes`
- [Tag administration](https://github.com/wangjacks/career-explorer/tree/main/src/app/api/manage/tags): `src/app/api/manage/tags`
- [Statistics and overview](https://github.com/wangjacks/career-explorer/tree/main/src/app/api/manage/stats): `src/app/api/manage/stats`
- [Data exports](https://github.com/wangjacks/career-explorer/blob/main/src/app/api/manage/export/route.ts): `src/app/api/manage/export/route.ts`
- [Audit logging](https://github.com/wangjacks/career-explorer/blob/main/src/lib/audit.ts): `src/lib/audit.ts`
- [Settings and profile config](https://github.com/wangjacks/career-explorer/tree/main/src/app/api/manage/settings): `src/app/api/manage/settings`
- [Media operations](https://github.com/wangjacks/career-explorer/tree/main/src/app/api/manage/media): `src/app/api/manage/media`
- [Storage management](https://github.com/wangjacks/career-explorer/blob/main/src/app/api/manage/storage/route.ts): `src/app/api/manage/storage/route.ts`

### Data and media

- [Database adapter](https://github.com/wangjacks/career-explorer/blob/main/src/lib/db.ts): `src/lib/db.ts`
- [MySQL and SQLite](https://github.com/wangjacks/career-explorer/blob/main/src/lib/db-mysql.ts): `src/lib/db-mysql.ts`
- [Storage abstraction](https://github.com/wangjacks/career-explorer/blob/main/src/lib/storage.ts): `src/lib/storage.ts`
- [Local files](https://github.com/wangjacks/career-explorer/blob/main/src/lib/storage-local.ts): `src/lib/storage-local.ts`
- [S3 object storage](https://github.com/wangjacks/career-explorer/blob/main/src/lib/storage-s3.ts): `src/lib/storage-s3.ts`
- [Image upload API](https://github.com/wangjacks/career-explorer/blob/main/src/app/api/upload/route.ts): `src/app/api/upload/route.ts`
- [Storage-aware images](https://github.com/wangjacks/career-explorer/blob/main/src/components/StorageImage.tsx): `src/components/StorageImage.tsx`

### Other components

- **Students**
- **Teachers**
- **Administrators**

## Connections

- Students → Pages and dashboards: use
- Teachers → Pages and dashboards: use
- Administrators → Pages and dashboards: use
- Pages and dashboards → Login and activation: authenticate
- Login and activation → Account verification: verify password (evidence: `src/app/api/auth/route.ts`)
- Login and activation → Session tokens: sign and verify (evidence: `src/app/api/auth/route.ts`)
- Login and activation → Database adapter: look up users (evidence: `src/app/api/auth/route.ts`)
- Installation setup → Database adapter: configure adapter (evidence: `src/app/api/setup/route.ts`)
- Students → Profile workflow: complete
- Profile workflow → Draft persistence: save draft (evidence: `src/hooks/useProfileDraft.ts`)
- Profile workflow → Profile submissions: submit profile
- Students → Tag and word cloud: explore interests
- Shared profile API → Database adapter: read and write profiles (evidence: `src/app/api/shared/profile/route.ts`)
- Role dashboards → Statistics and overview: view statistics
- Administrators → Class and people management: manage classes
- Teachers → Class and people management: manage class data
- Administrators → Tag administration: manage tags
- Administrators → Data exports: export data
- Data exports → Database adapter: read records (evidence: `src/app/api/manage/export/route.ts`)
- Data exports → Storage abstraction: read and sign images (evidence: `src/app/api/manage/export/route.ts`)
- Data exports → Audit logging: record actions (evidence: `src/app/api/manage/export/route.ts`)
- Administrators → Audit logging: review activity
- Administrators → Settings and profile config: configure system
- Administrators → Media operations: manage media
- Administrators → Storage management: configure backends
- Storage management → Database adapter: manage backend records (evidence: `src/app/api/manage/storage/route.ts`)
- Database adapter → MySQL and SQLite: select adapter (evidence: `src/lib/db.ts`)
- Image upload API → Database adapter: read storage config (evidence: `src/app/api/upload/route.ts`)
- Image upload API → Storage abstraction: store uploaded files (evidence: `src/app/api/upload/route.ts`)
- Storage abstraction → Local files: create local adapter (evidence: `src/lib/storage.ts`)
- Storage abstraction → S3 object storage: create S3 adapter (evidence: `src/lib/storage.ts`)
- Storage-aware images → Storage abstraction: resolve file URL (evidence: `src/components/StorageImage.tsx`)
