# wenxuanlee/typescript-generics-workshop architecture

> Architecture diagram of the GitHub repository wenxuanlee/typescript-generics-workshop, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/wenxuanlee/typescript-generics-workshop
- Repository: https://github.com/wenxuanlee/typescript-generics-workshop

## Overview

##### Project type and purpose
- This is an open-source, CLI-based tutorial runner for teaching TypeScript generics.
- It organizes individual “problem” and “solution” exercises in a file hierarchy and lets the user pick and run them via `npm run exercise`.
- Under the hood it uses Node + TypeScript + Vitest (via Vite) to compile, execute, and test each exercise.

##### File structure
- Top-level:
- package.json / package-lock.json – NPM scripts, dependencies, and entrypoints (e.g. `exercise`)
- tsconfig.json / vite.config.mts – TypeScript compiler settings and Vitest/Vite test configuration
- scripts/tests – custom test harness and snapshots
- src – exercise modules organized by chapters (`01-generics-intro`, `02-passing-type-arguments`, …) plus `helpers/type-utils.ts`
- Each exercise folder contains `.problem.ts` and sometimes `.explainer.ts` files (and solutions implicitly defined).
- CI workflows under `.github/workflows` run checks and Renovate.

##### README for additional insights
- Describes the interactive workflow: prompt user → run chosen exercise → tests pass or fail → reveal solutions.
- Encourages exploratory, test-driven learning.

##### Main components and their interactions
a. User (CLI)
b. CLI Entrypoint (defined in package.json: `npm run exercise`)
c. Exercise Manager / Prompt Module – scans `src/*/*.problem.ts`, displays choices, loads selected module
d. TypeScript Execution Environment – uses TS Node or Vite to compile+execute TypeScript on the fly
e. Test Runner – Vitest (configured via `vite.config.mts` and `scripts/tests`) that runs the test suite for the chosen exercise and compares against snapshots
f. Helpers – shared utilities in `src/helpers/type-utils.ts`
g. File System – the physical `src` directory and snapshot files under `scripts/tests/__snapshots__`
h. CI/CD – GitHub Actions workflows for automated checks and Renovate updates

##### Architectural patterns and design principles
- Modular per-exercise structure (one folder per exercise).
- Separation of concerns: CLI & prompt logic, test harness, exercise code, helpers.
- Test-driven learning: exercises fail until the user implements a solution that satisfies the tests.
- Configuration-as-code: TS config, Vite config, and NPM scripts define behavior.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User-facing components
    User["User (CLI)"]:::user
    CLI["CLI Entrypoint"]:::user
    Console["Console Output"]:::user

    %% Internal modules
    Prompt["Prompt Module / Exercise Manager"]:::internal
    Helpers["Helpers"]:::internal

    %% External tools
    TSExec["TS Execution Engine"]:::external
    Vitest["Vitest Test Runner"]:::external
    CI["CI/CD (GitHub Actions)"]:::external

    %% File system and exercises
    subgraph "File System" 
        FS_src["src directory"]:::fs
        subgraph "Exercise Modules" 
            Ex1["01-generics-intro"]:::fs
            Ex2["02-passing-type-arguments"]:::fs
            Ex3["03-art-of-type-arguments"]:::fs
            Ex4["04-generics-advanced"]:::fs
            Ex5["05-function-overloads"]:::fs
            Ex6["06-challenges"]:::fs
        end
        FS_snap["scripts/tests/__snapshots__"]:::fs
    end

    %% Test harness and config
    AllTest["all.test.ts"]:::internal
    SnapTest["all.test.ts.snap"]:::fs
    CleanUtil["cleanVitestOutput.ts"]:::internal
    VitestConfigFile["scripts/tests/vite.config.ts"]:::external
    ViteConfig["vite.config.mts"]:::external
    TSConfig["tsconfig.json"]:::external
    PackageJson["package.json"]:::external

    %% Connections
    User -->|"runs npm run exercise"| CLI
    CLI -->|"invokes"| Prompt
    Prompt -->|"scan exercises"| FS_src
    FS_src --> Ex1
    FS_src --> Ex2
    FS_src --> Ex3
    FS_src --> Ex4
    FS_src --> Ex5
    FS_src --> Ex6
    Prompt -->|"load helpers"| Helpers
    Prompt -->|"compile & execute"| TSExec
    Prompt -->|"run tests"| Vitest
    TSExec -->|"reads .problem.ts"| FS_src
    Vitest -->|"reads tests"| AllTest
    Vitest -->|"reads snapshots"| FS_snap
    Vitest -->|"writes cleaned output"| CleanUtil
    Vitest -->|"uses config"| VitestConfigFile
    Vitest -->|"uses Vite config"| ViteConfig
    TSExec -->|"uses TS config"| TSConfig
    Vitest -->|"report results"| Console
    CI -->|"on push runs"| CLI
    CI -->|"on push runs"| Vitest

    %% Click Events
    click PackageJson "https://github.com/wenxuanlee/typescript-generics-workshop/blob/main/package.json"
    click FS_src "https://github.com/wenxuanlee/typescript-generics-workshop/tree/main/src"
    click Ex1 "https://github.com/wenxuanlee/typescript-generics-workshop/tree/main/src/01-generics-intro"
    click Ex2 "https://github.com/wenxuanlee/typescript-generics-workshop/tree/main/src/02-passing-type-arguments"
    click Ex3 "https://github.com/wenxuanlee/typescript-generics-workshop/tree/main/src/03-art-of-type-arguments"
    click Ex4 "https://github.com/wenxuanlee/typescript-generics-workshop/tree/main/src/04-generics-advanced"
    click Ex5 "https://github.com/wenxuanlee/typescript-generics-workshop/tree/main/src/05-function-overloads"
    click Ex6 "https://github.com/wenxuanlee/typescript-generics-workshop/tree/main/src/06-challenges"
    click Helpers "https://github.com/wenxuanlee/typescript-generics-workshop/blob/main/src/helpers/type-utils.ts"
    click TSConfig "https://github.com/wenxuanlee/typescript-generics-workshop/blob/main/tsconfig.json"
    click ViteConfig "https://github.com/wenxuanlee/typescript-generics-workshop/blob/main/vite.config.mts"
    click VitestConfigFile "https://github.com/wenxuanlee/typescript-generics-workshop/blob/main/scripts/tests/vite.config.ts"
    click AllTest "https://github.com/wenxuanlee/typescript-generics-workshop/blob/main/scripts/tests/all.test.ts"
    click SnapTest "https://github.com/wenxuanlee/typescript-generics-workshop/blob/main/scripts/tests/__snapshots__/all.test.ts.snap"
    click CleanUtil "https://github.com/wenxuanlee/typescript-generics-workshop/blob/main/scripts/tests/cleanVitestOutput.ts"
    click CI "https://github.com/wenxuanlee/typescript-generics-workshop/blob/main/ .github/workflows/renovate-checks.yml"
    click CI "https://github.com/wenxuanlee/typescript-generics-workshop/blob/main/ .github/workflows/section-repos.yml"

    %% Styles
    classDef user fill:#e0f8d8,stroke:#2d7a2d,color:#2d7a2d
    classDef internal fill:#d0e8ff,stroke:#1f5fa6,color:#1f5fa6
    classDef external fill:#ffe0b2,stroke:#cc7000,color:#cc7000
    classDef fs fill:#f0f0f0,stroke:#888888,color:#888888
```
