docs/02_architecture.md

Application Architecture

1. Core Technology Stack

This application is a modern, lightweight single-page application (SPA) built with:

• React 19: The core UI library. We leverage React's component-based architecture and hooks (useState, useMemo) for managing state and logic.
• TypeScript: For static typing, which improves code quality, maintainability, and developer experience by catching errors early.
• Unicode for Math: All mathematical notation is handled using standard Unicode characters directly within the content. This approach removes external dependencies and simplifies the rendering pipeline.
• CSS-in-JS (via Style Objects): All styling is colocated within a single TypeScript file (src/styles/appStyles.ts). This approach provides typed styles and avoids the need for a separate CSS pipeline, simplifying the build process.
• No Build Step: The project uses import maps in index.html to load React from a CDN. This allows for rapid development without a complex bundler like Webpack or Vite.

2. Project Structure

The project is organized into a logical and scalable structure:

/
├── docs/                 # Documentation files (pedagogy, architecture, etc.)
├── src/                  # Application source code
│   ├── components/       # Reusable React components
│   │   ├── Calculator.tsx  # Interactive worksheet component
│   │   ├── ContentPage.tsx # Renders the basic layout for a content slide
│   │   ├── ContentRenderer.tsx # Renders different types of content (text, list, formula)
│   │   ├── ProgressBar.tsx # Visual progress indicator
│   │   ├── Quiz.tsx        # Multiple-choice quiz component
│   │   └── SlideRenderer.tsx # Dynamically renders the correct slide type
│   ├── data/             # Static data, including slide content
│   │   └── slides.ts     # The core content of the lesson
│   ├── styles/           # Styling definitions
│   │   └── appStyles.ts    # Centralized CSS-in-JS style objects
│   └── App.tsx           # Main application component, manages state
├── index.html            # The entry point of the application
├── index.tsx             # Renders the React root
└── metadata.json         # Application metadata

3. State Management

Application state is managed using a minimalist approach suitable for the app's scope:

• Global State (App.tsx): The main App component holds the primary piece of state: step, an integer representing the current slide index.
• Local State (components/*): Components manage their own internal state. For example, Calculator.tsx uses useState to track user inputs and submission status, and Quiz.tsx uses it to track the selected answer. This encapsulation keeps components self-contained and easy to reason about.

4. Component-Based Design

The application's architecture is highly modular and follows best practices for component design.

• App.tsx: The top-level component that orchestrates the UI. It manages navigation between slides and passes the current slide's data down to the SlideRenderer.
• SlideRenderer.tsx: A crucial component that acts as a router. It inspects the type property of the current slide's data and renders the appropriate layout and components (ContentPage, Quiz, Calculator).
• ContentRenderer.tsx: A central component responsible for interpreting the content array from the slide data. It dynamically renders paragraphs, lists, and formulas containing Unicode math and HTML.
• ContentPage.tsx: This component is a pure layout component. It renders the slide's title and subtitle and then delegates all block-level content rendering to the ContentRenderer.
• Interactive Components (Quiz, Calculator): These are specialized components responsible for rendering interactive elements. They handle their own state and logic.

5. Data Flow

The application follows a clean, unidirectional data flow and features a highly structured data model.

1. Data Model (slides.ts): The slides.ts file is the single source of truth. The SlideData interface uses a unified content array. Each slide's content is an array of ContentItem objects. Each object has a type (e.g., 'paragraph', 'list', 'formula') and the corresponding data. Mathematical notation is stored directly as Unicode strings.
2. Data Propagation: The main App component reads from slidesData based on the current step.
3. Props Drilling: The relevant slide data object is passed down as props from App to SlideRenderer, which then passes it to the appropriate layout and content components.

This architecture makes the application predictable, maintainable, and easy to debug.