# janwilmake/openapisearch architecture

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

- Interactive diagram: https://gitdiagram.com/janwilmake/openapisearch
- Repository: https://github.com/janwilmake/openapisearch

## Overview

##### Project type and purpose
- This is an open‑source, serverless web application and API (“OpenAPI‑Search”) that aggregates and exposes multiple OpenAPI definitions via a searchable interface.
- It combines static front‑end pages (HTML/CSS/JS) with a Cloudflare Worker back end, plus static JSON “registry” assets in the repo (“providers.json”, “openapi.json”, the `handmade/` folder).

##### File structure
- Top‑level static pages: `homepage.html`, `search.html`, `openapi.html`, `provider.html`
- Core serverless code: `main.ts` (entrypoint for Cloudflare Worker routes), `logo.ts` (utility for on‑the‑fly logos)
- Data assets: `providers.json`, `openapi.json`, `handmade/*.json` + schema files (`provider.schema.json`, `providers.schema.json`)
- Deployment config: `wrangler.toml` (Cloudflare Worker config), `package.json`/`tsconfig`

##### README
- Confirms a goal of combining multiple OpenAPI specs into a searchable directory
- Mentions moving to Cloudflare, programmatic registry, AI crawlers planned, schema‑based validation (via actionschema)

##### Main components & interactions
a. Front‑End (Browser)
- Static HTML pages + embedded JS for search UI, API calls, result rendering.
b. Cloudflare Worker (Back‑End)
- Acts as router: serves HTML/JS/CSS assets and JSON endpoints (`/api/search`, `/api/providers/:id`, `/api/openapi/:id`).
- Loads & validates JSON assets against schemas.
- Performs in‑memory or KV‑backed searches over the registry.
- May schedule updates via QStash/Upstash (future AI crawler integration).
c. Data Storage
- Script‑bundled JSON assets as “source of truth.”
- Optionally Cloudflare KV or Upstash Redis for caching or incremental updates.
d. External Services (future/optional)
- AI crawler service for metadata augmentation.
- Third‑party OpenAPI sources (APIs.guru, RapidAPI, etc.)

##### Architectural patterns & design principles
- Serverless “Function as a Service” with Cloudflare Workers
- Static‑first: keep registry data in code assets, load at startup
- JSON‑Schema validation layer to enforce standard compliance
- Separation of concerns:
- Static UI assets vs. dynamic API routes
- Data layer (JSON + optional KV) vs. business logic (search, validation)

##### Technologies & frameworks
- TypeScript / Deno‑like Worker runtime (via Wrangler)
- JSON Schema for data validation
- HTML5/CSS/Vanilla JS for front‑end
- (Planned) Upstash QStash & Redis for scheduling & caching

