# yggzee/psu-research-publication architecture

> Architecture diagram of the GitHub repository yggzee/psu-research-publication, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/yggzee/psu-research-publication
- Repository: https://github.com/yggzee/psu-research-publication

## Overview

This is a campus research repository and analytics portal: public visitors and institutional users discover researchers and publications, while instructors and administrators manage records; dashboards, impact views, reports, and AI assistance provide analysis. The frontend is routed through role-aware pages and uses an API client plus browser storage. The server API handler coordinates authentication, research data, scraping, AI, email, and safeguards. README content is absent, so capability coverage follows the supplied source index; unsampled implementation details and frontend-to-server URL wiring are not asserted.

Main entry points: [`src/app/routes.tsx`](https://github.com/yggzee/psu-research-publication/blob/main/src/app/routes.tsx) (Role-aware routes), [`src/app/services/api.service.ts`](https://github.com/yggzee/psu-research-publication/blob/main/src/app/services/api.service.ts) (API client), [`src/server/apiHandler.mjs`](https://github.com/yggzee/psu-research-publication/blob/main/src/server/apiHandler.mjs) (API handler), [`src/app/components/AdminPage.tsx`](https://github.com/yggzee/psu-research-publication/blob/main/src/app/components/AdminPage.tsx) (Administration)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Access and navigation"]
  node_app["Application shell<br/>[App.tsx]"]
  node_routes["Role-aware routes<br/>[routes.tsx]"]
end

subgraph group_discovery["Research discovery"]
  node_portal["Public repository"]
  node_search["Publication search<br/>[SearchEngine.tsx]"]
  node_researchers["Researcher directory"]
  node_profile["Researcher profile"]
  node_publication["Publication detail"]
  node_scraper["Scholar scraper<br/>[scholarScraper.mjs]"]
end

subgraph group_management["Research management"]
  node_admin["Administration<br/>[AdminPage.tsx]"]
  node_instructor_publications["Instructor publications"]
end

subgraph group_services["Server and data services"]
  node_api_client["API client<br/>[api.service.ts]"]
  node_research_store["Research state<br/>[researchStore.ts]"]
  node_api["API handler<br/>[apiHandler.mjs]"]
  node_auth["Authentication<br/>[authHelper.mjs]"]
  node_database[("Research database<br/>[db.mjs]")]
  node_turso[("Turso replication<br/>[turso.mjs]")]
  node_email["Email service<br/>[emailService.mjs]"]
  node_rate_limit["Rate limiting<br/>[rateLimiter.mjs]"]
end

subgraph group_analysis["Analysis and assistance"]
  node_dashboard["Research dashboard<br/>[Dashboard.tsx]"]
  node_impact["Impact analysis"]
  node_sdg["SDG impact matrix"]
  node_reports["Research reports<br/>[ReportsPage.tsx]"]
  node_ai_chat["Campus AI chat<br/>[AskCampusAI.tsx]"]
  node_ai_service["AI services<br/>[aiService.mjs]"]
end

node_visitor(("Visitor"))
node_campus_user(("Campus user"))

node_visitor -->|"browses"| node_portal
node_campus_user -.->|"opens pages"| node_routes
node_app -->|"mounts routes"| node_routes
node_routes -->|"routes to"| node_portal
node_routes -->|"routes to"| node_dashboard
node_routes -->|"routes to"| node_search
node_routes -->|"routes to"| node_researchers
node_routes -->|"routes to"| node_profile
node_routes -->|"routes to"| node_publication
node_routes -->|"routes to"| node_impact
node_routes -->|"routes to"| node_sdg
node_routes -->|"routes to"| node_reports
node_routes -->|"guards route"| node_admin
node_routes -.->|"routes to"| node_instructor_publications
node_search -->|"requests search"| node_api_client
node_portal -->|"requests repository data"| node_api_client
node_dashboard -->|"requests metrics"| node_api_client
node_researchers -->|"requests researchers"| node_api_client
node_profile -->|"requests profile data"| node_api_client
node_admin -->|"manages records"| node_api_client
node_admin -->|"reads and updates"| node_research_store
node_api_client -.->|"sends HTTP requests"| node_api
node_research_store -->|"syncs records"| node_api_client
node_api -->|"uses data access"| node_database
node_api -->|"uses authentication"| node_auth
node_api -->|"dispatches scraping"| node_scraper
node_api -->|"dispatches AI tasks"| node_ai_service
node_api -->|"sends email"| node_email
node_api -->|"applies limits"| node_rate_limit
node_database -->|"replicates and rehydrates"| node_turso
node_ai_service -->|"fetches research metadata"| node_scraper
node_impact -.->|"requests analysis data"| node_api_client
node_sdg -.->|"requests SDG data"| node_api_client
node_reports -.->|"requests report data"| node_api_client
node_ai_chat -.->|"requests AI assistance"| node_api_client

click node_app "https://github.com/yggzee/psu-research-publication/blob/main/src/app/App.tsx"
click node_routes "https://github.com/yggzee/psu-research-publication/blob/main/src/app/routes.tsx"
click node_portal "https://github.com/yggzee/psu-research-publication/blob/main/src/app/components/PublicRepositoryPortal.tsx"
click node_search "https://github.com/yggzee/psu-research-publication/blob/main/src/app/components/SearchEngine.tsx"
click node_researchers "https://github.com/yggzee/psu-research-publication/blob/main/src/app/components/ResearchersPage.tsx"
click node_profile "https://github.com/yggzee/psu-research-publication/blob/main/src/app/components/ResearcherProfile.tsx"
click node_publication "https://github.com/yggzee/psu-research-publication/blob/main/src/app/components/PublicationDetail.tsx"
click node_dashboard "https://github.com/yggzee/psu-research-publication/blob/main/src/app/components/Dashboard.tsx"
click node_impact "https://github.com/yggzee/psu-research-publication/blob/main/src/app/components/ImpactAnalysisPage.tsx"
click node_sdg "https://github.com/yggzee/psu-research-publication/blob/main/src/app/components/SDGImpactMatrix.tsx"
click node_reports "https://github.com/yggzee/psu-research-publication/blob/main/src/app/components/ReportsPage.tsx"
click node_ai_chat "https://github.com/yggzee/psu-research-publication/blob/main/src/app/components/AskCampusAI.tsx"
click node_admin "https://github.com/yggzee/psu-research-publication/blob/main/src/app/components/AdminPage.tsx"
click node_instructor_publications "https://github.com/yggzee/psu-research-publication/blob/main/src/app/components/InstructorPublicationsPage.tsx"
click node_api_client "https://github.com/yggzee/psu-research-publication/blob/main/src/app/services/api.service.ts"
click node_research_store "https://github.com/yggzee/psu-research-publication/blob/main/src/app/utils/researchStore.ts"
click node_api "https://github.com/yggzee/psu-research-publication/blob/main/src/server/apiHandler.mjs"
click node_auth "https://github.com/yggzee/psu-research-publication/blob/main/src/server/authHelper.mjs"
click node_database "https://github.com/yggzee/psu-research-publication/blob/main/src/server/db.mjs"
click node_turso "https://github.com/yggzee/psu-research-publication/blob/main/src/server/turso.mjs"
click node_scraper "https://github.com/yggzee/psu-research-publication/blob/main/src/server/scholarScraper.mjs"
click node_ai_service "https://github.com/yggzee/psu-research-publication/blob/main/src/server/aiService.mjs"
click node_email "https://github.com/yggzee/psu-research-publication/blob/main/src/server/emailService.mjs"
click node_rate_limit "https://github.com/yggzee/psu-research-publication/blob/main/src/server/rateLimiter.mjs"

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_routes,node_campus_user toneBlue
class node_portal,node_search,node_researchers,node_profile,node_publication,node_scraper toneAmber
class node_admin,node_instructor_publications toneMint
class node_api_client,node_research_store,node_api,node_auth,node_database,node_turso,node_email,node_rate_limit toneRose
class node_dashboard,node_impact,node_sdg,node_reports,node_ai_chat,node_ai_service,node_visitor toneIndigo
```

## Components

### Access and navigation

- [Application shell](https://github.com/yggzee/psu-research-publication/blob/main/src/app/App.tsx): `src/app/App.tsx`
- [Role-aware routes](https://github.com/yggzee/psu-research-publication/blob/main/src/app/routes.tsx): `src/app/routes.tsx`

### Research discovery

- [Public repository](https://github.com/yggzee/psu-research-publication/blob/main/src/app/components/PublicRepositoryPortal.tsx): `src/app/components/PublicRepositoryPortal.tsx`
- [Publication search](https://github.com/yggzee/psu-research-publication/blob/main/src/app/components/SearchEngine.tsx): `src/app/components/SearchEngine.tsx`
- [Researcher directory](https://github.com/yggzee/psu-research-publication/blob/main/src/app/components/ResearchersPage.tsx): `src/app/components/ResearchersPage.tsx`
- [Researcher profile](https://github.com/yggzee/psu-research-publication/blob/main/src/app/components/ResearcherProfile.tsx): `src/app/components/ResearcherProfile.tsx`
- [Publication detail](https://github.com/yggzee/psu-research-publication/blob/main/src/app/components/PublicationDetail.tsx): `src/app/components/PublicationDetail.tsx`
- [Scholar scraper](https://github.com/yggzee/psu-research-publication/blob/main/src/server/scholarScraper.mjs): `src/server/scholarScraper.mjs`

### Research management

- [Administration](https://github.com/yggzee/psu-research-publication/blob/main/src/app/components/AdminPage.tsx): `src/app/components/AdminPage.tsx`
- [Instructor publications](https://github.com/yggzee/psu-research-publication/blob/main/src/app/components/InstructorPublicationsPage.tsx): `src/app/components/InstructorPublicationsPage.tsx`

### Server and data services

- [API client](https://github.com/yggzee/psu-research-publication/blob/main/src/app/services/api.service.ts): `src/app/services/api.service.ts`
- [Research state](https://github.com/yggzee/psu-research-publication/blob/main/src/app/utils/researchStore.ts): `src/app/utils/researchStore.ts`
- [API handler](https://github.com/yggzee/psu-research-publication/blob/main/src/server/apiHandler.mjs): `src/server/apiHandler.mjs`
- [Authentication](https://github.com/yggzee/psu-research-publication/blob/main/src/server/authHelper.mjs): `src/server/authHelper.mjs`
- [Research database](https://github.com/yggzee/psu-research-publication/blob/main/src/server/db.mjs): `src/server/db.mjs`
- [Turso replication](https://github.com/yggzee/psu-research-publication/blob/main/src/server/turso.mjs): `src/server/turso.mjs`
- [Email service](https://github.com/yggzee/psu-research-publication/blob/main/src/server/emailService.mjs): `src/server/emailService.mjs`
- [Rate limiting](https://github.com/yggzee/psu-research-publication/blob/main/src/server/rateLimiter.mjs): `src/server/rateLimiter.mjs`

### Analysis and assistance

- [Research dashboard](https://github.com/yggzee/psu-research-publication/blob/main/src/app/components/Dashboard.tsx): `src/app/components/Dashboard.tsx`
- [Impact analysis](https://github.com/yggzee/psu-research-publication/blob/main/src/app/components/ImpactAnalysisPage.tsx): `src/app/components/ImpactAnalysisPage.tsx`
- [SDG impact matrix](https://github.com/yggzee/psu-research-publication/blob/main/src/app/components/SDGImpactMatrix.tsx): `src/app/components/SDGImpactMatrix.tsx`
- [Research reports](https://github.com/yggzee/psu-research-publication/blob/main/src/app/components/ReportsPage.tsx): `src/app/components/ReportsPage.tsx`
- [Campus AI chat](https://github.com/yggzee/psu-research-publication/blob/main/src/app/components/AskCampusAI.tsx): `src/app/components/AskCampusAI.tsx`
- [AI services](https://github.com/yggzee/psu-research-publication/blob/main/src/server/aiService.mjs): `src/server/aiService.mjs`

### Other components

- **Visitor**
- **Campus user**

## Connections

- Visitor → Public repository: browses
- Campus user → Role-aware routes: opens pages
- Application shell → Role-aware routes: mounts routes (evidence: `src/app/App.tsx`)
- Role-aware routes → Public repository: routes to (evidence: `src/app/routes.tsx`)
- Role-aware routes → Research dashboard: routes to (evidence: `src/app/routes.tsx`)
- Role-aware routes → Publication search: routes to (evidence: `src/app/routes.tsx`)
- Role-aware routes → Researcher directory: routes to (evidence: `src/app/routes.tsx`)
- Role-aware routes → Researcher profile: routes to (evidence: `src/app/routes.tsx`)
- Role-aware routes → Publication detail: routes to (evidence: `src/app/routes.tsx`)
- Role-aware routes → Impact analysis: routes to (evidence: `src/app/routes.tsx`)
- Role-aware routes → SDG impact matrix: routes to (evidence: `src/app/routes.tsx`)
- Role-aware routes → Research reports: routes to (evidence: `src/app/routes.tsx`)
- Role-aware routes → Administration: guards route (evidence: `src/app/routes.tsx`)
- Role-aware routes → Instructor publications: routes to (evidence: `src/app/routes.tsx`)
- Publication search → API client: requests search (evidence: `src/app/components/SearchEngine.tsx`)
- Public repository → API client: requests repository data (evidence: `src/app/components/PublicRepositoryPortal.tsx`)
- Research dashboard → API client: requests metrics (evidence: `src/app/components/Dashboard.tsx`)
- Researcher directory → API client: requests researchers (evidence: `src/app/components/ResearchersPage.tsx`)
- Researcher profile → API client: requests profile data (evidence: `src/app/components/ResearcherProfile.tsx`)
- Administration → API client: manages records (evidence: `src/app/components/AdminPage.tsx`)
- Administration → Research state: reads and updates (evidence: `src/app/components/AdminPage.tsx`)
- API client → API handler: sends HTTP requests
- Research state → API client: syncs records (evidence: `src/app/utils/researchStore.ts`)
- API handler → Research database: uses data access (evidence: `src/server/apiHandler.mjs`)
- API handler → Authentication: uses authentication (evidence: `src/server/apiHandler.mjs`)
- API handler → Scholar scraper: dispatches scraping (evidence: `src/server/apiHandler.mjs`)
- API handler → AI services: dispatches AI tasks (evidence: `src/server/apiHandler.mjs`)
- API handler → Email service: sends email (evidence: `src/server/apiHandler.mjs`)
- API handler → Rate limiting: applies limits (evidence: `src/server/apiHandler.mjs`)
- Research database → Turso replication: replicates and rehydrates (evidence: `src/server/db.mjs`)
- AI services → Scholar scraper: fetches research metadata (evidence: `src/server/aiService.mjs`)
- Impact analysis → API client: requests analysis data
- SDG impact matrix → API client: requests SDG data
- Research reports → API client: requests report data
- Campus AI chat → API client: requests AI assistance
