# evilmartians/oklch-picker architecture

> Architecture diagram of the GitHub repository evilmartians/oklch-picker, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/evilmartians/oklch-picker
- Repository: https://github.com/evilmartians/oklch-picker

## Overview

##### Project Type and Purpose
- It is entirely client-side, served as static assets (HTML/CSS/JS) and deployed (via Firebase Hosting) to a CDN. Build and CI/CD are managed with Vite, pnpm, and GitHub Actions.

##### High-Level Components
A. Client-side Runtime (Browser)
1. Entry Point
- index.html / index.ts
- Loads the SPA bundle, injects root component, sets up global stores.
2. UI Layer
- view/… folder: Pug templates, TS components, CSS/PostCSS files
- Components (button, chart, field, etc.) implement the interactive UI.
3. State Management
- Acts as the single source of truth for the UI.
4. Domain Logic
5. Web Workers
- view/chart/worker.ts and lib/workers.ts: offload heavy computations (e.g., chart path generation) to worker threads to keep UI responsive.
6. Assets & Manifests
- public/*.webmanifest: PWA metadata

B. Build & Toolchain
1. Build Configuration
- vite.config.js, config.js: define entry points, plugins (Pug, PostCSS), build targets
- tsconfig.json: TypeScript compiler settings
2. Linting & Formatting
- eslint.config.js, .stylelintrc, .prettierrc, .editorconfig: enforce code style across JS/TS/CSS/Pug
3. Testing & Quality
- .github/workflows/ci.yml: runs lint, tests, size-limit, builds on each PR

C. CI/CD & Deployment
1. Source Control & CI
- GitHub Actions (ci.yml): installs dependencies (pnpm), runs tests, lint, size-limit, then builds.
2. Hosting
- firebase.json: Firebase Hosting configuration, redirects, PWA caching.
3. Releases
- package.json / pnpm-lock.yaml: versioning and dependencies published to npm if needed.

##### Relationships & Data Flows
- Build-time: Source (view/, lib/, stores/, index.ts) → Vite → optimized JS/CSS/HTML bundle → deploy to Firebase.
- Web worker offload: Components dispatch heavy jobs to worker threads via lib/workers → worker returns results → main thread updates canvas/DOM.

##### Architectural Patterns & Principles
- Modular separation: UI (view/) vs State (stores/) vs Domain Logic (lib/).
- Reactive data flow: updates in stores automatically propagate to subscribed components.
- PWA best practices: webmanifest, static asset caching.
- Performance optimization: Web Workers for heavy computations; tree-shaking via Vite.

## Diagram (Mermaid)

```mermaid
flowchart TD
  subgraph "Development Environment"
    direction TB
    EP_HTML["index.html"]:::frontend
    EP_TS["index.ts"]:::frontend
    UI["view/"]:::frontend
    ST["stores/"]:::frontend
    DL["lib/"]:::frontend
    WW1["view/chart/worker.ts"]:::frontend
    WW2["lib/workers.ts"]:::frontend
  end

  subgraph "Build & Toolchain"
    direction TB
    VITE["vite.config.js"]:::build
    CFG["config.js"]:::build
    TS_CFG["tsconfig.json"]:::build
    ESL["eslint.config.js"]:::build
    SLINT[".stylelintrc"]:::build
    PRET[".prettierrc"]:::build
    EDCFG[".editorconfig"]:::build
    POSTCSS[".postcssrc"]:::build
    NANO["nano-staged.json"]:::build
  end

  subgraph "CI/CD Pipeline"
    direction TB
    CI[".github/workflows/ci.yml"]:::cicd
    TESTS["test/*.ts"]:::cicd
  end

  subgraph "Deployment"
    direction TB
    FB["firebase.json"]:::deploy
    DEPLOYED["CDN Deployed Assets"]:::deploy
    MANIF["public/"]:::frontend
  end

  subgraph "Runtime (Browser)"
    direction TB
    BROWSER["Browser"]:::frontend
    BUNDLE["SPA Bundle"]:::frontend
    UI_RUN["UI Components"]:::frontend
    STATE["State Stores"]:::frontend
    LOGIC["Domain Logic"]:::frontend
    CANVAS["DOM/Canvas"]:::frontend
    WORKER_RUN["Web Worker"]:::frontend
  end

  %% Build Flow
  EP_HTML & EP_TS & UI & ST & DL & WW1 & WW2 --> VITE
  VITE --> BUNDLE
  CI --> VITE
  CI --> FB
  FB --> DEPLOYED

  %% Deployment to Runtime
  DEPLOYED --> BROWSER
  BROWSER --> BUNDLE

  %% Runtime Data Flow
  BUNDLE --> UI_RUN
  UI_RUN --> STATE
  STATE --> LOGIC
  LOGIC --> UI_RUN
  LOGIC --> CANVAS
  UI_RUN --> WORKER_RUN
  WORKER_RUN --> UI_RUN

  %% Testing connection
  TESTS --> CI

  %% Click Events
  click EP_HTML "https://github.com/evilmartians/oklch-picker/blob/main/index.html"
  click EP_TS "https://github.com/evilmartians/oklch-picker/blob/main/index.ts"
  click UI "https://github.com/evilmartians/oklch-picker/tree/main/view/"
  click ST "https://github.com/evilmartians/oklch-picker/tree/main/stores/"
  click DL "https://github.com/evilmartians/oklch-picker/tree/main/lib/"
  click WW1 "https://github.com/evilmartians/oklch-picker/blob/main/view/chart/worker.ts"
  click WW2 "https://github.com/evilmartians/oklch-picker/blob/main/lib/workers.ts"
  click MANIF "https://github.com/evilmartians/oklch-picker/tree/main/public/"
  click VITE "https://github.com/evilmartians/oklch-picker/blob/main/vite.config.js"
  click CFG "https://github.com/evilmartians/oklch-picker/blob/main/config.js"
  click TS_CFG "https://github.com/evilmartians/oklch-picker/blob/main/tsconfig.json"
  click ESL "https://github.com/evilmartians/oklch-picker/blob/main/eslint.config.js"
  click SLINT "https://github.com/evilmartians/oklch-picker/blob/main/.stylelintrc"
  click PRET "https://github.com/evilmartians/oklch-picker/blob/main/.prettierrc"
  click EDCFG "https://github.com/evilmartians/oklch-picker/blob/main/.editorconfig"
  click POSTCSS "https://github.com/evilmartians/oklch-picker/blob/main/.postcssrc"
  click NANO "https://github.com/evilmartians/oklch-picker/blob/main/nano-staged.json"
  click TESTS "https://github.com/evilmartians/oklch-picker/blob/main/test/colors.test.ts"
  click TESTS "https://github.com/evilmartians/oklch-picker/blob/main/test/inputs.test.ts"
  click TESTS "https://github.com/evilmartians/oklch-picker/blob/main/test/set-globals.js"
  click CI "https://github.com/evilmartians/oklch-picker/blob/main/.github/workflows/ci.yml"
  click FB "https://github.com/evilmartians/oklch-picker/blob/main/firebase.json"
  click DEPLOYED "https://github.com/evilmartians/oklch-picker/blob/main/package.json"
  click DEPLOYED "https://github.com/evilmartians/oklch-picker/blob/main/pnpm-lock.yaml"

  %% Styles
  classDef frontend fill:#bbdefb,stroke:#0d47a1,color:#0d47a1;
  classDef build fill:#c8e6c9,stroke:#1b5e20,color:#1b5e20;
  classDef cicd fill:#ffe0b2,stroke:#e65100,color:#e65100;
  classDef deploy fill:#fff9c4,stroke:#f57f17,color:#f57f17;
```