##### Detailed capture of essential elements
- That the `handmade/` folder JSONs are loaded at build/deploy time as part of the Worker bundle
- Schema files driving validation before indexing

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Browser UI
    subgraph "Browser/UI"
        HomePage["homepage.html"]:::frontend
        SearchPage["search.html"]:::frontend
        OpenAPIPage["openapi.html"]:::frontend
        ProviderPage["provider.html"]:::frontend
    end

    %% Cloudflare Worker Modules
    subgraph "Cloudflare Worker"
        SA["Static Asset Handler"]:::backend
        AR["API Router & Handlers"]:::backend
        SV["Schema Validator Module"]:::backend
        SI["Search/Index Module"]:::backend
        Logo["Logo Utility"]:::backend
    end

    %% Data Storage
    subgraph "Data Storage"
        ProvidersJSON["providers.json"]:::storage
        OpenAPIJSON["openapi.json"]:::storage
        Handmade["handmade/"]:::storage
        KV["KV/Redis (optional)"]:::storage
    end

    %% JSON Schemas
    subgraph "Schemas"
        Sch1["provider.schema.json"]:::storage
        Sch2["providers.schema.json"]:::storage
    end

    %% External Services
    subgraph "External Services"
        Crawler["AI Crawler Service"]:::external
        Upstream["Upstream OpenAPI Sources"]:::external
    end

    %% Deployment Configuration
    subgraph "Deployment Config"
        Wrangler["wrangler.toml"]:::storage
        Package["package.json"]:::storage
        Lock["package-lock.json"]:::storage
        Types["globals.d.ts"]:::storage
    end

    %% Relationships
    HomePage -->|"HTTP GET"| SA
    SA -->|"HTTP Response"| HomePage

    SearchPage -->|"XHR /api/search"| AR
    OpenAPIPage -->|"XHR /api/openapi/:id"| AR
    ProviderPage -->|"XHR /api/providers/:id"| AR

    AR -->|"validate"| SV
    SV -->|"uses schemas"| Sch1
    SV -->|"uses schemas"| Sch2

    AR -->|"search call"| SI
    SI -->|"reads"| ProvidersJSON
    SI -->|"reads"| OpenAPIJSON
    SI -->|"reads"| Handmade
    SI -->|"optionally reads/writes"| KV

    SA -->|"serves static JSON"| ProvidersJSON
    SA -->|"serves static JSON"| OpenAPIJSON
    SA -->|"serves handmade JSON"| Handmade

    AR -->|"delegates logo"| Logo
    Logo -->|"loads"| ProvidersJSON

    AR -->|"schedule/fetch"| Crawler
    AR -->|"fetch live specs"| Upstream

    SA -->|"configures"| Wrangler
    AR -->|"configures"| Wrangler
    SV -->|"configures"| Wrangler

    SA -->|"package deps"| Package
    SA -->|"lock file"| Lock
    SA -->|"global types"| Types

    %% Responses back to UI
    AR -->|"JSON Response"| SearchPage
    AR -->|"JSON Response"| OpenAPIPage
    AR -->|"JSON Response"| ProviderPage

    %% Click Events
    click HomePage "https://github.com/janwilmake/openapisearch/blob/main/homepage.html"
    click SearchPage "https://github.com/janwilmake/openapisearch/blob/main/search.html"
    click OpenAPIPage "https://github.com/janwilmake/openapisearch/blob/main/openapi.html"
    click ProviderPage "https://github.com/janwilmake/openapisearch/blob/main/provider.html"
    click SA "https://github.com/janwilmake/openapisearch/blob/main/main.ts"
    click AR "https://github.com/janwilmake/openapisearch/blob/main/main.ts"
    click SV "https://github.com/janwilmake/openapisearch/blob/main/main.ts"
    click SI "https://github.com/janwilmake/openapisearch/blob/main/main.ts"
    click Logo "https://github.com/janwilmake/openapisearch/blob/main/logo.ts"
    click ProvidersJSON "https://github.com/janwilmake/openapisearch/blob/main/providers.json"
    click OpenAPIJSON "https://github.com/janwilmake/openapisearch/blob/main/openapi.json"
    click Handmade "https://github.com/janwilmake/openapisearch/tree/main/handmade/"
    click Sch1 "https://github.com/janwilmake/openapisearch/blob/main/provider.schema.json"
    click Sch2 "https://github.com/janwilmake/openapisearch/blob/main/providers.schema.json"
    click Wrangler "https://github.com/janwilmake/openapisearch/blob/main/wrangler.toml"
    click Package "https://github.com/janwilmake/openapisearch/blob/main/package.json"
    click Lock "https://github.com/janwilmake/openapisearch/blob/main/package-lock.json"
    click Types "https://github.com/janwilmake/openapisearch/blob/main/globals.d.ts"

    %% Styles
    classDef frontend fill:#D6E6FF,stroke:#0066CC
    classDef backend fill:#D5F5E3,stroke:#1E8449,stroke-width:2px
    classDef storage fill:#FDEBD0,stroke:#CA6F1E
    classDef external fill:#F4ECF7,stroke:#8E44AD
```
