# sittiponghaus/speedtest architecture

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

- Interactive diagram: https://gitdiagram.com/sittiponghaus/speedtest
- Repository: https://github.com/sittiponghaus/speedtest

## Overview

##### Project type and purpose
- This is a small full-stack web application whose frontend is built with Astro (static-site generation + client hydration using React/TSX) and Tailwind CSS, and whose backend consists of two serverless endpoints (download & upload) implemented as Cloudflare Workers. Its purpose is to measure network speed from the user’s browser and display the results in real time.

##### File structure
- Top-level config files:
- astro.config.mjs (Astro build & deploy settings)
- tailwind.config.ts, global.css (styling pipeline)
- tsconfig.json, package.json, pnpm-lock.yaml (TypeScript & dependency management)
- Public assets:
- public/assets/fonts/inter.css (static fonts)
- Frontend source (ASTRO + React components):
- src/pages/index.astro (entry page, imports layout + components)
- src/components/layout.astro (page shell)
- src/components/speed/* (UI building blocks: card, indicator, text)
- src/container/speedtest.container.tsx (component orchestration & business logic)
- src/lib/*:
– math.ts (throughput calculations)
– utils.ts (general helpers)
– xhr.ts (XHR wrapper to call your API endpoints)
- Serverless API endpoints (Cloudflare Workers):
- src/pages/api/speed-test/download.ts
- src/pages/api/speed-test/upload.ts

##### Key insights from the README
- “Exploring Cloudflare Workers using Astro and React.”
- Live demo at https://speedtest.sittipong.com/

##### Main components to capture
a. Client Browser (User Agent)
b. Static Asset CDN (Astro-generated HTML/CSS/JS & public assets)
c. React + Astro Frontend:
- Page Shell (layout.astro)
- Speed UI Components (card, indicator, text)
- Container Layer (speedtest.container.tsx)
d. Utility Library (math.ts, utils.ts, xhr.ts)
e. Serverless Backend (Cloudflare Workers):
- Download endpoint
- Upload endpoint
f. External Services (e.g., Cloudflare Pages or other host/CDN)

##### Relationships & data flow
- 1 → 2: Browser requests static page & assets from CDN
- 2 → 3: Astro serves index.astro, hydrates React components
- 3 → 4: On speed-test start, container calls xhr.ts
- 4 → 5: xhr.ts issues HTTP requests to /api/speed-test/download and /upload
- 5 → 4: Workers respond with chunks or results
- 4 → 3: Container computes throughput via math.ts, updates UI components
- 3 → 1: Browser renders updated speed indicator

##### Architectural patterns & design principles
- Static-site generation + client hydration (Astro)
- Component decomposition (UI atoms & container pattern)
- Separation of concerns: UI vs. business logic vs. network I/O vs. calculation
- Serverless micro-endpoints for compute-on-demand
- Type safety (TypeScript)

##### Detail
- Every folder’s responsibility (components vs. container vs. lib)
- Both download & upload paths separately
- Where Tailwind and global.css fit (styling pipeline)
- Build step (Astro → static/bundled JS)

## Diagram (Mermaid)

```mermaid
flowchart TB
    Browser["Browser (User Agent)"]:::external
    CDN["CDN / Static Assets (HTML/CSS/JS)"]:::external

    subgraph "Hosting / Build Configuration"
        AstroConfig["astro.config.mjs"]:::external
        TailwindConfig["tailwind.config.ts"]:::external
        GlobalCSS["src/global.css"]:::frontend
        Font["public/assets/fonts/inter.css"]:::external
    end

    subgraph "Presentation Layer"
        Index["src/pages/index.astro"]:::frontend
        Layout["src/components/layout.astro"]:::frontend
        Card["src/components/speed/card.tsx"]:::frontend
        Indicator["src/components/speed/indicator.tsx"]:::frontend
        TextComp["src/components/speed/text.tsx"]:::frontend
    end

    subgraph "Client Logic Layer"
        Container["src/container/speedtest.container.tsx"]:::frontend
        XHR["src/lib/xhr.ts"]:::lib
        MathUtil["src/lib/math.ts"]:::lib
        Utils["src/lib/utils.ts"]:::lib
    end

    subgraph "Serverless API Layer"
        Download["src/pages/api/speed-test/download.ts"]:::serverless
        Upload["src/pages/api/speed-test/upload.ts"]:::serverless
    end

    Browser -->|requests page| CDN
    CDN -->|serves index| Index
    Index -->|uses layout| Layout
    Index -->|renders component| Card
    Index -->|renders component| Indicator
    Index -->|renders component| TextComp
    Index -->|hydrates container| Container

    Container -->|calls| XHR
    Container -->|calls| MathUtil
    Container -->|uses| Utils

    XHR -->|HTTP request| Download
    XHR -->|HTTP request| Upload
    Download -->|response chunks| XHR
    Upload -->|response result| XHR

    Container -->|updates UI| Index
    Index -->|renders update| Browser

    AstroConfig --> CDN
    TailwindConfig --> GlobalCSS
    GlobalCSS --> CDN
    Font --> CDN

    click AstroConfig "https://github.com/sittiponghaus/speedtest/blob/main/astro.config.mjs"
    click TailwindConfig "https://github.com/sittiponghaus/speedtest/blob/main/tailwind.config.ts"
    click GlobalCSS "https://github.com/sittiponghaus/speedtest/blob/main/src/global.css"
    click Font "https://github.com/sittiponghaus/speedtest/blob/main/public/assets/fonts/inter.css"
    click Index "https://github.com/sittiponghaus/speedtest/blob/main/src/pages/index.astro"
    click Layout "https://github.com/sittiponghaus/speedtest/blob/main/src/components/layout.astro"
    click Card "https://github.com/sittiponghaus/speedtest/blob/main/src/components/speed/card.tsx"
    click Indicator "https://github.com/sittiponghaus/speedtest/blob/main/src/components/speed/indicator.tsx"
    click TextComp "https://github.com/sittiponghaus/speedtest/blob/main/src/components/speed/text.tsx"
    click Container "https://github.com/sittiponghaus/speedtest/blob/main/src/container/speedtest.container.tsx"
    click MathUtil "https://github.com/sittiponghaus/speedtest/blob/main/src/lib/math.ts"
    click Utils "https://github.com/sittiponghaus/speedtest/blob/main/src/lib/utils.ts"
    click XHR "https://github.com/sittiponghaus/speedtest/blob/main/src/lib/xhr.ts"
    click Download "https://github.com/sittiponghaus/speedtest/blob/main/src/pages/api/speed-test/download.ts"
    click Upload "https://github.com/sittiponghaus/speedtest/blob/main/src/pages/api/speed-test/upload.ts"

    classDef frontend fill:#D0E8FF,stroke:#0366d6,color:#0366d6
    classDef lib fill:#D0FFD8,stroke:#28a745,color:#28a745
    classDef serverless fill:#FFD8A8,stroke:#d73a49,color:#d73a49
    classDef external fill:#E0E0E0,stroke:#6a737d,color:#6a737d
```
