# vasavi-suniganti/yuki architecture

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

- Interactive diagram: https://gitdiagram.com/vasavi-suniganti/yuki
- Repository: https://github.com/vasavi-suniganti/yuki

## Overview

POLARIS is a polar-science repository and outreach portal. Users explore expeditions, datasets, publications, maps, and learning resources; authenticated researchers submit material, reviewers process it, and media staff prepare public-facing stories. The backend provides AI analysis, metadata and dataset processing, review workflow, and a public data API, with Firebase-backed identity and records plus demo fallbacks. The graph preserves README-documented feature areas even where their implementation was not sampled; those broader connections are marked as unverified where source evidence is unavailable.

Main entry points: [`client/src/App.tsx`](https://github.com/vasavi-suniganti/yuki/blob/main/client/src/App.tsx) (Page router), [`server/src/routes/api.ts`](https://github.com/vasavi-suniganti/yuki/blob/main/server/src/routes/api.ts) (Product API routes), [`client/src/lib/auth.tsx`](https://github.com/vasavi-suniganti/yuki/blob/main/client/src/lib/auth.tsx) (Identity and roles), [`client/src/pages/ResearcherDashboard.tsx`](https://github.com/vasavi-suniganti/yuki/blob/main/client/src/pages/ResearcherDashboard.tsx) (Researcher workspace)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_discovery["Public Discovery"]
  node_app["Page router<br/>[App.tsx]"]
  node_explore["Science discovery<br/>[Explore.tsx]"]
  node_expeditions["Expedition records<br/>[Expeditions.tsx]"]
  node_research_publications["Research library<br/>[Research.tsx]"]
end

subgraph group_research["Research Tools"]
  node_datasets["Dataset explorer<br/>[Datasets.tsx]"]
  node_maps["Maps and time<br/>[MapTimeGraph.tsx]"]
  node_ai_page["AI research tools<br/>[AI.tsx]"]
  node_ai_engine["Grounded AI engine<br/>[ai.ts]"]
  node_retrieval["Evidence retrieval<br/>[retrieval.ts]"]
  node_parser["Dataset parser<br/>[datasetParser.ts]"]
end

subgraph group_governance["Curation and Review"]
  node_researcher["Researcher workspace"]
  node_reviewer["Reviewer workspace"]
  node_media["Media studio"]
  node_admin["Admin workspace<br/>[AdminDashboard.tsx]"]
  node_signature["Media features"]
  node_metadata["Metadata extraction"]
  node_review_flow["Review state machine<br/>[reviewWorkflow.ts]"]
end

subgraph group_platform["Platform Services"]
  node_auth["Identity and roles<br/>[auth.tsx]"]
  node_client_firebase["Firebase client<br/>[firebase.ts]"]
  node_api_client["API client<br/>[api.ts]"]
  node_data_service["Typed data service<br/>[dataService.ts]"]
  node_demo_data["Demo records<br/>[demo.ts]"]
  node_server["API server<br/>[index.ts]"]
  node_api_routes["Product API routes<br/>[api.ts]"]
  node_open_api["Open data API<br/>[openApi.ts]"]
  node_server_auth["Request authorization<br/>[auth.ts]"]
  node_server_firebase["Firebase Admin<br/>[firebase.ts]"]
  node_store[("Firestore")]
  node_firebase_auth["Firebase Authentication"]
end

subgraph group_learning["Education"]
  node_learning["Learning hub"]
  node_quiz["Quiz engine"]
  node_learning_content["Learning content<br/>[learningContent.ts]"]
  node_student_learning["Student progress<br/>[studentLearning.ts]"]
end

node_visitor(("Portal visitor"))

node_visitor -->|"opens portal"| node_app
node_app -->|"routes to"| node_explore
node_app -->|"routes to"| node_expeditions
node_app -->|"routes to"| node_datasets
node_app -->|"routes to"| node_maps
node_app -->|"routes to"| node_research_publications
node_app -->|"routes to"| node_ai_page
node_app -->|"guards route"| node_researcher
node_app -->|"guards route"| node_reviewer
node_app -->|"guards route"| node_media
node_app -->|"guards route"| node_admin
node_app -->|"routes to"| node_learning
node_researcher -->|"uses identity"| node_auth
node_reviewer -->|"uses identity"| node_auth
node_media -->|"uses identity"| node_auth
node_auth -->|"uses Firebase"| node_client_firebase
node_client_firebase -.->|"authenticates with"| node_firebase_auth
node_auth -.->|"reads user profiles"| node_store
node_researcher -->|"calls API"| node_api_client
node_reviewer -->|"calls API"| node_api_client
node_data_service -->|"uses Firebase"| node_client_firebase
node_data_service -->|"uses API client"| node_api_client
node_researcher -->|"uses fallback data"| node_demo_data
node_media -->|"saves story"| node_signature
node_learning -.->|"offers quizzes"| node_quiz
node_quiz -->|"uses questions"| node_learning_content
node_quiz -.->|"records progress"| node_student_learning
node_server -->|"mounts routes"| node_api_routes
node_server -->|"mounts routes"| node_open_api
node_api_routes -->|"uses middleware"| node_server_auth
node_server_auth -->|"verifies identity"| node_server_firebase
node_api_routes -->|"dispatches AI"| node_ai_engine
node_ai_engine -->|"retrieves evidence"| node_retrieval
node_api_routes -->|"parses datasets"| node_parser
node_api_routes -->|"extracts metadata"| node_metadata
node_api_routes -->|"creates reviews"| node_review_flow
node_review_flow -->|"reads and writes"| node_server_firebase
node_server_auth -->|"loads user roles"| node_store
node_open_api -->|"reads records"| node_server_firebase
node_server_firebase -.->|"accesses database"| node_store
node_api_client -.->|"sends requests"| node_server
node_ai_page -.->|"requests AI features"| node_api_routes
node_datasets -.->|"requests processing"| node_api_routes

click node_app "https://github.com/vasavi-suniganti/yuki/blob/main/client/src/App.tsx"
click node_explore "https://github.com/vasavi-suniganti/yuki/blob/main/client/src/pages/Explore.tsx"
click node_expeditions "https://github.com/vasavi-suniganti/yuki/blob/main/client/src/pages/Expeditions.tsx"
click node_datasets "https://github.com/vasavi-suniganti/yuki/blob/main/client/src/pages/Datasets.tsx"
click node_maps "https://github.com/vasavi-suniganti/yuki/blob/main/client/src/pages/MapTimeGraph.tsx"
click node_research_publications "https://github.com/vasavi-suniganti/yuki/blob/main/client/src/pages/Research.tsx"
click node_ai_page "https://github.com/vasavi-suniganti/yuki/blob/main/client/src/pages/AI.tsx"
click node_researcher "https://github.com/vasavi-suniganti/yuki/blob/main/client/src/pages/ResearcherDashboard.tsx"
click node_reviewer "https://github.com/vasavi-suniganti/yuki/blob/main/client/src/pages/ReviewerDashboard.tsx"
click node_media "https://github.com/vasavi-suniganti/yuki/blob/main/client/src/pages/MediaManagerDashboard.tsx"
click node_admin "https://github.com/vasavi-suniganti/yuki/blob/main/client/src/pages/AdminDashboard.tsx"
click node_auth "https://github.com/vasavi-suniganti/yuki/blob/main/client/src/lib/auth.tsx"
click node_client_firebase "https://github.com/vasavi-suniganti/yuki/blob/main/client/src/lib/firebase.ts"
click node_api_client "https://github.com/vasavi-suniganti/yuki/blob/main/client/src/lib/api.ts"
click node_data_service "https://github.com/vasavi-suniganti/yuki/blob/main/client/src/services/dataService.ts"
click node_demo_data "https://github.com/vasavi-suniganti/yuki/blob/main/client/src/data/demo.ts"
click node_signature "https://github.com/vasavi-suniganti/yuki/blob/main/client/src/lib/signatureFeatures.ts"
click node_learning "https://github.com/vasavi-suniganti/yuki/blob/main/client/src/pages/EducationVirtual.tsx"
click node_quiz "https://github.com/vasavi-suniganti/yuki/blob/main/client/src/components/AdvancedQuizEngine.tsx"
click node_learning_content "https://github.com/vasavi-suniganti/yuki/blob/main/client/src/data/learningContent.ts"
click node_student_learning "https://github.com/vasavi-suniganti/yuki/blob/main/client/src/lib/studentLearning.ts"
click node_server "https://github.com/vasavi-suniganti/yuki/blob/main/server/src/index.ts"
click node_api_routes "https://github.com/vasavi-suniganti/yuki/blob/main/server/src/routes/api.ts"
click node_open_api "https://github.com/vasavi-suniganti/yuki/blob/main/server/src/routes/openApi.ts"
click node_server_auth "https://github.com/vasavi-suniganti/yuki/blob/main/server/src/middleware/auth.ts"
click node_server_firebase "https://github.com/vasavi-suniganti/yuki/blob/main/server/src/services/firebase.ts"
click node_ai_engine "https://github.com/vasavi-suniganti/yuki/blob/main/server/src/services/ai.ts"
click node_retrieval "https://github.com/vasavi-suniganti/yuki/blob/main/server/src/services/retrieval.ts"
click node_parser "https://github.com/vasavi-suniganti/yuki/blob/main/server/src/services/datasetParser.ts"
click node_metadata "https://github.com/vasavi-suniganti/yuki/blob/main/server/src/services/metadataExtractor.ts"
click node_review_flow "https://github.com/vasavi-suniganti/yuki/blob/main/server/src/services/reviewWorkflow.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,node_explore,node_expeditions,node_research_publications toneBlue
class node_datasets,node_maps,node_ai_page,node_ai_engine,node_retrieval,node_parser toneAmber
class node_researcher,node_reviewer,node_media,node_admin,node_signature,node_metadata,node_review_flow toneMint
class node_auth,node_client_firebase,node_api_client,node_data_service,node_demo_data,node_server,node_api_routes,node_open_api,node_server_auth,node_server_firebase,node_store,node_firebase_auth toneRose
class node_learning,node_quiz,node_learning_content,node_student_learning,node_visitor toneIndigo
```

## Components

### Public Discovery

- [Page router](https://github.com/vasavi-suniganti/yuki/blob/main/client/src/App.tsx): `client/src/App.tsx`
- [Science discovery](https://github.com/vasavi-suniganti/yuki/blob/main/client/src/pages/Explore.tsx): `client/src/pages/Explore.tsx`
- [Expedition records](https://github.com/vasavi-suniganti/yuki/blob/main/client/src/pages/Expeditions.tsx): `client/src/pages/Expeditions.tsx`
- [Research library](https://github.com/vasavi-suniganti/yuki/blob/main/client/src/pages/Research.tsx): `client/src/pages/Research.tsx`

### Research Tools

- [Dataset explorer](https://github.com/vasavi-suniganti/yuki/blob/main/client/src/pages/Datasets.tsx): `client/src/pages/Datasets.tsx`
- [Maps and time](https://github.com/vasavi-suniganti/yuki/blob/main/client/src/pages/MapTimeGraph.tsx): `client/src/pages/MapTimeGraph.tsx`
- [AI research tools](https://github.com/vasavi-suniganti/yuki/blob/main/client/src/pages/AI.tsx): `client/src/pages/AI.tsx`
- [Grounded AI engine](https://github.com/vasavi-suniganti/yuki/blob/main/server/src/services/ai.ts): `server/src/services/ai.ts`
- [Evidence retrieval](https://github.com/vasavi-suniganti/yuki/blob/main/server/src/services/retrieval.ts): `server/src/services/retrieval.ts`
- [Dataset parser](https://github.com/vasavi-suniganti/yuki/blob/main/server/src/services/datasetParser.ts): `server/src/services/datasetParser.ts`

### Curation and Review

- [Researcher workspace](https://github.com/vasavi-suniganti/yuki/blob/main/client/src/pages/ResearcherDashboard.tsx): `client/src/pages/ResearcherDashboard.tsx`
- [Reviewer workspace](https://github.com/vasavi-suniganti/yuki/blob/main/client/src/pages/ReviewerDashboard.tsx): `client/src/pages/ReviewerDashboard.tsx`
- [Media studio](https://github.com/vasavi-suniganti/yuki/blob/main/client/src/pages/MediaManagerDashboard.tsx): `client/src/pages/MediaManagerDashboard.tsx`
- [Admin workspace](https://github.com/vasavi-suniganti/yuki/blob/main/client/src/pages/AdminDashboard.tsx): `client/src/pages/AdminDashboard.tsx`
- [Media features](https://github.com/vasavi-suniganti/yuki/blob/main/client/src/lib/signatureFeatures.ts): `client/src/lib/signatureFeatures.ts`
- [Metadata extraction](https://github.com/vasavi-suniganti/yuki/blob/main/server/src/services/metadataExtractor.ts): `server/src/services/metadataExtractor.ts`
- [Review state machine](https://github.com/vasavi-suniganti/yuki/blob/main/server/src/services/reviewWorkflow.ts): `server/src/services/reviewWorkflow.ts`

### Platform Services

- [Identity and roles](https://github.com/vasavi-suniganti/yuki/blob/main/client/src/lib/auth.tsx): `client/src/lib/auth.tsx`
- [Firebase client](https://github.com/vasavi-suniganti/yuki/blob/main/client/src/lib/firebase.ts): `client/src/lib/firebase.ts`
- [API client](https://github.com/vasavi-suniganti/yuki/blob/main/client/src/lib/api.ts): `client/src/lib/api.ts`
- [Typed data service](https://github.com/vasavi-suniganti/yuki/blob/main/client/src/services/dataService.ts): `client/src/services/dataService.ts`
- [Demo records](https://github.com/vasavi-suniganti/yuki/blob/main/client/src/data/demo.ts): `client/src/data/demo.ts`
- [API server](https://github.com/vasavi-suniganti/yuki/blob/main/server/src/index.ts): `server/src/index.ts`
- [Product API routes](https://github.com/vasavi-suniganti/yuki/blob/main/server/src/routes/api.ts): `server/src/routes/api.ts`
- [Open data API](https://github.com/vasavi-suniganti/yuki/blob/main/server/src/routes/openApi.ts): `server/src/routes/openApi.ts`
- [Request authorization](https://github.com/vasavi-suniganti/yuki/blob/main/server/src/middleware/auth.ts): `server/src/middleware/auth.ts`
- [Firebase Admin](https://github.com/vasavi-suniganti/yuki/blob/main/server/src/services/firebase.ts): `server/src/services/firebase.ts`
- **Firestore**
- **Firebase Authentication**

### Education

- [Learning hub](https://github.com/vasavi-suniganti/yuki/blob/main/client/src/pages/EducationVirtual.tsx): `client/src/pages/EducationVirtual.tsx`
- [Quiz engine](https://github.com/vasavi-suniganti/yuki/blob/main/client/src/components/AdvancedQuizEngine.tsx): `client/src/components/AdvancedQuizEngine.tsx`
- [Learning content](https://github.com/vasavi-suniganti/yuki/blob/main/client/src/data/learningContent.ts): `client/src/data/learningContent.ts`
- [Student progress](https://github.com/vasavi-suniganti/yuki/blob/main/client/src/lib/studentLearning.ts): `client/src/lib/studentLearning.ts`

### Other components

- **Portal visitor**

## Connections

- Portal visitor → Page router: opens portal (evidence: `client/src/App.tsx`)
- Page router → Science discovery: routes to (evidence: `client/src/App.tsx`)
- Page router → Expedition records: routes to (evidence: `client/src/App.tsx`)
- Page router → Dataset explorer: routes to (evidence: `client/src/App.tsx`)
- Page router → Maps and time: routes to (evidence: `client/src/App.tsx`)
- Page router → Research library: routes to (evidence: `client/src/App.tsx`)
- Page router → AI research tools: routes to (evidence: `client/src/App.tsx`)
- Page router → Researcher workspace: guards route (evidence: `client/src/App.tsx`)
- Page router → Reviewer workspace: guards route (evidence: `client/src/App.tsx`)
- Page router → Media studio: guards route (evidence: `client/src/App.tsx`)
- Page router → Admin workspace: guards route (evidence: `client/src/App.tsx`)
- Page router → Learning hub: routes to (evidence: `client/src/App.tsx`)
- Researcher workspace → Identity and roles: uses identity (evidence: `client/src/pages/ResearcherDashboard.tsx`)
- Reviewer workspace → Identity and roles: uses identity (evidence: `client/src/pages/ReviewerDashboard.tsx`)
- Media studio → Identity and roles: uses identity (evidence: `client/src/pages/MediaManagerDashboard.tsx`)
- Identity and roles → Firebase client: uses Firebase (evidence: `client/src/lib/auth.tsx`)
- Firebase client → Firebase Authentication: authenticates with
- Identity and roles → Firestore: reads user profiles
- Researcher workspace → API client: calls API (evidence: `client/src/pages/ResearcherDashboard.tsx`)
- Reviewer workspace → API client: calls API (evidence: `client/src/pages/ReviewerDashboard.tsx`)
- Typed data service → Firebase client: uses Firebase (evidence: `client/src/services/dataService.ts`)
- Typed data service → API client: uses API client (evidence: `client/src/services/dataService.ts`)
- Researcher workspace → Demo records: uses fallback data (evidence: `client/src/pages/ResearcherDashboard.tsx`)
- Media studio → Media features: saves story (evidence: `client/src/pages/MediaManagerDashboard.tsx`)
- Learning hub → Quiz engine: offers quizzes
- Quiz engine → Learning content: uses questions (evidence: `client/src/components/AdvancedQuizEngine.tsx`)
- Quiz engine → Student progress: records progress (evidence: `client/src/components/AdvancedQuizEngine.tsx`)
- API server → Product API routes: mounts routes (evidence: `server/src/index.ts`)
- API server → Open data API: mounts routes (evidence: `server/src/index.ts`)
- Product API routes → Request authorization: uses middleware (evidence: `server/src/routes/api.ts`)
- Request authorization → Firebase Admin: verifies identity (evidence: `server/src/middleware/auth.ts`)
- Product API routes → Grounded AI engine: dispatches AI (evidence: `server/src/routes/api.ts`)
- Grounded AI engine → Evidence retrieval: retrieves evidence (evidence: `server/src/services/ai.ts`)
- Product API routes → Dataset parser: parses datasets (evidence: `server/src/routes/api.ts`)
- Product API routes → Metadata extraction: extracts metadata (evidence: `server/src/routes/api.ts`)
- Product API routes → Review state machine: creates reviews (evidence: `server/src/routes/api.ts`)
- Review state machine → Firebase Admin: reads and writes (evidence: `server/src/services/reviewWorkflow.ts`)
- Request authorization → Firestore: loads user roles (evidence: `server/src/middleware/auth.ts`)
- Open data API → Firebase Admin: reads records (evidence: `server/src/routes/openApi.ts`)
- Firebase Admin → Firestore: accesses database
- API client → API server: sends requests
- AI research tools → Product API routes: requests AI features
- Dataset explorer → Product API routes: requests processing
