# cmackenzie1/holster architecture

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

- Interactive diagram: https://gitdiagram.com/cmackenzie1/holster
- Repository: https://github.com/cmackenzie1/holster

## Overview

##### Project type and purpose
- This is a serverless micro‑services monorepo (“Holster”) containing a suite of Cloudflare Workers (nine individual HTTP endpoints) plus a shared analytics library.
- Purpose: expose small, single‑responsibility HTTP services (echo, hash, ip, rand, rdap, stocks, paste, tfstate) behind friendly URLs, all managed in a single PNPM workspace.

##### File structure
- Top‑level files:
- pnpm-workspace.yaml, package.json, tsconfig.json, biome.json – configure the monorepo, TypeScript, linting, formatting
- .github/workflows/workers.yml – CI/CD definition for build, test, deploy
- /packages/analytics – a shared TypeScript module used by Workers for telemetry
- /workers – each subdirectory is its own Worker:
- apigw – API‑Gateway proxy with CF Access integration
- echo, hash, ip, rand – stateless request handlers
- paste, rdap, stocks – integrate with external services (KV, SQL migrations, RDAP servers, YahooFinance API)
- tfstate – HTTP backend for Terraform state, uses Durable Objects or KV and middlewares
- Each worker has its own wrangler.toml (Cloudflare config), src/, test/, tsconfig.json, and vitest setup.

##### README for additional insights
- Confirms that each worker publishes to its own subdomain on mirio.dev
- Notes tfstate can be accessed via an apigw route for basic‑auth handling
- “Create new Worker” hints at extensibility: plugging additional services into the same workspace

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Developer and CI/CD
    Dev["Developer"]:::blue
    GitHub["GitHub Repo"]:::blue
    Actions["CI/CD (GitHub Actions)"]:::blue

    Dev -->|push code| GitHub
    GitHub -->|trigger workflow| Actions

    %% Monorepo Workspace
    subgraph "Monorepo Workspace (PNPM)" 
        direction TB
        Analytics["Shared Analytics Lib"]:::gray

        subgraph "Workers"
            direction TB
            Apigw["apigw Worker"]:::green
            Echo["echo Worker"]:::green
            Hash["hash Worker"]:::green
            Ip["ip Worker"]:::green
            Rand["rand Worker"]:::green
            Rdap["rdap Worker"]:::green
            Stocks["stocks Worker"]:::green
            Paste["paste Worker"]:::green
            Tfstate["tfstate Worker"]:::green
        end
    end

    %% Build and Deploy
    Actions -->|build & test| Analytics
    Analytics -->|monorepo deps| Apigw
    Analytics --> Echo
    Analytics --> Hash
    Analytics --> Ip
    Analytics --> Rand
    Analytics --> Rdap
    Analytics --> Stocks
    Analytics --> Paste
    Analytics --> Tfstate
    Actions -->|wrangler deploy| CFEdge

    %% Cloudflare Edge Network
    subgraph "Cloudflare Edge Network" 
        direction TB
        CFEdge["Workers Runtime"]:::green
        KVDO["KV / Durable Objects"]:::green
    end

    %% External Services
    subgraph "External Services" 
        direction TB
        RDAPServ["RDAP Servers"]:::orange
        Yahoo["YahooFinance API"]:::orange
        CFAccess["Cloudflare Access"]:::orange
    end

    %% User Flow
    User["End User (HTTP Client)"]:::orange
    User -->|HTTP request| CFEdge
    CFEdge -->|route to| Apigw
    Apigw -->|transform auth| CFAccess
    Apigw -->|forward to| Tfstate
    CFEdge --> Echo
    CFEdge --> Hash
    CFEdge --> Ip
    CFEdge --> Rand
    CFEdge --> Rdap
    CFEdge --> Stocks
    CFEdge --> Paste

    %% Workers interactions
    Paste -->|read/write| KVDO
    Tfstate -->|use| KVDO
    Rdap -->|query| RDAPServ
    Stocks -->|query| Yahoo

    CFEdge -->|respond| User

    %% Click Events
    click Analytics "https://github.com/cmackenzie1/holster/blob/main/packages/analytics/src/index.ts"
    click Apigw "https://github.com/cmackenzie1/holster/blob/main/workers/apigw/src/index.ts"
    click Echo "https://github.com/cmackenzie1/holster/blob/main/workers/echo/src/index.ts"
    click Hash "https://github.com/cmackenzie1/holster/blob/main/workers/hash/src/index.ts"
    click Ip "https://github.com/cmackenzie1/holster/blob/main/workers/ip/src/index.ts"
    click Rand "https://github.com/cmackenzie1/holster/blob/main/workers/rand/src/index.ts"
    click Rdap "https://github.com/cmackenzie1/holster/blob/main/workers/rdap/src/index.ts"
    click Stocks "https://github.com/cmackenzie1/holster/blob/main/workers/stocks/src/index.ts"
    click Paste "https://github.com/cmackenzie1/holster/blob/main/workers/paste/src/index.ts"
    click Tfstate "https://github.com/cmackenzie1/holster/blob/main/workers/tfstate/src/index.ts"
    click CFAccess "https://github.com/cmackenzie1/holster/blob/main/.github/workflows/workers.yml"
    click GitHub "https://github.com/cmackenzie1/holster/blob/main/pnpm-workspace.yaml"

    %% Styles
    classDef blue fill:#D0E6FF,stroke:#0284C7,color:#000
    classDef green fill:#D1FAE5,stroke:#059669,color:#000
    classDef orange fill:#FFE7D9,stroke:#FB923C,color:#000
    classDef gray fill:#E5E7EB,stroke:#6B7280,color:#000
```
