# xulbux/svg-api architecture

> Architecture diagram of the GitHub repository xulbux/svg-api, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/xulbux/svg-api
- Repository: https://github.com/xulbux/svg-api

## Overview

SVG API is a Cloudflare Workers engine that turns URL requests into dynamic SVG badges, service metrics, icons, stacks, typing animations, and quote cards; it also serves a website with documentation and an interactive URL builder. The principal runtime path is request handling, route interpretation, optional live-metric retrieval, then SVG generation. The graph preserves the documented render modes and website capabilities. Some routing and page wiring is unsampled, so those links are marked unverified rather than presented as inspected calls.

Main entry points: [`src/routes/svg.ts`](https://github.com/xulbux/svg-api/blob/main/src/routes/svg.ts) (SVG Route), [`src/services/fetcher.ts`](https://github.com/xulbux/svg-api/blob/main/src/services/fetcher.ts) (Metric Fetcher), [`src/index.ts`](https://github.com/xulbux/svg-api/blob/main/src/index.ts) (Worker Entry), [`src/svg/renderer.ts`](https://github.com/xulbux/svg-api/blob/main/src/svg/renderer.ts) (Badge Renderer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Worker Runtime"]
  node_worker["Worker Entry<br/>[index.ts]"]
  node_http["HTTP Routes<br/>[http.ts]"]
  node_schema["Route Schema<br/>[schema.ts]"]
  node_svgroute["SVG Route<br/>[svg.ts]"]
  node_params["Parameter Parsing<br/>[params.ts]"]
end

subgraph group_services["Live Services"]
  node_presets["Service Presets<br/>[services.ts]"]
  node_fetcher["Metric Fetcher<br/>[fetcher.ts]"]
  node_metrics["Metric Formatting<br/>[metrics.ts]"]
  node_endpoint["Endpoint Helpers<br/>[endpoint.ts]"]
  node_cache[("Edge Cache<br/>[edgeCache.ts]")]
end

subgraph group_rendering["SVG Rendering"]
  node_renderer["Badge Renderer<br/>[renderer.ts]"]
  node_icons["Icon Renderer<br/>[icons.ts]"]
  node_stack["Stack Renderer<br/>[stack.ts]"]
  node_typing["Typing Renderer<br/>[typing.ts]"]
  node_quote["Quote Renderer<br/>[quote.ts]"]
  node_svgshared["SVG Primitives<br/>[shared.ts]"]
end

subgraph group_website["Website and Builder"]
  node_sitepages["Website Pages"]
  node_docs["Service Docs<br/>[services.ts]"]
  node_builder["Builder Controls"]
  node_builderclient["Builder Client"]
end

node_user(("URL Client"))
node_upstream(("Public Registries"))

node_user -->|"requests URL"| node_worker
node_worker -.->|"dispatches requests"| node_http
node_http -.->|"routes requests"| node_schema
node_schema -.->|"describes endpoints"| node_svgroute
node_svgroute -->|"parses options"| node_params
node_svgroute -->|"resolves metrics"| node_fetcher
node_svgroute -->|"renders badges"| node_renderer
node_svgroute -->|"renders stacks"| node_stack
node_svgroute -->|"resolves typing layout"| node_typing
node_svgroute -->|"renders quotes"| node_quote
node_presets -->|"configures services"| node_fetcher
node_fetcher -->|"reads responses"| node_endpoint
node_fetcher -->|"caches responses"| node_cache
node_fetcher -.->|"fetches metrics"| node_upstream
node_metrics -->|"builds metrics"| node_endpoint
node_renderer -->|"renders icons"| node_icons
node_renderer -->|"uses primitives"| node_svgshared
node_typing -->|"resolves icons"| node_icons
node_typing -->|"uses primitives"| node_svgshared
node_worker -.->|"serves pages"| node_sitepages
node_sitepages -->|"shows service catalog"| node_docs
node_builder -.->|"uses builder logic"| node_builderclient

click node_worker "https://github.com/xulbux/svg-api/blob/main/src/index.ts"
click node_http "https://github.com/xulbux/svg-api/blob/main/src/routes/http.ts"
click node_schema "https://github.com/xulbux/svg-api/blob/main/src/routes/schema.ts"
click node_svgroute "https://github.com/xulbux/svg-api/blob/main/src/routes/svg.ts"
click node_params "https://github.com/xulbux/svg-api/blob/main/src/routes/params.ts"
click node_presets "https://github.com/xulbux/svg-api/blob/main/src/config/services.ts"
click node_fetcher "https://github.com/xulbux/svg-api/blob/main/src/services/fetcher.ts"
click node_metrics "https://github.com/xulbux/svg-api/blob/main/src/services/metrics.ts"
click node_endpoint "https://github.com/xulbux/svg-api/blob/main/src/services/endpoint.ts"
click node_cache "https://github.com/xulbux/svg-api/blob/main/src/services/edgeCache.ts"
click node_renderer "https://github.com/xulbux/svg-api/blob/main/src/svg/renderer.ts"
click node_icons "https://github.com/xulbux/svg-api/blob/main/src/svg/icons.ts"
click node_stack "https://github.com/xulbux/svg-api/blob/main/src/svg/stack.ts"
click node_typing "https://github.com/xulbux/svg-api/blob/main/src/svg/typing.ts"
click node_quote "https://github.com/xulbux/svg-api/blob/main/src/svg/quote.ts"
click node_svgshared "https://github.com/xulbux/svg-api/blob/main/src/svg/shared.ts"
click node_sitepages "https://github.com/xulbux/svg-api/tree/main/src/site/pages"
click node_docs "https://github.com/xulbux/svg-api/blob/main/src/site/catalog/services.ts"
click node_builder "https://github.com/xulbux/svg-api/blob/main/src/site/components/BuilderControls.tsx"
click node_builderclient "https://github.com/xulbux/svg-api/tree/main/src/site/client/builder"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_worker,node_http,node_schema,node_svgroute,node_params,node_user toneBlue
class node_presets,node_fetcher,node_metrics,node_endpoint,node_cache toneAmber
class node_renderer,node_icons,node_stack,node_typing,node_quote,node_svgshared toneMint
class node_sitepages,node_docs,node_builder,node_builderclient toneRose
class node_upstream toneIndigo
```

## Components

### Worker Runtime

- [Worker Entry](https://github.com/xulbux/svg-api/blob/main/src/index.ts): `src/index.ts`
- [HTTP Routes](https://github.com/xulbux/svg-api/blob/main/src/routes/http.ts): `src/routes/http.ts`
- [Route Schema](https://github.com/xulbux/svg-api/blob/main/src/routes/schema.ts): `src/routes/schema.ts`
- [SVG Route](https://github.com/xulbux/svg-api/blob/main/src/routes/svg.ts): `src/routes/svg.ts`
- [Parameter Parsing](https://github.com/xulbux/svg-api/blob/main/src/routes/params.ts): `src/routes/params.ts`

### Live Services

- [Service Presets](https://github.com/xulbux/svg-api/blob/main/src/config/services.ts): `src/config/services.ts`
- [Metric Fetcher](https://github.com/xulbux/svg-api/blob/main/src/services/fetcher.ts): `src/services/fetcher.ts`
- [Metric Formatting](https://github.com/xulbux/svg-api/blob/main/src/services/metrics.ts): `src/services/metrics.ts`
- [Endpoint Helpers](https://github.com/xulbux/svg-api/blob/main/src/services/endpoint.ts): `src/services/endpoint.ts`
- [Edge Cache](https://github.com/xulbux/svg-api/blob/main/src/services/edgeCache.ts): `src/services/edgeCache.ts`

### SVG Rendering

- [Badge Renderer](https://github.com/xulbux/svg-api/blob/main/src/svg/renderer.ts): `src/svg/renderer.ts`
- [Icon Renderer](https://github.com/xulbux/svg-api/blob/main/src/svg/icons.ts): `src/svg/icons.ts`
- [Stack Renderer](https://github.com/xulbux/svg-api/blob/main/src/svg/stack.ts): `src/svg/stack.ts`
- [Typing Renderer](https://github.com/xulbux/svg-api/blob/main/src/svg/typing.ts): `src/svg/typing.ts`
- [Quote Renderer](https://github.com/xulbux/svg-api/blob/main/src/svg/quote.ts): `src/svg/quote.ts`
- [SVG Primitives](https://github.com/xulbux/svg-api/blob/main/src/svg/shared.ts): `src/svg/shared.ts`

### Website and Builder

- [Website Pages](https://github.com/xulbux/svg-api/tree/main/src/site/pages): `src/site/pages`
- [Service Docs](https://github.com/xulbux/svg-api/blob/main/src/site/catalog/services.ts): `src/site/catalog/services.ts`
- [Builder Controls](https://github.com/xulbux/svg-api/blob/main/src/site/components/BuilderControls.tsx): `src/site/components/BuilderControls.tsx`
- [Builder Client](https://github.com/xulbux/svg-api/tree/main/src/site/client/builder): `src/site/client/builder`

### Other components

- **URL Client**
- **Public Registries**

## Connections

- URL Client → Worker Entry: requests URL (evidence: `README.md`)
- Worker Entry → HTTP Routes: dispatches requests (evidence: `src/index.ts`)
- HTTP Routes → Route Schema: routes requests
- Route Schema → SVG Route: describes endpoints (evidence: `src/routes/schema.ts`)
- SVG Route → Parameter Parsing: parses options (evidence: `src/routes/svg.ts`)
- SVG Route → Metric Fetcher: resolves metrics (evidence: `src/routes/svg.ts`)
- SVG Route → Badge Renderer: renders badges (evidence: `src/routes/svg.ts`)
- SVG Route → Stack Renderer: renders stacks (evidence: `src/routes/svg.ts`)
- SVG Route → Typing Renderer: resolves typing layout (evidence: `src/routes/svg.ts`)
- SVG Route → Quote Renderer: renders quotes (evidence: `src/routes/schema.ts`)
- Service Presets → Metric Fetcher: configures services (evidence: `src/config/services.ts`)
- Metric Fetcher → Endpoint Helpers: reads responses (evidence: `src/services/fetcher.ts`)
- Metric Fetcher → Edge Cache: caches responses (evidence: `src/services/fetcher.ts`)
- Metric Fetcher → Public Registries: fetches metrics
- Metric Formatting → Endpoint Helpers: builds metrics (evidence: `src/services/metrics.ts`)
- Badge Renderer → Icon Renderer: renders icons (evidence: `src/svg/renderer.ts`)
- Badge Renderer → SVG Primitives: uses primitives (evidence: `src/svg/renderer.ts`)
- Typing Renderer → Icon Renderer: resolves icons (evidence: `src/svg/typing.ts`)
- Typing Renderer → SVG Primitives: uses primitives (evidence: `src/svg/typing.ts`)
- Worker Entry → Website Pages: serves pages (evidence: `src/index.ts`)
- Website Pages → Service Docs: shows service catalog (evidence: `src/site/pages/ServicesPage.tsx`)
- Builder Controls → Builder Client: uses builder logic
