# dalph955-png/sahel-orientation architecture

> Architecture diagram of the GitHub repository dalph955-png/sahel-orientation, 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/dalph955-png/sahel-orientation
- Repository: https://github.com/dalph955-png/sahel-orientation

## Overview

Sahel Orientation guides Senegalese Bac students from a bilingual profile through deterministic formation matching, balanced recommendations, comparison, and checking official sources. The browser keeps profile and preference data locally; optional AI reads free text or narrates existing engine results, with deterministic fallbacks. The graph preserves the README’s additional weight settings, bilingual data, and formation-detail capabilities. Some page and API wiring is documented rather than visible in the sampled excerpts, so those connections are limited to explicitly described behavior.

Main entry points: [`src/app/api/chat/route.ts`](https://github.com/dalph955-png/sahel-orientation/blob/main/src/app/api/chat/route.ts) (Chat API), [`src/lib/store.tsx`](https://github.com/dalph955-png/sahel-orientation/blob/main/src/lib/store.tsx) (Profile state), [`src/app/profil/page.tsx`](https://github.com/dalph955-png/sahel-orientation/blob/main/src/app/profil/page.tsx) (Build profile), [`src/lib/matching.ts`](https://github.com/dalph955-png/sahel-orientation/blob/main/src/lib/matching.ts) (Match and rank)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_journey["Student journey"]
  node_landing["Start<br/>[page.tsx]"]
  node_profile["Build profile<br/>[page.tsx]"]
  node_results["Profile results<br/>[page.tsx]"]
  node_shortlist["Recommendations<br/>[page.tsx]"]
  node_compare["Compare paths<br/>[page.tsx]"]
  node_verify["Verify details<br/>[page.tsx]"]
  node_verifyindex["Verification guide<br/>[page.tsx]"]
  node_settings["Weights and language<br/>[page.tsx]"]
  node_formationdetail["Formation detail"]
end

subgraph group_domain["Orientation engine"]
  node_matching["Match and rank<br/>[matching.ts]"]
  node_formations["Formation dataset<br/>[formations.ts]"]
  node_explain["Profile explanations<br/>[explain.ts]"]
  node_freetext["Lexical reading<br/>[freeText.ts]"]
end

subgraph group_ai["Optional AI"]
  node_chat["Chat API<br/>[route.ts]"]
  node_ai["AI providers<br/>[ai.ts]"]
end

subgraph group_state["Local state"]
  node_store["Profile state<br/>[store.tsx]"]
  node_browserstore[("Browser storage")]
end

node_student(("Student"))
node_providers{{"Configured model services"}}
node_official{{"Official sources"}}

node_student -->|"opens app"| node_landing
node_landing -->|"starts profile"| node_profile
node_profile -->|"updates profile"| node_store
node_store -->|"persists locally"| node_browserstore
node_browserstore -->|"restores state"| node_store
node_profile -->|"reads locally"| node_freetext
node_profile -.->|"requests inference"| node_chat
node_profile -->|"continues"| node_results
node_results -->|"reads profile"| node_store
node_results -->|"builds narrative"| node_explain
node_results -.->|"requests narration"| node_chat
node_shortlist -->|"reads profile"| node_store
node_shortlist -->|"gets recommendations"| node_matching
node_matching -->|"scores records"| node_formations
node_compare -->|"reads profile"| node_store
node_compare -->|"scores paths"| node_matching
node_compare -.->|"requests comparison"| node_chat
node_settings -->|"updates preferences"| node_store
node_settings -->|"previews bands"| node_matching
node_verify -->|"reads formation"| node_formations
node_verify -->|"links for verification"| node_official
node_verifyindex -->|"directs student"| node_official
node_shortlist -->|"opens details"| node_formationdetail
node_chat -.->|"interprets text"| node_freetext
node_chat -->|"builds fallback"| node_explain
node_chat -->|"scores comparison"| node_matching
node_chat -.->|"requests narration"| node_ai
node_ai -.->|"calls provider"| node_providers

click node_landing "https://github.com/dalph955-png/sahel-orientation/blob/main/src/app/page.tsx"
click node_profile "https://github.com/dalph955-png/sahel-orientation/blob/main/src/app/profil/page.tsx"
click node_results "https://github.com/dalph955-png/sahel-orientation/blob/main/src/app/resultats/page.tsx"
click node_shortlist "https://github.com/dalph955-png/sahel-orientation/blob/main/src/app/parcours/page.tsx"
click node_compare "https://github.com/dalph955-png/sahel-orientation/blob/main/src/app/comparer/page.tsx"
click node_verify "https://github.com/dalph955-png/sahel-orientation/blob/main/src/app/verifier/%5Bid%5D/page.tsx"
click node_verifyindex "https://github.com/dalph955-png/sahel-orientation/blob/main/src/app/verifier/page.tsx"
click node_settings "https://github.com/dalph955-png/sahel-orientation/blob/main/src/app/reglages/page.tsx"
click node_store "https://github.com/dalph955-png/sahel-orientation/blob/main/src/lib/store.tsx"
click node_matching "https://github.com/dalph955-png/sahel-orientation/blob/main/src/lib/matching.ts"
click node_formations "https://github.com/dalph955-png/sahel-orientation/blob/main/src/lib/formations.ts"
click node_explain "https://github.com/dalph955-png/sahel-orientation/blob/main/src/lib/explain.ts"
click node_freetext "https://github.com/dalph955-png/sahel-orientation/blob/main/src/lib/freeText.ts"
click node_chat "https://github.com/dalph955-png/sahel-orientation/blob/main/src/app/api/chat/route.ts"
click node_ai "https://github.com/dalph955-png/sahel-orientation/blob/main/src/lib/ai.ts"
click node_formationdetail "https://github.com/dalph955-png/sahel-orientation/blob/main/src/components/formation-detail.tsx"

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_landing,node_profile,node_results,node_shortlist,node_compare,node_verify,node_verifyindex,node_settings,node_formationdetail toneBlue
class node_matching,node_formations,node_explain,node_freetext toneAmber
class node_chat,node_ai toneMint
class node_store,node_browserstore toneRose
class node_student,node_providers,node_official toneIndigo
```

## Components

### Student journey

- [Start](https://github.com/dalph955-png/sahel-orientation/blob/main/src/app/page.tsx): `src/app/page.tsx`
- [Build profile](https://github.com/dalph955-png/sahel-orientation/blob/main/src/app/profil/page.tsx): `src/app/profil/page.tsx`
- [Profile results](https://github.com/dalph955-png/sahel-orientation/blob/main/src/app/resultats/page.tsx): `src/app/resultats/page.tsx`
- [Recommendations](https://github.com/dalph955-png/sahel-orientation/blob/main/src/app/parcours/page.tsx): `src/app/parcours/page.tsx`
- [Compare paths](https://github.com/dalph955-png/sahel-orientation/blob/main/src/app/comparer/page.tsx): `src/app/comparer/page.tsx`
- [Verify details](https://github.com/dalph955-png/sahel-orientation/blob/main/src/app/verifier/%5Bid%5D/page.tsx): `src/app/verifier/[id]/page.tsx`
- [Verification guide](https://github.com/dalph955-png/sahel-orientation/blob/main/src/app/verifier/page.tsx): `src/app/verifier/page.tsx`
- [Weights and language](https://github.com/dalph955-png/sahel-orientation/blob/main/src/app/reglages/page.tsx): `src/app/reglages/page.tsx`
- [Formation detail](https://github.com/dalph955-png/sahel-orientation/blob/main/src/components/formation-detail.tsx): `src/components/formation-detail.tsx`

### Orientation engine

- [Match and rank](https://github.com/dalph955-png/sahel-orientation/blob/main/src/lib/matching.ts): `src/lib/matching.ts`
- [Formation dataset](https://github.com/dalph955-png/sahel-orientation/blob/main/src/lib/formations.ts): `src/lib/formations.ts`
- [Profile explanations](https://github.com/dalph955-png/sahel-orientation/blob/main/src/lib/explain.ts): `src/lib/explain.ts`
- [Lexical reading](https://github.com/dalph955-png/sahel-orientation/blob/main/src/lib/freeText.ts): `src/lib/freeText.ts`

### Optional AI

- [Chat API](https://github.com/dalph955-png/sahel-orientation/blob/main/src/app/api/chat/route.ts): `src/app/api/chat/route.ts`
- [AI providers](https://github.com/dalph955-png/sahel-orientation/blob/main/src/lib/ai.ts): `src/lib/ai.ts`

### Local state

- [Profile state](https://github.com/dalph955-png/sahel-orientation/blob/main/src/lib/store.tsx): `src/lib/store.tsx`
- **Browser storage**

### Other components

- **Student**
- **Configured model services**
- **Official sources**

## Connections

- Student → Start: opens app
- Start → Build profile: starts profile
- Build profile → Profile state: updates profile
- Profile state → Browser storage: persists locally
- Browser storage → Profile state: restores state
- Build profile → Lexical reading: reads locally
- Build profile → Chat API: requests inference
- Build profile → Profile results: continues
- Profile results → Profile state: reads profile
- Profile results → Profile explanations: builds narrative
- Profile results → Chat API: requests narration
- Recommendations → Profile state: reads profile
- Recommendations → Match and rank: gets recommendations
- Match and rank → Formation dataset: scores records
- Compare paths → Profile state: reads profile
- Compare paths → Match and rank: scores paths
- Compare paths → Chat API: requests comparison
- Weights and language → Profile state: updates preferences
- Weights and language → Match and rank: previews bands
- Verify details → Formation dataset: reads formation
- Verify details → Official sources: links for verification
- Verification guide → Official sources: directs student
- Recommendations → Formation detail: opens details
- Chat API → Lexical reading: interprets text
- Chat API → Profile explanations: builds fallback
- Chat API → Match and rank: scores comparison
- Chat API → AI providers: requests narration
- AI providers → Configured model services: calls provider