# flynne09/studexa architecture

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

- Interactive diagram: https://gitdiagram.com/flynne09/studexa
- Repository: https://github.com/flynne09/studexa

## Overview

Studexa is a Flutter classroom assessment and study-material platform. Teachers manage classes and learning materials, generate and edit grounded Actual and Practice quizzes, publish practice work, and monitor results; students join classes, read materials, take quizzes, and review scores. The README documents the client’s Supabase integrations and the Edge Function security boundary. Flutter sources and database migrations are absent from the supplied tree, so client capabilities and storage are represented from README evidence; function internals are shown only where paths are supported.

Main entry points: [`supabase/functions/_shared/quiz_edge.mjs`](https://github.com/flynne09/studexa/blob/main/supabase/functions/_shared/quiz_edge.mjs) (Quiz request handling), [`supabase/functions/_shared/submit_quiz_attempt_edge.mjs`](https://github.com/flynne09/studexa/blob/main/supabase/functions/_shared/submit_quiz_attempt_edge.mjs) (Attempt submission handling), [`supabase/functions/_shared/teacher_gemini_key_edge.mjs`](https://github.com/flynne09/studexa/blob/main/supabase/functions/_shared/teacher_gemini_key_edge.mjs) (Teacher key handling), [`supabase/functions/_shared/quiz_generator.mjs`](https://github.com/flynne09/studexa/blob/main/supabase/functions/_shared/quiz_generator.mjs) (Grounded generation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Flutter app"]
  node_app["Studexa app"]
end

subgraph group_learning["Learning workflow"]
  node_classes["Class management"]
  node_materials["Study materials"]
  node_extraction["On-device extraction"]
  node_quiz_authoring["Quiz authoring"]
  node_quiz_attempts["Quiz attempts"]
  node_results["Results review"]
end

subgraph group_backend["Supabase backend"]
  node_auth["Supabase Auth"]
  node_postgres[("Supabase Postgres")]
  node_storage[("Private file storage")]
  node_generate_endpoint["Generate quiz endpoint<br/>[index.ts]"]
  node_submit_endpoint["Submit attempt endpoint<br/>[index.ts]"]
  node_key_endpoint["Teacher key endpoint<br/>[index.ts]"]
  node_postgres_rest["Postgres REST access<br/>[postgres_rest.mjs]"]
  node_attempt_edge["Attempt submission handling"]
  node_identity["Identity checks"]
  node_teacher_key_edge["Teacher key handling"]
  node_vault[("Supabase Vault")]
end

subgraph group_ai["Quiz generation"]
  node_quiz_edge["Quiz request handling<br/>[quiz_edge.mjs]"]
  node_quiz_generator["Grounded generation<br/>[quiz_generator.mjs]"]
  node_question_filters["Question filtering"]
end

node_teacher(("Teacher"))
node_student(("Student"))
node_gemini["Google Gemini"]

node_teacher -->|"uses"| node_app
node_student -->|"uses"| node_app
node_app -->|"authenticates with"| node_auth
node_app -->|"reads and writes"| node_postgres
node_app -->|"uploads and reads"| node_storage
node_app -->|"manages"| node_classes
node_app -->|"manages"| node_materials
node_materials -->|"extracts text on device"| node_extraction
node_app -->|"creates and edits"| node_quiz_authoring
node_app -->|"takes quizzes"| node_quiz_attempts
node_app -->|"reviews"| node_results
node_app -->|"requests generation"| node_generate_endpoint
node_app -->|"submits attempt"| node_submit_endpoint
node_app -->|"manages teacher key"| node_key_endpoint
node_generate_endpoint -->|"dispatches"| node_quiz_edge
node_quiz_edge -->|"checks identity"| node_identity
node_quiz_edge -->|"loads quiz context"| node_postgres_rest
node_quiz_edge -->|"generates questions"| node_quiz_generator
node_quiz_generator -->|"requests completions"| node_gemini
node_quiz_edge -->|"filters questions"| node_question_filters
node_quiz_edge -->|"saves quiz"| node_postgres_rest
node_submit_endpoint -->|"dispatches"| node_attempt_edge
node_attempt_edge -->|"checks identity"| node_identity
node_attempt_edge -->|"records attempt"| node_postgres_rest
node_key_endpoint -->|"dispatches"| node_teacher_key_edge
node_teacher_key_edge -->|"checks identity"| node_identity
node_teacher_key_edge -->|"stores teacher key"| node_vault
node_quiz_generator -.->|"uses key backup"| node_vault

click node_generate_endpoint "https://github.com/flynne09/studexa/blob/main/supabase/functions/generate-quiz/index.ts"
click node_submit_endpoint "https://github.com/flynne09/studexa/blob/main/supabase/functions/submit-quiz-attempt/index.ts"
click node_key_endpoint "https://github.com/flynne09/studexa/blob/main/supabase/functions/teacher-gemini-key/index.ts"
click node_quiz_edge "https://github.com/flynne09/studexa/blob/main/supabase/functions/_shared/quiz_edge.mjs"
click node_quiz_generator "https://github.com/flynne09/studexa/blob/main/supabase/functions/_shared/quiz_generator.mjs"
click node_question_filters "https://github.com/flynne09/studexa/blob/main/supabase/functions/_shared/question_filters.mjs"
click node_postgres_rest "https://github.com/flynne09/studexa/blob/main/supabase/functions/_shared/postgres_rest.mjs"
click node_attempt_edge "https://github.com/flynne09/studexa/blob/main/supabase/functions/_shared/submit_quiz_attempt_edge.mjs"
click node_identity "https://github.com/flynne09/studexa/blob/main/supabase/functions/_shared/supabase_identity.mjs"
click node_teacher_key_edge "https://github.com/flynne09/studexa/blob/main/supabase/functions/_shared/teacher_gemini_key_edge.mjs"

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_app toneBlue
class node_classes,node_materials,node_extraction,node_quiz_authoring,node_quiz_attempts,node_results toneAmber
class node_auth,node_postgres,node_storage,node_generate_endpoint,node_submit_endpoint,node_key_endpoint,node_postgres_rest,node_attempt_edge,node_identity,node_teacher_key_edge,node_vault toneMint
class node_quiz_edge,node_quiz_generator,node_question_filters toneRose
class node_teacher,node_student,node_gemini toneIndigo
```

## Components

### Flutter app

- **Studexa app**

### Learning workflow

- **Class management**
- **Study materials**
- **On-device extraction**
- **Quiz authoring**
- **Quiz attempts**
- **Results review**

### Supabase backend

- **Supabase Auth**
- **Supabase Postgres**
- **Private file storage**
- [Generate quiz endpoint](https://github.com/flynne09/studexa/blob/main/supabase/functions/generate-quiz/index.ts): `supabase/functions/generate-quiz/index.ts`
- [Submit attempt endpoint](https://github.com/flynne09/studexa/blob/main/supabase/functions/submit-quiz-attempt/index.ts): `supabase/functions/submit-quiz-attempt/index.ts`
- [Teacher key endpoint](https://github.com/flynne09/studexa/blob/main/supabase/functions/teacher-gemini-key/index.ts): `supabase/functions/teacher-gemini-key/index.ts`
- [Postgres REST access](https://github.com/flynne09/studexa/blob/main/supabase/functions/_shared/postgres_rest.mjs): `supabase/functions/_shared/postgres_rest.mjs`
- [Attempt submission handling](https://github.com/flynne09/studexa/blob/main/supabase/functions/_shared/submit_quiz_attempt_edge.mjs): `supabase/functions/_shared/submit_quiz_attempt_edge.mjs`
- [Identity checks](https://github.com/flynne09/studexa/blob/main/supabase/functions/_shared/supabase_identity.mjs): `supabase/functions/_shared/supabase_identity.mjs`
- [Teacher key handling](https://github.com/flynne09/studexa/blob/main/supabase/functions/_shared/teacher_gemini_key_edge.mjs): `supabase/functions/_shared/teacher_gemini_key_edge.mjs`
- **Supabase Vault**

### Quiz generation

- [Quiz request handling](https://github.com/flynne09/studexa/blob/main/supabase/functions/_shared/quiz_edge.mjs): `supabase/functions/_shared/quiz_edge.mjs`
- [Grounded generation](https://github.com/flynne09/studexa/blob/main/supabase/functions/_shared/quiz_generator.mjs): `supabase/functions/_shared/quiz_generator.mjs`
- [Question filtering](https://github.com/flynne09/studexa/blob/main/supabase/functions/_shared/question_filters.mjs): `supabase/functions/_shared/question_filters.mjs`

### Other components

- **Teacher**
- **Student**
- **Google Gemini**

## Connections

- Teacher → Studexa app: uses
- Student → Studexa app: uses
- Studexa app → Supabase Auth: authenticates with
- Studexa app → Supabase Postgres: reads and writes
- Studexa app → Private file storage: uploads and reads
- Studexa app → Class management: manages
- Studexa app → Study materials: manages
- Study materials → On-device extraction: extracts text on device
- Studexa app → Quiz authoring: creates and edits
- Studexa app → Quiz attempts: takes quizzes
- Studexa app → Results review: reviews
- Studexa app → Generate quiz endpoint: requests generation
- Studexa app → Submit attempt endpoint: submits attempt
- Studexa app → Teacher key endpoint: manages teacher key
- Generate quiz endpoint → Quiz request handling: dispatches
- Quiz request handling → Identity checks: checks identity
- Quiz request handling → Postgres REST access: loads quiz context
- Quiz request handling → Grounded generation: generates questions
- Grounded generation → Google Gemini: requests completions
- Quiz request handling → Question filtering: filters questions
- Quiz request handling → Postgres REST access: saves quiz
- Submit attempt endpoint → Attempt submission handling: dispatches
- Attempt submission handling → Identity checks: checks identity
- Attempt submission handling → Postgres REST access: records attempt
- Teacher key endpoint → Teacher key handling: dispatches
- Teacher key handling → Identity checks: checks identity
- Teacher key handling → Supabase Vault: stores teacher key
- Grounded generation → Supabase Vault: uses key backup