# allylearning/frontier-economics-ai-quiz architecture

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

- Interactive diagram: https://gitdiagram.com/allylearning/frontier-economics-ai-quiz
- Repository: https://github.com/allylearning/frontier-economics-ai-quiz

## Overview

Frontier Economics Quiz is an embedded AI-policy training quiz. A player starts a quiz, answers policy questions, can request a hint, and receives scoring, feedback, and a generated performance summary; scores are also saved for leaderboard display. The graph follows the sampled client and server-action calls. The README documents only the product purpose, so unsampled page composition and detailed flow wiring are not expanded beyond supported paths.

Main entry points: [`src/components/quiz/QuizClient.tsx`](https://github.com/allylearning/frontier-economics-ai-quiz/blob/main/src/components/quiz/QuizClient.tsx) (Quiz controller), [`src/ai/genkit.ts`](https://github.com/allylearning/frontier-economics-ai-quiz/blob/main/src/ai/genkit.ts) (Genkit runtime), [`src/app/page.tsx`](https://github.com/allylearning/frontier-economics-ai-quiz/blob/main/src/app/page.tsx) (Quiz page), [`src/ai/flows/generate-hint.ts`](https://github.com/allylearning/frontier-economics-ai-quiz/blob/main/src/ai/flows/generate-hint.ts) (Hint generation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Quiz experience"]
  node_page["Quiz page<br/>[page.tsx]"]
  node_client["Quiz controller<br/>[QuizClient.tsx]"]
  node_start["Quiz setup<br/>[StartScreen.tsx]"]
  node_question["Question interface<br/>[QuestionCard.tsx]"]
  node_progress["Quiz progress<br/>[QuizProgress.tsx]"]
  node_summary["Results summary<br/>[QuizSummary.tsx]"]
end

subgraph group_content["Quiz content"]
  node_questions["Question pool<br/>[questions.ts]"]
  node_types["Quiz data types<br/>[index.ts]"]
end

subgraph group_ai["AI assistance"]
  node_hint["Hint generation<br/>[generate-hint.ts]"]
  node_evaluation["Answer evaluation"]
  node_summarizer["Summary generation"]
  node_genkit["Genkit runtime<br/>[genkit.ts]"]
end

subgraph group_scores["Scoring and leaderboard"]
  node_leaderboard["Leaderboard actions"]
  node_database[("Leaderboard database<br/>[prisma.ts]")]
end

node_player(("Player"))
node_model{{"Google AI model"}}

node_player -->|"opens quiz"| node_page
node_page -->|"renders"| node_client
node_client -->|"presents setup"| node_start
node_client -->|"loads questions"| node_questions
node_client -->|"presents question"| node_question
node_client -->|"updates progress"| node_progress
node_client -->|"requests hint"| node_hint
node_client -->|"requests evaluation"| node_evaluation
node_client -->|"saves and fetches scores"| node_leaderboard
node_client -->|"requests summary"| node_summarizer
node_client -->|"displays results"| node_summary
node_leaderboard -->|"reads and writes"| node_database
node_summarizer -->|"runs flow"| node_genkit
node_hint -->|"runs flow"| node_genkit
node_evaluation -->|"runs flow"| node_genkit
node_genkit -.->|"calls model"| node_model

click node_page "https://github.com/allylearning/frontier-economics-ai-quiz/blob/main/src/app/page.tsx"
click node_client "https://github.com/allylearning/frontier-economics-ai-quiz/blob/main/src/components/quiz/QuizClient.tsx"
click node_start "https://github.com/allylearning/frontier-economics-ai-quiz/blob/main/src/components/quiz/StartScreen.tsx"
click node_question "https://github.com/allylearning/frontier-economics-ai-quiz/blob/main/src/components/quiz/QuestionCard.tsx"
click node_progress "https://github.com/allylearning/frontier-economics-ai-quiz/blob/main/src/components/quiz/QuizProgress.tsx"
click node_summary "https://github.com/allylearning/frontier-economics-ai-quiz/blob/main/src/components/quiz/QuizSummary.tsx"
click node_questions "https://github.com/allylearning/frontier-economics-ai-quiz/blob/main/src/lib/questions.ts"
click node_types "https://github.com/allylearning/frontier-economics-ai-quiz/blob/main/src/types/index.ts"
click node_hint "https://github.com/allylearning/frontier-economics-ai-quiz/blob/main/src/ai/flows/generate-hint.ts"
click node_evaluation "https://github.com/allylearning/frontier-economics-ai-quiz/blob/main/src/ai/flows/evaluate-open-text-answer.ts"
click node_summarizer "https://github.com/allylearning/frontier-economics-ai-quiz/blob/main/src/ai/flows/generate-quiz-summary.ts"
click node_genkit "https://github.com/allylearning/frontier-economics-ai-quiz/blob/main/src/ai/genkit.ts"
click node_leaderboard "https://github.com/allylearning/frontier-economics-ai-quiz/blob/main/src/actions/leaderboardActions.ts"
click node_database "https://github.com/allylearning/frontier-economics-ai-quiz/blob/main/src/lib/prisma.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_page,node_client,node_start,node_question,node_progress,node_summary toneBlue
class node_questions,node_types toneAmber
class node_hint,node_evaluation,node_summarizer,node_genkit toneMint
class node_leaderboard,node_database toneRose
class node_player,node_model toneIndigo
```

## Components

### Quiz experience

- [Quiz page](https://github.com/allylearning/frontier-economics-ai-quiz/blob/main/src/app/page.tsx): `src/app/page.tsx`
- [Quiz controller](https://github.com/allylearning/frontier-economics-ai-quiz/blob/main/src/components/quiz/QuizClient.tsx): `src/components/quiz/QuizClient.tsx`
- [Quiz setup](https://github.com/allylearning/frontier-economics-ai-quiz/blob/main/src/components/quiz/StartScreen.tsx): `src/components/quiz/StartScreen.tsx`
- [Question interface](https://github.com/allylearning/frontier-economics-ai-quiz/blob/main/src/components/quiz/QuestionCard.tsx): `src/components/quiz/QuestionCard.tsx`
- [Quiz progress](https://github.com/allylearning/frontier-economics-ai-quiz/blob/main/src/components/quiz/QuizProgress.tsx): `src/components/quiz/QuizProgress.tsx`
- [Results summary](https://github.com/allylearning/frontier-economics-ai-quiz/blob/main/src/components/quiz/QuizSummary.tsx): `src/components/quiz/QuizSummary.tsx`

### Quiz content

- [Question pool](https://github.com/allylearning/frontier-economics-ai-quiz/blob/main/src/lib/questions.ts): `src/lib/questions.ts`
- [Quiz data types](https://github.com/allylearning/frontier-economics-ai-quiz/blob/main/src/types/index.ts): `src/types/index.ts`

### AI assistance

- [Hint generation](https://github.com/allylearning/frontier-economics-ai-quiz/blob/main/src/ai/flows/generate-hint.ts): `src/ai/flows/generate-hint.ts`
- [Answer evaluation](https://github.com/allylearning/frontier-economics-ai-quiz/blob/main/src/ai/flows/evaluate-open-text-answer.ts): `src/ai/flows/evaluate-open-text-answer.ts`
- [Summary generation](https://github.com/allylearning/frontier-economics-ai-quiz/blob/main/src/ai/flows/generate-quiz-summary.ts): `src/ai/flows/generate-quiz-summary.ts`
- [Genkit runtime](https://github.com/allylearning/frontier-economics-ai-quiz/blob/main/src/ai/genkit.ts): `src/ai/genkit.ts`

### Scoring and leaderboard

- [Leaderboard actions](https://github.com/allylearning/frontier-economics-ai-quiz/blob/main/src/actions/leaderboardActions.ts): `src/actions/leaderboardActions.ts`
- [Leaderboard database](https://github.com/allylearning/frontier-economics-ai-quiz/blob/main/src/lib/prisma.ts): `src/lib/prisma.ts`

### Other components

- **Player**
- **Google AI model**

## Connections

- Player → Quiz page: opens quiz
- Quiz page → Quiz controller: renders
- Quiz controller → Quiz setup: presents setup
- Quiz controller → Question pool: loads questions
- Quiz controller → Question interface: presents question
- Quiz controller → Quiz progress: updates progress
- Quiz controller → Hint generation: requests hint
- Quiz controller → Answer evaluation: requests evaluation
- Quiz controller → Leaderboard actions: saves and fetches scores
- Quiz controller → Summary generation: requests summary
- Quiz controller → Results summary: displays results
- Leaderboard actions → Leaderboard database: reads and writes
- Summary generation → Genkit runtime: runs flow
- Hint generation → Genkit runtime: runs flow
- Answer evaluation → Genkit runtime: runs flow
- Genkit runtime → Google AI model: calls model