# richardzimring/heatmap architecture

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

- Interactive diagram: https://gitdiagram.com/richardzimring/heatmap
- Repository: https://github.com/richardzimring/heatmap

## Overview

##### Project type and purpose
- Purpose: display live, interactive stock-option heatmap data for any ticker, direction, and metric.

##### File structure
- Top level splits into two clearly separated directories:
- back-end – a Serverless/Node.js (TypeScript) service with three Lambda handlers (getDates, getOptions, getQuote) plus types and a Serverless framework config (serverless.yml).
- front-end – a React/TypeScript SPA (App.tsx, Heatmap.tsx, utilities, static assets in public/).
- Configuration files:
- back-end/serverless.yml – defines AWS Lambda functions, API Gateway endpoints, IAM roles.
- front-end/tsconfig.json, package.json, public/manifest.json – standard CRA or similar setup.

##### Core components & their roles
a. Frontend (React SPA)
- App.tsx, Heatmap.tsx: UI layers for rendering heatmap, controls for ticker/direction/metrics.
- init/init.tsx, utils.tsx, useWindowDimensions.js: bootstrap and helper code.
- Bundled/static assets deployed to S3 + distribution (CloudFront) or similar.
b. API Layer (AWS API Gateway)
- Routes mapped in serverless.yml to three Lambda functions.
c. Business Logic (AWS Lambda functions)
- utils.ts: shared logic for error handling, request shaping.
- types/*.ts: TypeScript interfaces for request/response payloads.
d. External Services
- Third-party stock/option data provider (HTTP API).

##### Relationships and data flow
1. User’s browser (React app) requests heatmap parameters (ticker, metric, direction).
2. Frontend issues REST calls to API Gateway endpoints (e.g., GET /dates, /options, /quote).
3. API Gateway routes call the corresponding AWS Lambda function.
4. Lambda function uses internal utils and types, then calls the external data provider.
5. External service returns raw data → Lambda transforms it into JSON matching types/datesResponse, options, quoteResponse → returns to API Gateway → HTTP response back to browser.
6. React UI parses JSON, updates state, re-renders the heatmap component.

##### Architectural patterns and design principles
- Clear separation of concerns: UI vs. domain logic vs. infra config.
- Serverless microservices: each Lambda does one job (Single Responsibility).
- Type safety everywhere (TS in front-end and back-end).
- Declarative infra-as-code (serverless.yml).
- SPA static hosting + CDN + API Gateway + Lambda for minimal ops overhead.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Front-end (React SPA)"
        FEApp["Browser / React App"]:::frontend
        App["App.tsx"]:::frontend
        Heatmap["Heatmap.tsx"]:::frontend
        Init["init/init.tsx"]:::frontend
        UtilsFE["utils.tsx"]:::frontend
        Hook["useWindowDimensions.js"]:::frontend
        Manifest["public/index.html / manifest.json"]:::frontend
        FEApp --> App
        FEApp --> Heatmap
        FEApp --> Init
        FEApp --> UtilsFE
        FEApp --> Hook
    end

    FEApp -->|"Initial page load"| Static["Static Hosting (S3/CloudFront)"]:::infra
    Static --> FEApp

    FEApp -->|"GET /dates, /options, /quote"| APIGW["AWS API Gateway"]:::awsinfra

    subgraph "Back-end (Serverless)"
        Config["serverless.yml"]:::infra
        APIGW --> Config
        subgraph "Lambda Functions & Services"
            Dates["getDates"]:::lambda
            Options["getOptions"]:::lambda
            Quote["getQuote"]:::lambda
            UtilsBE["Shared Utils"]:::backend
            TypesDR["datesResponse.ts"]:::backend
            TypesOpt["options.ts"]:::backend
            TypesQR["quoteResponse.ts"]:::backend
        end
        APIGW --> Dates
        APIGW --> Options
        APIGW --> Quote
        Config --> Dates
        Config --> Options
        Config --> Quote
        Dates --> UtilsBE
        Options --> UtilsBE
        Quote --> UtilsBE
        Dates --> TypesDR
        Options --> TypesOpt
        Quote --> TypesQR
    end

    subgraph "External Services"
        StockAPI["External Stock Data API"]:::external
    end

    Dates -->|"HTTP API call"| StockAPI
    Options -->|"HTTP API call"| StockAPI
    Quote -->|"HTTP API call"| StockAPI
    StockAPI --> Dates
    StockAPI --> Options
    StockAPI --> Quote
    Dates --> APIGW
    Options --> APIGW
    Quote --> APIGW
    APIGW --> FEApp

    click App "https://github.com/richardzimring/heatmap/blob/main/front-end/src/App.tsx"
    click Heatmap "https://github.com/richardzimring/heatmap/blob/main/front-end/src/Heatmap.tsx"
    click Init "https://github.com/richardzimring/heatmap/blob/main/front-end/src/init/init.tsx"
    click UtilsFE "https://github.com/richardzimring/heatmap/blob/main/front-end/src/utils.tsx"
    click Hook "https://github.com/richardzimring/heatmap/blob/main/front-end/src/useWindowDimensions.js"
    click Manifest "https://github.com/richardzimring/heatmap/blob/main/front-end/public/index.html"
    click Manifest "https://github.com/richardzimring/heatmap/blob/main/front-end/public/manifest.json"
    click Config "https://github.com/richardzimring/heatmap/blob/main/back-end/serverless.yml"
    click Dates "https://github.com/richardzimring/heatmap/blob/main/back-end/requests/getDates.ts"
    click Options "https://github.com/richardzimring/heatmap/blob/main/back-end/requests/getOptions.ts"
    click Quote "https://github.com/richardzimring/heatmap/blob/main/back-end/requests/getQuote.ts"
    click UtilsBE "https://github.com/richardzimring/heatmap/blob/main/back-end/utils.ts"
    click TypesDR "https://github.com/richardzimring/heatmap/blob/main/back-end/types/datesResponse.ts"
    click TypesOpt "https://github.com/richardzimring/heatmap/blob/main/back-end/types/options.ts"
    click TypesQR "https://github.com/richardzimring/heatmap/blob/main/back-end/types/quoteResponse.ts"

    classDef frontend fill:#D0E8FF,stroke:#0366d6,color:#0366d6
    classDef backend fill:#E2FFD0,stroke:#228B22,color:#228B22
    classDef awsinfra fill:#FFECB3,stroke:#FF8C00,color:#FF8C00
    classDef lambda fill:#C8E6C9,stroke:#2E7D32,color:#2E7D32
    classDef infra fill:#FFE0B2,stroke:#BF360C,color:#BF360C
    classDef external fill:#E0E0E0,stroke:#616161,color:#616161
```
