# aguerta/tops_academy architecture

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

- Interactive diagram: https://gitdiagram.com/aguerta/tops_academy
- Repository: https://github.com/aguerta/tops_academy

## Overview

Top’s Academy combines a course-bank validator with a browser-based mastery practice platform. Students discover a course, review its competencies, practice and receive feedback, then see progress reflected in mastery tracking; the backend discovers and serves course banks. The README also documents a larger AI content-to-course pipeline, but its implementation is not present in the supplied tree, so it is not mapped here. Edges reflect excerpts, the source index, or README statements; unsampled frontend connections are omitted.

Main entry points: [`src/validator/core.py`](https://github.com/aguerta/tops_academy/blob/main/src/validator/core.py) (Validation Core), [`platform/src/App.tsx`](https://github.com/aguerta/tops_academy/blob/main/platform/src/App.tsx) (Application Flow), [`platform/src/components/PracticeSession.tsx`](https://github.com/aguerta/tops_academy/blob/main/platform/src/components/PracticeSession.tsx) (Practice Session), [`platform/src/utils/masteryStorage.ts`](https://github.com/aguerta/tops_academy/blob/main/platform/src/utils/masteryStorage.ts) (Mastery Tracking)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_platform["Practice Platform"]
  node_entry["Web App Entry<br/>[main.tsx]"]
  node_app["Application Flow<br/>[App.tsx]"]
  node_library["Course Library<br/>[CourseLibrary.tsx]"]
  node_overview["Course Overview<br/>[CourseOverview.tsx]"]
  node_practice["Practice Session"]
  node_question["Question Card<br/>[QuestionCard.tsx]"]
  node_feedback["Feedback<br/>[FeedbackToast.tsx]"]
  node_completion["Completion Screen"]
  node_challenge["Course Challenge"]
  node_mastery["Mastery Tracking<br/>[masteryStorage.ts]"]
  node_session_store[("Session Recovery<br/>[sessionStore.ts]")]
  node_math["Math Equivalence<br/>[mathEquivalence.ts]"]
  node_question_utils["Question Utilities<br/>[questionUtils.ts]"]
  node_render_math["Math Rendering<br/>[MathText.tsx]"]
end

subgraph group_course_data["Course Discovery"]
  node_course_server["Course API Server<br/>[courseServer.cjs]"]
  node_course_index[("Course Index<br/>[courseIndex.cjs]")]
  node_course_loader["Course Loader<br/>[courseLoader.ts]"]
  node_course_bank["Course JSON Banks"]
end

subgraph group_validation["Course Validation"]
  node_validator_cli["Validator CLI<br/>[cli.py]"]
  node_validator_core["Validation Core<br/>[core.py]"]
  node_lexical["Lexical Scanner<br/>[lexical_scanner.py]"]
  node_schema["Schema Validator"]
  node_rules["Structural Rules<br/>[rules.py]"]
  node_psychometric["Psychometric Checks"]
  node_validation_models["Validation Results<br/>[models.py]"]
end

node_student(("Student"))

node_student -->|"opens"| node_entry
node_entry -->|"renders"| node_app
node_app -->|"loads courses"| node_course_loader
node_app -->|"shows"| node_library
node_library -->|"selects course"| node_app
node_app -->|"loads progress"| node_mastery
node_app -->|"restores session"| node_session_store
node_overview -->|"reads progress"| node_mastery
node_practice -->|"renders"| node_question
node_practice -->|"shows feedback"| node_feedback
node_practice -->|"checks answers"| node_math
node_practice -->|"grades choices"| node_question_utils
node_practice -->|"saves session"| node_session_store
node_question -->|"normalizes questions"| node_question_utils
node_question -->|"renders math"| node_render_math
node_overview -->|"renders content"| node_render_math
node_feedback -->|"renders content"| node_render_math
node_completion -->|"renders content"| node_render_math
node_completion -->|"reads progress"| node_mastery
node_challenge -.->|"records mastery"| node_mastery
node_course_server -->|"uses index"| node_course_index
node_course_index -->|"scans banks"| node_course_bank
node_course_loader -.->|"fetches course data"| node_course_server
node_validator_cli -->|"runs validation"| node_validator_core
node_validator_core -->|"checks syntax"| node_lexical
node_validator_core -->|"checks schema"| node_schema
node_validator_core -->|"checks rules"| node_rules
node_validator_core -->|"checks quality"| node_psychometric
node_validator_core -->|"builds results"| node_validation_models
node_rules -->|"creates errors"| node_validation_models
node_lexical -->|"creates errors"| node_validation_models

click node_entry "https://github.com/aguerta/tops_academy/blob/main/platform/src/main.tsx"
click node_app "https://github.com/aguerta/tops_academy/blob/main/platform/src/App.tsx"
click node_library "https://github.com/aguerta/tops_academy/blob/main/platform/src/components/CourseLibrary.tsx"
click node_overview "https://github.com/aguerta/tops_academy/blob/main/platform/src/components/CourseOverview.tsx"
click node_practice "https://github.com/aguerta/tops_academy/blob/main/platform/src/components/PracticeSession.tsx"
click node_question "https://github.com/aguerta/tops_academy/blob/main/platform/src/components/QuestionCard.tsx"
click node_feedback "https://github.com/aguerta/tops_academy/blob/main/platform/src/components/FeedbackToast.tsx"
click node_completion "https://github.com/aguerta/tops_academy/blob/main/platform/src/components/CompletionScreen.tsx"
click node_challenge "https://github.com/aguerta/tops_academy/blob/main/platform/src/components/CourseChallenge.tsx"
click node_mastery "https://github.com/aguerta/tops_academy/blob/main/platform/src/utils/masteryStorage.ts"
click node_session_store "https://github.com/aguerta/tops_academy/blob/main/platform/src/utils/sessionStore.ts"
click node_math "https://github.com/aguerta/tops_academy/blob/main/platform/src/utils/mathEquivalence.ts"
click node_question_utils "https://github.com/aguerta/tops_academy/blob/main/platform/src/utils/questionUtils.ts"
click node_render_math "https://github.com/aguerta/tops_academy/blob/main/platform/src/components/MathText.tsx"
click node_course_server "https://github.com/aguerta/tops_academy/blob/main/platform/server/courseServer.cjs"
click node_course_index "https://github.com/aguerta/tops_academy/blob/main/platform/server/courseIndex.cjs"
click node_course_loader "https://github.com/aguerta/tops_academy/blob/main/platform/src/utils/courseLoader.ts"
click node_validator_cli "https://github.com/aguerta/tops_academy/blob/main/src/validator/cli.py"
click node_validator_core "https://github.com/aguerta/tops_academy/blob/main/src/validator/core.py"
click node_lexical "https://github.com/aguerta/tops_academy/blob/main/src/validator/lexical_scanner.py"
click node_schema "https://github.com/aguerta/tops_academy/blob/main/src/validator/schema_validator.py"
click node_rules "https://github.com/aguerta/tops_academy/blob/main/src/validator/rules.py"
click node_psychometric "https://github.com/aguerta/tops_academy/blob/main/src/validator/psychometric_checker.py"
click node_validation_models "https://github.com/aguerta/tops_academy/blob/main/src/validator/models.py"

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_entry,node_app,node_library,node_overview,node_practice,node_question,node_feedback,node_completion,node_challenge,node_mastery,node_session_store,node_math,node_question_utils,node_render_math toneBlue
class node_course_server,node_course_index,node_course_loader,node_course_bank toneAmber
class node_validator_cli,node_validator_core,node_lexical,node_schema,node_rules,node_psychometric,node_validation_models toneMint
class node_student toneIndigo
```

## Components

### Practice Platform

- [Web App Entry](https://github.com/aguerta/tops_academy/blob/main/platform/src/main.tsx): `platform/src/main.tsx`
- [Application Flow](https://github.com/aguerta/tops_academy/blob/main/platform/src/App.tsx): `platform/src/App.tsx`
- [Course Library](https://github.com/aguerta/tops_academy/blob/main/platform/src/components/CourseLibrary.tsx): `platform/src/components/CourseLibrary.tsx`
- [Course Overview](https://github.com/aguerta/tops_academy/blob/main/platform/src/components/CourseOverview.tsx): `platform/src/components/CourseOverview.tsx`
- [Practice Session](https://github.com/aguerta/tops_academy/blob/main/platform/src/components/PracticeSession.tsx): `platform/src/components/PracticeSession.tsx`
- [Question Card](https://github.com/aguerta/tops_academy/blob/main/platform/src/components/QuestionCard.tsx): `platform/src/components/QuestionCard.tsx`
- [Feedback](https://github.com/aguerta/tops_academy/blob/main/platform/src/components/FeedbackToast.tsx): `platform/src/components/FeedbackToast.tsx`
- [Completion Screen](https://github.com/aguerta/tops_academy/blob/main/platform/src/components/CompletionScreen.tsx): `platform/src/components/CompletionScreen.tsx`
- [Course Challenge](https://github.com/aguerta/tops_academy/blob/main/platform/src/components/CourseChallenge.tsx): `platform/src/components/CourseChallenge.tsx`
- [Mastery Tracking](https://github.com/aguerta/tops_academy/blob/main/platform/src/utils/masteryStorage.ts): `platform/src/utils/masteryStorage.ts`
- [Session Recovery](https://github.com/aguerta/tops_academy/blob/main/platform/src/utils/sessionStore.ts): `platform/src/utils/sessionStore.ts`
- [Math Equivalence](https://github.com/aguerta/tops_academy/blob/main/platform/src/utils/mathEquivalence.ts): `platform/src/utils/mathEquivalence.ts`
- [Question Utilities](https://github.com/aguerta/tops_academy/blob/main/platform/src/utils/questionUtils.ts): `platform/src/utils/questionUtils.ts`
- [Math Rendering](https://github.com/aguerta/tops_academy/blob/main/platform/src/components/MathText.tsx): `platform/src/components/MathText.tsx`

### Course Discovery

- [Course API Server](https://github.com/aguerta/tops_academy/blob/main/platform/server/courseServer.cjs): `platform/server/courseServer.cjs`
- [Course Index](https://github.com/aguerta/tops_academy/blob/main/platform/server/courseIndex.cjs): `platform/server/courseIndex.cjs`
- [Course Loader](https://github.com/aguerta/tops_academy/blob/main/platform/src/utils/courseLoader.ts): `platform/src/utils/courseLoader.ts`
- **Course JSON Banks**

### Course Validation

- [Validator CLI](https://github.com/aguerta/tops_academy/blob/main/src/validator/cli.py): `src/validator/cli.py`
- [Validation Core](https://github.com/aguerta/tops_academy/blob/main/src/validator/core.py): `src/validator/core.py`
- [Lexical Scanner](https://github.com/aguerta/tops_academy/blob/main/src/validator/lexical_scanner.py): `src/validator/lexical_scanner.py`
- [Schema Validator](https://github.com/aguerta/tops_academy/blob/main/src/validator/schema_validator.py): `src/validator/schema_validator.py`
- [Structural Rules](https://github.com/aguerta/tops_academy/blob/main/src/validator/rules.py): `src/validator/rules.py`
- [Psychometric Checks](https://github.com/aguerta/tops_academy/blob/main/src/validator/psychometric_checker.py): `src/validator/psychometric_checker.py`
- [Validation Results](https://github.com/aguerta/tops_academy/blob/main/src/validator/models.py): `src/validator/models.py`

### Other components

- **Student**

## Connections

- Student → Web App Entry: opens (evidence: `platform/src/main.tsx`)
- Web App Entry → Application Flow: renders (evidence: `platform/src/main.tsx`)
- Application Flow → Course Loader: loads courses (evidence: `platform/src/App.tsx`)
- Application Flow → Course Library: shows (evidence: `platform/src/App.tsx`)
- Course Library → Application Flow: selects course (evidence: `platform/src/App.tsx`)
- Application Flow → Mastery Tracking: loads progress (evidence: `platform/src/App.tsx`)
- Application Flow → Session Recovery: restores session (evidence: `platform/src/App.tsx`)
- Course Overview → Mastery Tracking: reads progress (evidence: `platform/src/components/CourseOverview.tsx`)
- Practice Session → Question Card: renders (evidence: `platform/src/components/PracticeSession.tsx`)
- Practice Session → Feedback: shows feedback (evidence: `platform/src/components/PracticeSession.tsx`)
- Practice Session → Math Equivalence: checks answers (evidence: `platform/src/components/PracticeSession.tsx`)
- Practice Session → Question Utilities: grades choices (evidence: `platform/src/components/PracticeSession.tsx`)
- Practice Session → Session Recovery: saves session (evidence: `platform/src/components/PracticeSession.tsx`)
- Question Card → Question Utilities: normalizes questions (evidence: `platform/src/components/QuestionCard.tsx`)
- Question Card → Math Rendering: renders math (evidence: `platform/src/components/QuestionCard.tsx`)
- Course Overview → Math Rendering: renders content (evidence: `platform/src/components/CourseOverview.tsx`)
- Feedback → Math Rendering: renders content (evidence: `platform/src/components/FeedbackToast.tsx`)
- Completion Screen → Math Rendering: renders content (evidence: `platform/src/components/CompletionScreen.tsx`)
- Completion Screen → Mastery Tracking: reads progress (evidence: `platform/src/components/CompletionScreen.tsx`)
- Course Challenge → Mastery Tracking: records mastery
- Course API Server → Course Index: uses index (evidence: `platform/server/courseServer.cjs`)
- Course Index → Course JSON Banks: scans banks (evidence: `platform/server/courseIndex.cjs`)
- Course Loader → Course API Server: fetches course data
- Validator CLI → Validation Core: runs validation (evidence: `src/validator/cli.py`)
- Validation Core → Lexical Scanner: checks syntax (evidence: `src/validator/core.py`)
- Validation Core → Schema Validator: checks schema (evidence: `src/validator/core.py`)
- Validation Core → Structural Rules: checks rules (evidence: `src/validator/core.py`)
- Validation Core → Psychometric Checks: checks quality (evidence: `src/validator/core.py`)
- Validation Core → Validation Results: builds results (evidence: `src/validator/core.py`)
- Structural Rules → Validation Results: creates errors (evidence: `src/validator/rules.py`)
- Lexical Scanner → Validation Results: creates errors (evidence: `src/validator/lexical_scanner.py`)
