# hanzo-hatake/project-recommender architecture

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

- Interactive diagram: https://gitdiagram.com/hanzo-hatake/project-recommender
- Repository: https://github.com/hanzo-hatake/project-recommender

## Overview

This is a student project-topic recommender with student and administrator views. Students enter interests and constraints, request ranked topic matches, then inspect, bookmark, dismiss, or accept a topic; analytics and administration provide separate supporting workflows. The backend recommendation handler delegates matching to a service that uses embeddings and topic data. The frontend API client and several backend modules are present in the tree but were not sampled, so uncertain request wiring and internal behavior are not asserted.

Main entry points: [`frontend/src/App.tsx`](https://github.com/hanzo-hatake/project-recommender/blob/main/frontend/src/App.tsx) (Route and access control), [`backend/src/services/recommender.rs`](https://github.com/hanzo-hatake/project-recommender/blob/main/backend/src/services/recommender.rs) (Recommendation service), [`frontend/src/services/api.ts`](https://github.com/hanzo-hatake/project-recommender/blob/main/frontend/src/services/api.ts) (API client), [`backend/src/main.rs`](https://github.com/hanzo-hatake/project-recommender/blob/main/backend/src/main.rs) (HTTP server)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web interface"]
  node_app["Route and access control<br/>[App.tsx]"]
  node_recommendations_page["Topic matching UI"]
  node_dashboard_page["Student dashboard<br/>[DashboardPage.tsx]"]
  node_analytics_page["Analytics view<br/>[AnalyticsPage.tsx]"]
  node_admin_page["Admin console<br/>[AdminPage.tsx]"]
  node_api_client["API client<br/>[api.ts]"]
  node_role_hook["Role lookup<br/>[useRole.ts]"]
end

subgraph group_api["API workflows"]
  node_server["HTTP server<br/>[main.rs]"]
  node_recommendation_handler["Recommendation endpoint<br/>[recommendations.rs]"]
  node_topics_handler["Topic endpoints<br/>[topics.rs]"]
  node_admin_handler["Admin endpoints<br/>[admin.rs]"]
end

subgraph group_matching["Recommendation engine"]
  node_recommender["Recommendation service<br/>[recommender.rs]"]
  node_embeddings["Text embeddings<br/>[embeddings.rs]"]
  node_nlp["Text processing<br/>[nlp.rs]"]
end

subgraph group_state["Persistent data"]
  node_postgres[("PostgreSQL<br/>[connection.rs]")]
end

node_student(("Student"))
node_administrator(("Administrator"))
node_clerk(("Clerk identity"))

node_student -->|"uses"| node_app
node_administrator -->|"uses"| node_app
node_app -->|"routes"| node_recommendations_page
node_app -->|"routes"| node_dashboard_page
node_app -->|"routes"| node_analytics_page
node_app -->|"routes"| node_admin_page
node_app -->|"checks role"| node_role_hook
node_role_hook -->|"requests role"| node_api_client
node_role_hook -->|"reads identity"| node_clerk
node_server -->|"registers"| node_recommendation_handler
node_server -->|"registers"| node_topics_handler
node_server -->|"registers"| node_admin_handler
node_recommendation_handler -->|"requests matches"| node_recommender
node_recommender -->|"encodes text"| node_embeddings
node_recommender -->|"processes text"| node_nlp
node_recommender -->|"reads topics"| node_postgres
node_recommendation_handler -->|"returns matches"| node_student
node_admin_handler -->|"reads and updates"| node_postgres
node_topics_handler -->|"accesses topics"| node_postgres
node_recommendations_page -->|"requests recommendations"| node_api_client
node_analytics_page -->|"requests analytics"| node_api_client
node_admin_page -->|"requests admin data"| node_api_client

click node_app "https://github.com/hanzo-hatake/project-recommender/blob/main/frontend/src/App.tsx"
click node_recommendations_page "https://github.com/hanzo-hatake/project-recommender/blob/main/frontend/src/pages/RecommendationsPage.tsx"
click node_dashboard_page "https://github.com/hanzo-hatake/project-recommender/blob/main/frontend/src/pages/DashboardPage.tsx"
click node_analytics_page "https://github.com/hanzo-hatake/project-recommender/blob/main/frontend/src/pages/AnalyticsPage.tsx"
click node_admin_page "https://github.com/hanzo-hatake/project-recommender/blob/main/frontend/src/pages/AdminPage.tsx"
click node_api_client "https://github.com/hanzo-hatake/project-recommender/blob/main/frontend/src/services/api.ts"
click node_role_hook "https://github.com/hanzo-hatake/project-recommender/blob/main/frontend/src/store/useRole.ts"
click node_server "https://github.com/hanzo-hatake/project-recommender/blob/main/backend/src/main.rs"
click node_recommendation_handler "https://github.com/hanzo-hatake/project-recommender/blob/main/backend/src/handlers/recommendations.rs"
click node_topics_handler "https://github.com/hanzo-hatake/project-recommender/blob/main/backend/src/handlers/topics.rs"
click node_admin_handler "https://github.com/hanzo-hatake/project-recommender/blob/main/backend/src/handlers/admin.rs"
click node_recommender "https://github.com/hanzo-hatake/project-recommender/blob/main/backend/src/services/recommender.rs"
click node_embeddings "https://github.com/hanzo-hatake/project-recommender/blob/main/backend/src/services/embeddings.rs"
click node_nlp "https://github.com/hanzo-hatake/project-recommender/blob/main/backend/src/services/nlp.rs"
click node_postgres "https://github.com/hanzo-hatake/project-recommender/blob/main/backend/src/db/connection.rs"

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_recommendations_page,node_dashboard_page,node_analytics_page,node_admin_page,node_api_client,node_role_hook toneBlue
class node_server,node_recommendation_handler,node_topics_handler,node_admin_handler toneAmber
class node_recommender,node_embeddings,node_nlp toneMint
class node_postgres toneRose
class node_student,node_administrator,node_clerk toneIndigo
```

## Components

### Web interface

- [Route and access control](https://github.com/hanzo-hatake/project-recommender/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Topic matching UI](https://github.com/hanzo-hatake/project-recommender/blob/main/frontend/src/pages/RecommendationsPage.tsx): `frontend/src/pages/RecommendationsPage.tsx`
- [Student dashboard](https://github.com/hanzo-hatake/project-recommender/blob/main/frontend/src/pages/DashboardPage.tsx): `frontend/src/pages/DashboardPage.tsx`
- [Analytics view](https://github.com/hanzo-hatake/project-recommender/blob/main/frontend/src/pages/AnalyticsPage.tsx): `frontend/src/pages/AnalyticsPage.tsx`
- [Admin console](https://github.com/hanzo-hatake/project-recommender/blob/main/frontend/src/pages/AdminPage.tsx): `frontend/src/pages/AdminPage.tsx`
- [API client](https://github.com/hanzo-hatake/project-recommender/blob/main/frontend/src/services/api.ts): `frontend/src/services/api.ts`
- [Role lookup](https://github.com/hanzo-hatake/project-recommender/blob/main/frontend/src/store/useRole.ts): `frontend/src/store/useRole.ts`

### API workflows

- [HTTP server](https://github.com/hanzo-hatake/project-recommender/blob/main/backend/src/main.rs): `backend/src/main.rs`
- [Recommendation endpoint](https://github.com/hanzo-hatake/project-recommender/blob/main/backend/src/handlers/recommendations.rs): `backend/src/handlers/recommendations.rs`
- [Topic endpoints](https://github.com/hanzo-hatake/project-recommender/blob/main/backend/src/handlers/topics.rs): `backend/src/handlers/topics.rs`
- [Admin endpoints](https://github.com/hanzo-hatake/project-recommender/blob/main/backend/src/handlers/admin.rs): `backend/src/handlers/admin.rs`

### Recommendation engine

- [Recommendation service](https://github.com/hanzo-hatake/project-recommender/blob/main/backend/src/services/recommender.rs): `backend/src/services/recommender.rs`
- [Text embeddings](https://github.com/hanzo-hatake/project-recommender/blob/main/backend/src/services/embeddings.rs): `backend/src/services/embeddings.rs`
- [Text processing](https://github.com/hanzo-hatake/project-recommender/blob/main/backend/src/services/nlp.rs): `backend/src/services/nlp.rs`

### Persistent data

- [PostgreSQL](https://github.com/hanzo-hatake/project-recommender/blob/main/backend/src/db/connection.rs): `backend/src/db/connection.rs`

### Other components

- **Student**
- **Administrator**
- **Clerk identity**

## Connections

- Student → Route and access control: uses
- Administrator → Route and access control: uses
- Route and access control → Topic matching UI: routes
- Route and access control → Student dashboard: routes
- Route and access control → Analytics view: routes
- Route and access control → Admin console: routes
- Route and access control → Role lookup: checks role
- Role lookup → API client: requests role
- Role lookup → Clerk identity: reads identity
- HTTP server → Recommendation endpoint: registers
- HTTP server → Topic endpoints: registers
- HTTP server → Admin endpoints: registers
- Recommendation endpoint → Recommendation service: requests matches
- Recommendation service → Text embeddings: encodes text
- Recommendation service → Text processing: processes text
- Recommendation service → PostgreSQL: reads topics
- Recommendation endpoint → Student: returns matches
- Admin endpoints → PostgreSQL: reads and updates
- Topic endpoints → PostgreSQL: accesses topics
- Topic matching UI → API client: requests recommendations
- Analytics view → API client: requests analytics
- Admin console → API client: requests admin data