How sultvnnnn/mahreen-pathfinder works
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: api.ts API client · recommendation_service.py Recommendation service · quiz.py Quiz routes · app Web pages
Components 16
Web experience
- Web pages
frontend/src/app - Quiz form
frontend/src/components/QuizForm.tsx - Recommendation display
frontend/src/components/ResultCard.tsx - Login and registration
frontend/src/components/AuthCard.tsx - API client
frontend/src/lib/api.ts
API and domain
- FastAPI app
backend/app/main.py - Program routes
backend/app/api/programs.py - Quiz routes
backend/app/api/quiz.py - Recommendation service
backend/app/services/recommendation_service.py
Persistence
- Program repository
backend/app/repositories/program_repository.py - Submission repository
backend/app/repositories/submission_repository.py - Postgres
Identity
- Auth client
frontend/src/lib/supabase/client.ts - JWT verification
backend/app/core/auth.py - Supabase Auth
Other components
- Visitor
Connections 27
- 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