# wongjiahau/ttap-web architecture

> Architecture diagram of the GitHub repository wongjiahau/ttap-web, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/wongjiahau/ttap-web
- Repository: https://github.com/wongjiahau/ttap-web

## Overview

##### Main Components
- Frontend UI: Built using React (located in src/ts/react). This includes various components like timetable views, dialogs, panels, pages, and tutorial pages.
- State Management: Handled via Redux (directories src/ts/redux/actions, src/ts/redux/reducers, src/ts/redux/containers). This module deals with actions for switching views, updating slots, and managing the timetable states.
- Business Logic & Data Models: Found in src/ts/model, src/ts/dataStructure, src/ts/enums, and src/ts/util. These handle the core timetable, slot, subject, and matrix-related logic.
- Parsers & Converters: Modules in src/ts/parser (and tests for parsing) which convert raw HTML/JSON inputs into usable timetable data.
- Permutator: A specialized module located in src/ts/permutator that deals with finding and generalizing timetable arrangements.
- Backend/configuration/External Services: Although TTAP is a front-end heavy application, there are some integration points to Firebase (with firebase.json, database.rules.json), suggesting some backend or real-time database services. Also, external build and deployment scripts (under scripts, Travis CI, GitHub Actions workflows) give hints about CI/CD integration.

##### Relationships and Interactions
- The React components (UI layer) interact with the Redux store to manage state. This includes dispatching actions (in src/ts/redux/actions) and receiving updated state via connected containers.
- Business logic (data models, matrix handling, and timetable calculations) sits between the UI and data handling modules, being called by Redux actions or even directly by React components when transforming data for presentation.
- Parsing modules are used at the entry-point of data (for example, when reading exported timetable data or HTML from student portals) to convert raw data into domain models.
- The permutator modules implement algorithms to find, generalize, and rearrange timetable slots. These modules are invoked based on user selections and are connected to both the data models and UI feedback components.
- External services and configurations (Firebase, Surge hosting, analytics) are peripheral but tie into aspects such as deployment, user authentication (if present), and analytics.

##### Architectural Patterns & Design Principles
- Component-Based UI: React promotes breaking the UI into reusable, isolated components. The file tree shows distinct directories for various React views, panels, and pages.
- Separation of Concerns: The codebase cleanly separates presentation (React components), state management (Redux), business logic (model, data structure, and permutator modules), and parsing utilities.

##### Relevant Technologies & Frameworks
- React, Redux, TypeScript as the core libraries.
- Node.js as the runtime platform.
- Firebase: for hosting, real-time database, or authentication (evidenced by firebase.json and database.rules.json).
- Material-UI: referenced in the README for UI styling.
- Create-React-App influences the project layout.
- CI/CD tools (GitHub Actions, Travis CI) integrated via configuration files.

##### Capturing Essential Architectural Elements
- Don’t oversimplify: aim to include as many components and interactions as possible to capture real dependencies.
- Be detailed about stateflow, especially between UI events, Redux dispatching, and business logic processing.
- Encompass both the static aspects (file structure, module responsibilities) and the dynamic aspects (how the user flows through timetable creation, conflict resolution, and timetable export features).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend Layer"
        UI["React Components (UI)"]:::ui
    end

    %% State Management
    subgraph "State Management"
        Redux["Redux Store (Actions/Reducers)"]:::redux
    end

    %% Business Logic & Data Models
    subgraph "Business Logic & Data Models"
        Models["Data Models"]:::logic
        Structures["Data Structures"]:::logic
        Enums["Enums"]:::logic
        Utilities["Utilities"]:::logic
    end

    %% Parsers & Converters
    subgraph "Parsers & Converters"
        Parsers["Parsers & Converters"]:::parser
    end

    %% Timetable Permutator
    subgraph "Timetable Permutator"
        Permutator["Timetable Permutator"]:::permutator
    end

    %% Backend & External Services
    subgraph "Backend & External Services"
        FBConfig["Firebase Config"]:::backend
        FBRules["Firebase Rules"]:::backend
        FBIntegration["Firebase Integration"]:::backend
    end

    %% Data Flow between components
    UI -->|"dispatches-action"| Redux
    Redux -->|"updates-state"| UI
    UI -->|"triggers"| Models
    Redux -->|"invokes"| Models
    Parsers -->|"converts-data"| Models
    Models -->|"utilizes"| Structures
    Models -->|"reads"| Enums
    Models -->|"employs"| Utilities
    Models -->|"passes-data"| Permutator
    Permutator -->|"returns-arrangement"| Redux
    Permutator -->|"updates-flow"| UI
    UI -->|"fetches-configuration"| FBConfig
    UI -->|"retrieves-rules"| FBRules
    FBIntegration -->|"integrates-auth"| UI

    %% Click Events
    click UI "https://github.com/wongjiahau/ttap-web/tree/master/src/ts/react"
    click Redux "https://github.com/wongjiahau/ttap-web/tree/master/src/ts/redux"
    click Models "https://github.com/wongjiahau/ttap-web/tree/master/src/ts/model"
    click Structures "https://github.com/wongjiahau/ttap-web/tree/master/src/ts/dataStructure"
    click Enums "https://github.com/wongjiahau/ttap-web/tree/master/src/ts/enums"
    click Utilities "https://github.com/wongjiahau/ttap-web/tree/master/src/ts/util"
    click Parsers "https://github.com/wongjiahau/ttap-web/tree/master/src/ts/parser"
    click Permutator "https://github.com/wongjiahau/ttap-web/tree/master/src/ts/permutator"
    click FBConfig "https://github.com/wongjiahau/ttap-web/blob/master/firebase.json"
    click FBRules "https://github.com/wongjiahau/ttap-web/blob/master/database.rules.json"
    click FBIntegration "https://github.com/wongjiahau/ttap-web/tree/master/src/ts/fire"

    %% Styles
    classDef ui fill:#f9f,stroke:#333,stroke-width:2px;
    classDef redux fill:#bbf,stroke:#333,stroke-width:2px;
    classDef logic fill:#cfc,stroke:#333,stroke-width:2px;
    classDef parser fill:#fcf,stroke:#333,stroke-width:2px;
    classDef permutator fill:#ff9,stroke:#333,stroke-width:2px;
    classDef backend fill:#9cf,stroke:#333,stroke-width:2px;
```
