# wynx1123/ai-welfare-hub architecture

> Architecture diagram of the GitHub repository wynx1123/ai-welfare-hub, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/wynx1123/ai-welfare-hub
- Repository: https://github.com/wynx1123/ai-welfare-hub

## Overview

This repository is a data-driven directory of AI services offering public or promotional API access. Users browse and filter site listings, compare policies, credits, protocols and live status, then follow a provider’s registration or API links. The documented Arena Hero game-to-Core-redemption capability is a separate branch. Runtime evidence shows refresh fetching guarded public endpoints and preserving stale fields before the static page and README consume the snapshots. Workflow details come from sampled source; broader directory capabilities are retained from the README.

Main entry points: [`scripts/build.mjs`](https://github.com/wynx1123/ai-welfare-hub/blob/main/scripts/build.mjs) (Page and README generation), [`scripts/refresh.mjs`](https://github.com/wynx1123/ai-welfare-hub/blob/main/scripts/refresh.mjs) (Snapshot refresh), [`scripts/lib/fetchGuard.mjs`](https://github.com/wynx1123/ai-welfare-hub/blob/main/scripts/lib/fetchGuard.mjs) (Guarded fetch), [`docs/index.html`](https://github.com/wynx1123/ai-welfare-hub/blob/main/docs/index.html) (Browse and filter)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_catalog["Service catalog"]
  node_site_catalog["Provider records<br/>[sites.json]"]
  node_free_api_data["Free API listings<br/>[free-apis.json]"]
  node_provider_sites(("Listed AI services"))
end

subgraph group_monitoring["Live monitoring"]
  node_live_snapshot[("Live snapshot<br/>[live.json]")]
  node_refresh["Snapshot refresh<br/>[refresh.mjs]"]
  node_safe_fetch["Guarded fetch<br/>[fetchGuard.mjs]"]
  node_provider_public_apis(("Provider status APIs"))
end

subgraph group_publication["Directory presentation"]
  node_static_page["Browse and filter<br/>[index.html]"]
  node_readme["Policy directory<br/>[README.md]"]
  node_build["Page and README generation<br/>[build.mjs]"]
end

subgraph group_arena["Arena redemption"]
  node_arena_game(("Arena Hero game"))
  node_core_exchange(("Core redemption shop"))
  node_redeem_codes["Provider access codes"]
end

node_visitor(("Directory visitor"))
node_visitor_provider(("Provider registration"))

node_refresh -->|"reads providers"| node_site_catalog
node_refresh -->|"reads prior snapshot"| node_live_snapshot
node_refresh -->|"requests guarded fetch"| node_safe_fetch
node_safe_fetch -->|"probes home and mirrors"| node_provider_sites
node_safe_fetch -->|"fetches status and pricing"| node_provider_public_apis
node_refresh -->|"writes refreshed snapshot"| node_live_snapshot
node_build -->|"reads listing data"| node_site_catalog
node_build -->|"reads live status"| node_live_snapshot
node_build -->|"reads API listings"| node_free_api_data
node_build -->|"generates page"| node_static_page
node_build -->|"generates directory"| node_readme
node_visitor -->|"browses and filters"| node_static_page
node_static_page -->|"links to signup"| node_visitor_provider
node_visitor -->|"reads provider policies"| node_readme
node_readme -->|"links to signup"| node_visitor_provider
node_arena_game -->|"earns Core for"| node_core_exchange
node_core_exchange -->|"exchanges for codes"| node_redeem_codes

click node_site_catalog "https://github.com/wynx1123/ai-welfare-hub/blob/main/data/sites.json"
click node_live_snapshot "https://github.com/wynx1123/ai-welfare-hub/blob/main/data/live.json"
click node_free_api_data "https://github.com/wynx1123/ai-welfare-hub/blob/main/data/free-apis.json"
click node_refresh "https://github.com/wynx1123/ai-welfare-hub/blob/main/scripts/refresh.mjs"
click node_safe_fetch "https://github.com/wynx1123/ai-welfare-hub/blob/main/scripts/lib/fetchGuard.mjs"
click node_static_page "https://github.com/wynx1123/ai-welfare-hub/blob/main/docs/index.html"
click node_readme "https://github.com/wynx1123/ai-welfare-hub/blob/main/README.md"
click node_build "https://github.com/wynx1123/ai-welfare-hub/blob/main/scripts/build.mjs"

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_site_catalog,node_free_api_data,node_provider_sites toneBlue
class node_live_snapshot,node_refresh,node_safe_fetch,node_provider_public_apis toneAmber
class node_static_page,node_readme,node_build toneMint
class node_arena_game,node_core_exchange,node_redeem_codes toneRose
class node_visitor,node_visitor_provider toneIndigo
```

## Components

### Service catalog

- [Provider records](https://github.com/wynx1123/ai-welfare-hub/blob/main/data/sites.json): `data/sites.json`
- [Free API listings](https://github.com/wynx1123/ai-welfare-hub/blob/main/data/free-apis.json): `data/free-apis.json`
- **Listed AI services**

### Live monitoring

- [Live snapshot](https://github.com/wynx1123/ai-welfare-hub/blob/main/data/live.json): `data/live.json`
- [Snapshot refresh](https://github.com/wynx1123/ai-welfare-hub/blob/main/scripts/refresh.mjs): `scripts/refresh.mjs`
- [Guarded fetch](https://github.com/wynx1123/ai-welfare-hub/blob/main/scripts/lib/fetchGuard.mjs): `scripts/lib/fetchGuard.mjs`
- **Provider status APIs**

### Directory presentation

- [Browse and filter](https://github.com/wynx1123/ai-welfare-hub/blob/main/docs/index.html): `docs/index.html`
- [Policy directory](https://github.com/wynx1123/ai-welfare-hub/blob/main/README.md): `README.md`
- [Page and README generation](https://github.com/wynx1123/ai-welfare-hub/blob/main/scripts/build.mjs): `scripts/build.mjs`

### Arena redemption

- **Arena Hero game**
- **Core redemption shop**
- **Provider access codes**

### Other components

- **Directory visitor**
- **Provider registration**

## Connections

- Snapshot refresh → Provider records: reads providers
- Snapshot refresh → Live snapshot: reads prior snapshot
- Snapshot refresh → Guarded fetch: requests guarded fetch
- Guarded fetch → Listed AI services: probes home and mirrors
- Guarded fetch → Provider status APIs: fetches status and pricing
- Snapshot refresh → Live snapshot: writes refreshed snapshot
- Page and README generation → Provider records: reads listing data
- Page and README generation → Live snapshot: reads live status
- Page and README generation → Free API listings: reads API listings
- Page and README generation → Browse and filter: generates page
- Page and README generation → Policy directory: generates directory
- Directory visitor → Browse and filter: browses and filters
- Browse and filter → Provider registration: links to signup
- Directory visitor → Policy directory: reads provider policies
- Policy directory → Provider registration: links to signup
- Arena Hero game → Core redemption shop: earns Core for
- Core redemption shop → Provider access codes: exchanges for codes