# sultvnnnn/mahreen-pathfinder architecture

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

- Interactive diagram: https://gitdiagram.com/sultvnnnn/mahreen-pathfinder
- Repository: https://github.com/sultvnnnn/mahreen-pathfinder

## Overview

Mahreen PathFinder helps Indonesian youth explore Mahreen programs and receive transparent, personalized recommendations through a three-step interest quiz. The main journey runs from browser authentication and quiz submission through API validation, deterministic tag scoring, persistence, and displayed recommendations. Separate branches provide the program catalog and public aggregate statistics. The graph combines sampled source with README-documented capabilities; unsampled route wiring is shown only where the README supports it.

Main entry points: [`frontend/src/lib/api.ts`](https://github.com/sultvnnnn/mahreen-pathfinder/blob/main/frontend/src/lib/api.ts) (API client), [`backend/app/services/recommendation_service.py`](https://github.com/sultvnnnn/mahreen-pathfinder/blob/main/backend/app/services/recommendation_service.py) (Recommendation service), [`backend/app/api/quiz.py`](https://github.com/sultvnnnn/mahreen-pathfinder/blob/main/backend/app/api/quiz.py) (Quiz routes), [`frontend/src/app`](https://github.com/sultvnnnn/mahreen-pathfinder/tree/main/frontend/src/app) (Web pages)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web experience"]
  node_webapp["Web pages"]
  node_quizform["Quiz form<br/>[QuizForm.tsx]"]
  node_result["Recommendation display<br/>[ResultCard.tsx]"]
  node_authcard["Login and registration<br/>[AuthCard.tsx]"]
  node_apiclient["API client<br/>[api.ts]"]
end

subgraph group_backend["API and domain"]
  node_fastapi["FastAPI app<br/>[main.py]"]
  node_programapi["Program routes<br/>[programs.py]"]
  node_quizapi["Quiz routes<br/>[quiz.py]"]
  node_recommendation["Recommendation service"]
end

subgraph group_data["Persistence"]
  node_programrepo["Program repository"]
  node_submissionrepo["Submission repository"]
  node_database[("Postgres")]
end

subgraph group_identity["Identity"]
  node_supabaseclient["Auth client<br/>[client.ts]"]
  node_authverify["JWT verification<br/>[auth.py]"]
  node_supabaseauth{{"Supabase Auth"}}
end

node_visitor(("Visitor"))

node_visitor -->|"browses pages"| node_webapp
node_webapp -->|"opens quiz"| node_quizform
node_webapp -->|"opens login"| node_authcard
node_authcard -->|"requests session"| node_supabaseclient
node_supabaseclient -->|"authenticates"| node_supabaseauth
node_quizform -->|"submits answers"| node_apiclient
node_apiclient -->|"POST quiz"| node_quizapi
node_quizapi -->|"validates bearer"| node_authverify
node_authverify -.->|"gets JWKS"| node_supabaseauth
node_quizapi -->|"processes submission"| node_recommendation
node_recommendation -->|"loads programs"| node_programrepo
node_recommendation -->|"saves submission"| node_submissionrepo
node_recommendation -->|"records activity"| node_submissionrepo
node_recommendation -->|"returns results"| node_quizapi
node_quizapi -->|"returns recommendations"| node_apiclient
node_apiclient -->|"provides results"| node_result
node_webapp -->|"requests catalog"| node_apiclient
node_apiclient -->|"GET programs"| node_programapi
node_programapi -->|"loads catalog"| node_programrepo
node_webapp -->|"requests stats"| node_apiclient
node_apiclient -->|"GET stats"| node_fastapi
node_fastapi -->|"dispatches stats"| node_recommendation
node_recommendation -->|"reads aggregates"| node_submissionrepo
node_programrepo -->|"queries programs"| node_database
node_submissionrepo -->|"reads and writes"| node_database
node_fastapi -->|"mounts routes"| node_programapi
node_fastapi -->|"mounts routes"| node_quizapi

click node_webapp "https://github.com/sultvnnnn/mahreen-pathfinder/tree/main/frontend/src/app"
click node_quizform "https://github.com/sultvnnnn/mahreen-pathfinder/blob/main/frontend/src/components/QuizForm.tsx"
click node_result "https://github.com/sultvnnnn/mahreen-pathfinder/blob/main/frontend/src/components/ResultCard.tsx"
click node_authcard "https://github.com/sultvnnnn/mahreen-pathfinder/blob/main/frontend/src/components/AuthCard.tsx"
click node_apiclient "https://github.com/sultvnnnn/mahreen-pathfinder/blob/main/frontend/src/lib/api.ts"
click node_supabaseclient "https://github.com/sultvnnnn/mahreen-pathfinder/blob/main/frontend/src/lib/supabase/client.ts"
click node_fastapi "https://github.com/sultvnnnn/mahreen-pathfinder/blob/main/backend/app/main.py"
click node_programapi "https://github.com/sultvnnnn/mahreen-pathfinder/blob/main/backend/app/api/programs.py"
click node_quizapi "https://github.com/sultvnnnn/mahreen-pathfinder/blob/main/backend/app/api/quiz.py"
click node_authverify "https://github.com/sultvnnnn/mahreen-pathfinder/blob/main/backend/app/core/auth.py"
click node_recommendation "https://github.com/sultvnnnn/mahreen-pathfinder/blob/main/backend/app/services/recommendation_service.py"
click node_programrepo "https://github.com/sultvnnnn/mahreen-pathfinder/blob/main/backend/app/repositories/program_repository.py"
click node_submissionrepo "https://github.com/sultvnnnn/mahreen-pathfinder/blob/main/backend/app/repositories/submission_repository.py"

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_webapp,node_quizform,node_result,node_authcard,node_apiclient toneBlue
class node_fastapi,node_programapi,node_quizapi,node_recommendation toneAmber
class node_programrepo,node_submissionrepo,node_database toneMint
class node_supabaseclient,node_authverify,node_supabaseauth toneRose
class node_visitor toneIndigo
```

## Components

### Web experience

- [Web pages](https://github.com/sultvnnnn/mahreen-pathfinder/tree/main/frontend/src/app): `frontend/src/app`
- [Quiz form](https://github.com/sultvnnnn/mahreen-pathfinder/blob/main/frontend/src/components/QuizForm.tsx): `frontend/src/components/QuizForm.tsx`
- [Recommendation display](https://github.com/sultvnnnn/mahreen-pathfinder/blob/main/frontend/src/components/ResultCard.tsx): `frontend/src/components/ResultCard.tsx`
- [Login and registration](https://github.com/sultvnnnn/mahreen-pathfinder/blob/main/frontend/src/components/AuthCard.tsx): `frontend/src/components/AuthCard.tsx`
- [API client](https://github.com/sultvnnnn/mahreen-pathfinder/blob/main/frontend/src/lib/api.ts): `frontend/src/lib/api.ts`

### API and domain

- [FastAPI app](https://github.com/sultvnnnn/mahreen-pathfinder/blob/main/backend/app/main.py): `backend/app/main.py`
- [Program routes](https://github.com/sultvnnnn/mahreen-pathfinder/blob/main/backend/app/api/programs.py): `backend/app/api/programs.py`
- [Quiz routes](https://github.com/sultvnnnn/mahreen-pathfinder/blob/main/backend/app/api/quiz.py): `backend/app/api/quiz.py`
- [Recommendation service](https://github.com/sultvnnnn/mahreen-pathfinder/blob/main/backend/app/services/recommendation_service.py): `backend/app/services/recommendation_service.py`

### Persistence

- [Program repository](https://github.com/sultvnnnn/mahreen-pathfinder/blob/main/backend/app/repositories/program_repository.py): `backend/app/repositories/program_repository.py`
- [Submission repository](https://github.com/sultvnnnn/mahreen-pathfinder/blob/main/backend/app/repositories/submission_repository.py): `backend/app/repositories/submission_repository.py`
- **Postgres**

### Identity

- [Auth client](https://github.com/sultvnnnn/mahreen-pathfinder/blob/main/frontend/src/lib/supabase/client.ts): `frontend/src/lib/supabase/client.ts`
- [JWT verification](https://github.com/sultvnnnn/mahreen-pathfinder/blob/main/backend/app/core/auth.py): `backend/app/core/auth.py`
- **Supabase Auth**

### Other components

- **Visitor**

## Connections

- Visitor → Web pages: browses pages
- Web pages → Quiz form: opens quiz
- Web pages → Login and registration: opens login
- Login and registration → Auth client: requests session
- Auth client → Supabase Auth: authenticates
- Quiz form → API client: submits answers
- API client → Quiz routes: POST quiz
- Quiz routes → JWT verification: validates bearer
- JWT verification → Supabase Auth: gets JWKS
- Quiz routes → Recommendation service: processes submission
- Recommendation service → Program repository: loads programs
- Recommendation service → Submission repository: saves submission
- Recommendation service → Submission repository: records activity
- Recommendation service → Quiz routes: returns results
- Quiz routes → API client: returns recommendations
- API client → Recommendation display: provides results
- Web pages → API client: requests catalog
- API client → Program routes: GET programs
- Program routes → Program repository: loads catalog
- Web pages → API client: requests stats
- API client → FastAPI app: GET stats
- FastAPI app → Recommendation service: dispatches stats
- Recommendation service → Submission repository: reads aggregates
- Program repository → Postgres: queries programs
- Submission repository → Postgres: reads and writes
- FastAPI app → Program routes: mounts routes
- FastAPI app → Quiz routes: mounts routes