# nicolascrr/franol architecture

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

- Interactive diagram: https://gitdiagram.com/nicolascrr/franol
- Repository: https://github.com/nicolascrr/franol

## Overview

Frañol is a bilingual French–Spanish learning app. Learners choose a language, authenticate, manage vocabulary/expressions/conjugations, and practice through quizzes; quiz presets, discovery, AI-generated explanations and conjugations extend that workflow. The graph includes the documented shared-password session flow and Supabase-backed content/presets. Some page and route implementations were not sampled, so their UI-to-API relationships are shown only as unverified dashed links.

Main entry points: [`src/app/dashboard/page.tsx`](https://github.com/nicolascrr/franol/blob/develop/src/app/dashboard/page.tsx) (Dashboard), [`src/app/dashboard/content/page.tsx`](https://github.com/nicolascrr/franol/blob/develop/src/app/dashboard/content/page.tsx) (Content management), [`src/app/dashboard/practice/setup/page.tsx`](https://github.com/nicolascrr/franol/blob/develop/src/app/dashboard/practice/setup/page.tsx) (Practice setup), [`src/app/dashboard/practice/quiz/page.tsx`](https://github.com/nicolascrr/franol/blob/develop/src/app/dashboard/practice/quiz/page.tsx) (Quiz session)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Learner experience"]
  node_home["Language choice<br/>[page.tsx]"]
  node_dashboard["Dashboard<br/>[page.tsx]"]
  node_changelog["Release notes<br/>[Changelog.tsx]"]
end

subgraph group_learning["Content and practice"]
  node_content_ui["Content management<br/>[page.tsx]"]
  node_add_ui["Add learning items<br/>[page.tsx]"]
  node_practice_ui["Practice setup<br/>[page.tsx]"]
  node_quiz_ui["Quiz session<br/>[page.tsx]"]
  node_results_ui["Quiz results<br/>[page.tsx]"]
  node_discovery_ui["Content discovery<br/>[page.tsx]"]
  node_presets_ui["Quiz presets<br/>[page.tsx]"]
  node_quiz_engine["Quiz logic<br/>[quiz.ts]"]
  node_preset_api["Preset API<br/>[route.ts]"]
end

subgraph group_ai["AI learning services"]
  node_ai_api["AI endpoints<br/>[route.ts]"]
  node_ai_client["Gemini client<br/>[client.ts]"]
  node_prompts["Localized prompts<br/>[index.ts]"]
end

subgraph group_identity["Authentication"]
  node_login["Login page<br/>[page.tsx]"]
  node_middleware["Route protection<br/>[middleware.ts]"]
  node_auth_api["Auth endpoints<br/>[route.ts]"]
  node_sessions["Signed sessions<br/>[session.ts]"]
end

subgraph group_platform["Data and language layer"]
  node_content_store["Supabase data access<br/>[client.ts]"]
  node_locale["Locale context<br/>[LocaleContext.tsx]"]
  node_language_fields["Bilingual field access<br/>[lang.ts]"]
  node_validation["Input validation"]
  node_releases["Release data<br/>[releases.ts]"]
end

node_learner(("Learner"))
node_supabase[("Supabase")]
node_ai_service["Gemini API"]

node_learner -->|"chooses language"| node_home
node_learner -->|"signs in"| node_login
node_login -.->|"submits credentials"| node_auth_api
node_auth_api -->|"signs session"| node_sessions
node_middleware -->|"verifies session"| node_sessions
node_learner -.->|"uses app"| node_dashboard
node_dashboard -.->|"opens content"| node_content_ui
node_dashboard -.->|"adds items"| node_add_ui
node_dashboard -.->|"starts practice"| node_practice_ui
node_practice_ui -.->|"configures quiz"| node_quiz_ui
node_quiz_ui -->|"uses quiz logic"| node_quiz_engine
node_quiz_ui -.->|"shows results"| node_results_ui
node_practice_ui -.->|"offers discovery"| node_discovery_ui
node_practice_ui -.->|"offers presets"| node_presets_ui
node_content_ui -->|"reads and writes"| node_content_store
node_quiz_engine -->|"accesses data"| node_content_store
node_content_store -.->|"queries"| node_supabase
node_presets_ui -.->|"manages presets"| node_preset_api
node_preset_api -->|"reads and writes"| node_supabase
node_quiz_ui -.->|"requests generation"| node_ai_api
node_ai_api -->|"sanitizes prompt"| node_validation
node_ai_api -->|"builds quiz prompt"| node_prompts
node_ai_api -->|"requests completion"| node_ai_client
node_ai_client -.->|"calls Gemini"| node_ai_service
node_content_ui -->|"uses locale"| node_locale
node_content_ui -->|"reads language fields"| node_language_fields
node_quiz_engine -->|"uses language helpers"| node_language_fields
node_changelog -->|"renders release data"| node_releases

click node_home "https://github.com/nicolascrr/franol/blob/develop/src/app/page.tsx"
click node_login "https://github.com/nicolascrr/franol/blob/develop/src/app/login/page.tsx"
click node_middleware "https://github.com/nicolascrr/franol/blob/develop/src/middleware.ts"
click node_auth_api "https://github.com/nicolascrr/franol/blob/develop/src/app/api/auth/login/route.ts"
click node_sessions "https://github.com/nicolascrr/franol/blob/develop/src/lib/auth/session.ts"
click node_dashboard "https://github.com/nicolascrr/franol/blob/develop/src/app/dashboard/page.tsx"
click node_content_ui "https://github.com/nicolascrr/franol/blob/develop/src/app/dashboard/content/page.tsx"
click node_add_ui "https://github.com/nicolascrr/franol/blob/develop/src/app/dashboard/add/page.tsx"
click node_practice_ui "https://github.com/nicolascrr/franol/blob/develop/src/app/dashboard/practice/setup/page.tsx"
click node_quiz_ui "https://github.com/nicolascrr/franol/blob/develop/src/app/dashboard/practice/quiz/page.tsx"
click node_results_ui "https://github.com/nicolascrr/franol/blob/develop/src/app/dashboard/practice/results/page.tsx"
click node_discovery_ui "https://github.com/nicolascrr/franol/blob/develop/src/app/dashboard/practice/discovery/page.tsx"
click node_presets_ui "https://github.com/nicolascrr/franol/blob/develop/src/app/dashboard/practice/presets/page.tsx"
click node_quiz_engine "https://github.com/nicolascrr/franol/blob/develop/src/lib/quiz.ts"
click node_content_store "https://github.com/nicolascrr/franol/blob/develop/src/lib/supabase/client.ts"
click node_preset_api "https://github.com/nicolascrr/franol/blob/develop/src/app/api/quiz-presets/route.ts"
click node_ai_api "https://github.com/nicolascrr/franol/blob/develop/src/app/api/ai/generate-batch/route.ts"
click node_ai_client "https://github.com/nicolascrr/franol/blob/develop/src/lib/ai/client.ts"
click node_prompts "https://github.com/nicolascrr/franol/blob/develop/src/lib/prompts/index.ts"
click node_locale "https://github.com/nicolascrr/franol/blob/develop/src/contexts/LocaleContext.tsx"
click node_language_fields "https://github.com/nicolascrr/franol/blob/develop/src/lib/lang.ts"
click node_validation "https://github.com/nicolascrr/franol/blob/develop/src/lib/auth/input-validation.ts"
click node_changelog "https://github.com/nicolascrr/franol/blob/develop/src/components/dashboard/Changelog.tsx"
click node_releases "https://github.com/nicolascrr/franol/blob/develop/src/data/releases.ts"

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_home,node_dashboard,node_changelog toneBlue
class node_content_ui,node_add_ui,node_practice_ui,node_quiz_ui,node_results_ui,node_discovery_ui,node_presets_ui,node_quiz_engine,node_preset_api,node_supabase toneAmber
class node_ai_api,node_ai_client,node_prompts,node_ai_service toneMint
class node_login,node_middleware,node_auth_api,node_sessions toneRose
class node_content_store,node_locale,node_language_fields,node_validation,node_releases,node_learner toneIndigo
```

## Components

### Learner experience

- [Language choice](https://github.com/nicolascrr/franol/blob/develop/src/app/page.tsx): `src/app/page.tsx`
- [Dashboard](https://github.com/nicolascrr/franol/blob/develop/src/app/dashboard/page.tsx): `src/app/dashboard/page.tsx`
- [Release notes](https://github.com/nicolascrr/franol/blob/develop/src/components/dashboard/Changelog.tsx): `src/components/dashboard/Changelog.tsx`

### Content and practice

- [Content management](https://github.com/nicolascrr/franol/blob/develop/src/app/dashboard/content/page.tsx): `src/app/dashboard/content/page.tsx`
- [Add learning items](https://github.com/nicolascrr/franol/blob/develop/src/app/dashboard/add/page.tsx): `src/app/dashboard/add/page.tsx`
- [Practice setup](https://github.com/nicolascrr/franol/blob/develop/src/app/dashboard/practice/setup/page.tsx): `src/app/dashboard/practice/setup/page.tsx`
- [Quiz session](https://github.com/nicolascrr/franol/blob/develop/src/app/dashboard/practice/quiz/page.tsx): `src/app/dashboard/practice/quiz/page.tsx`
- [Quiz results](https://github.com/nicolascrr/franol/blob/develop/src/app/dashboard/practice/results/page.tsx): `src/app/dashboard/practice/results/page.tsx`
- [Content discovery](https://github.com/nicolascrr/franol/blob/develop/src/app/dashboard/practice/discovery/page.tsx): `src/app/dashboard/practice/discovery/page.tsx`
- [Quiz presets](https://github.com/nicolascrr/franol/blob/develop/src/app/dashboard/practice/presets/page.tsx): `src/app/dashboard/practice/presets/page.tsx`
- [Quiz logic](https://github.com/nicolascrr/franol/blob/develop/src/lib/quiz.ts): `src/lib/quiz.ts`
- [Preset API](https://github.com/nicolascrr/franol/blob/develop/src/app/api/quiz-presets/route.ts): `src/app/api/quiz-presets/route.ts`

### AI learning services

- [AI endpoints](https://github.com/nicolascrr/franol/blob/develop/src/app/api/ai/generate-batch/route.ts): `src/app/api/ai/generate-batch/route.ts`
- [Gemini client](https://github.com/nicolascrr/franol/blob/develop/src/lib/ai/client.ts): `src/lib/ai/client.ts`
- [Localized prompts](https://github.com/nicolascrr/franol/blob/develop/src/lib/prompts/index.ts): `src/lib/prompts/index.ts`

### Authentication

- [Login page](https://github.com/nicolascrr/franol/blob/develop/src/app/login/page.tsx): `src/app/login/page.tsx`
- [Route protection](https://github.com/nicolascrr/franol/blob/develop/src/middleware.ts): `src/middleware.ts`
- [Auth endpoints](https://github.com/nicolascrr/franol/blob/develop/src/app/api/auth/login/route.ts): `src/app/api/auth/login/route.ts`
- [Signed sessions](https://github.com/nicolascrr/franol/blob/develop/src/lib/auth/session.ts): `src/lib/auth/session.ts`

### Data and language layer

- [Supabase data access](https://github.com/nicolascrr/franol/blob/develop/src/lib/supabase/client.ts): `src/lib/supabase/client.ts`
- [Locale context](https://github.com/nicolascrr/franol/blob/develop/src/contexts/LocaleContext.tsx): `src/contexts/LocaleContext.tsx`
- [Bilingual field access](https://github.com/nicolascrr/franol/blob/develop/src/lib/lang.ts): `src/lib/lang.ts`
- [Input validation](https://github.com/nicolascrr/franol/blob/develop/src/lib/auth/input-validation.ts): `src/lib/auth/input-validation.ts`
- [Release data](https://github.com/nicolascrr/franol/blob/develop/src/data/releases.ts): `src/data/releases.ts`

### Other components

- **Learner**
- **Supabase**
- **Gemini API**

## Connections

- Learner → Language choice: chooses language
- Learner → Login page: signs in
- Login page → Auth endpoints: submits credentials
- Auth endpoints → Signed sessions: signs session (evidence: `src/app/api/auth/login/route.ts`)
- Route protection → Signed sessions: verifies session (evidence: `src/middleware.ts`)
- Learner → Dashboard: uses app
- Dashboard → Content management: opens content
- Dashboard → Add learning items: adds items
- Dashboard → Practice setup: starts practice
- Practice setup → Quiz session: configures quiz
- Quiz session → Quiz logic: uses quiz logic (evidence: `src/lib/quiz.ts`)
- Quiz session → Quiz results: shows results
- Practice setup → Content discovery: offers discovery
- Practice setup → Quiz presets: offers presets
- Content management → Supabase data access: reads and writes (evidence: `src/app/dashboard/content/page.tsx`)
- Quiz logic → Supabase data access: accesses data (evidence: `src/lib/quiz.ts`)
- Supabase data access → Supabase: queries
- Quiz presets → Preset API: manages presets
- Preset API → Supabase: reads and writes (evidence: `src/app/api/quiz-presets/route.ts`)
- Quiz session → AI endpoints: requests generation
- AI endpoints → Input validation: sanitizes prompt (evidence: `src/app/api/ai/generate-batch/route.ts`)
- AI endpoints → Localized prompts: builds quiz prompt (evidence: `src/app/api/ai/generate-batch/route.ts`)
- AI endpoints → Gemini client: requests completion (evidence: `src/app/api/ai/generate-batch/route.ts`)
- Gemini client → Gemini API: calls Gemini
- Content management → Locale context: uses locale (evidence: `src/app/dashboard/content/page.tsx`)
- Content management → Bilingual field access: reads language fields (evidence: `src/app/dashboard/content/page.tsx`)
- Quiz logic → Bilingual field access: uses language helpers (evidence: `src/lib/quiz.ts`)
- Release notes → Release data: renders release data (evidence: `src/components/dashboard/Changelog.tsx`)
