# ipfs/service-worker-gateway architecture

> Architecture diagram of the GitHub repository ipfs/service-worker-gateway, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-08). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ipfs/service-worker-gateway
- Repository: https://github.com/ipfs/service-worker-gateway

## Overview

##### Project type and purpose
- This is a full-stack web application whose core feature is an in-browser IPFS Gateway implemented as a Service Worker.
- The frontend is a React+TypeScript SPA; the “backend” is a lightweight static‐file server (Node/TypeScript or Go) that also provides a reverse-proxy for subdomain‐style IPFS path routing.
- The Service Worker itself contains an embedded Helia IPFS node and uses the verified-fetch library to retrieve, hash-verify, and reassemble blocks from the IPFS network or configured HTTP gateways.

##### File structure
- Top-level scripts & config:
- build.js, serve.ts → Node scripts to bundle and serve the frontend.
- main.go → Go HTTP server for static assets + reverse proxy (subdomain routing / IPNS).
- package.json, tsconfig.json, babel.config.json → build & toolchain config.
- public/ → static HTML, SW manifests, redirect rules.
- src/
- app.tsx, components/, context/, pages/ → React SPA + UI for SW config.
- sw.ts, ipfs-sw-first-hit.ts, service-worker-utils.ts → Service Worker entrypoints & utilities.
- lib/ → helper modules (block fetching, CID verification, routing logic, local storage, SW messaging).
- tests
- test-e2e/ → Playwright E2E suites that spin up the server, register the SW, and exercise IPFS fetch flows.
- test/ → unit tests for utility functions.
- .github/workflows → CI/CD build, test, and deploy pipelines.

##### README for additional insights
- The README explicitly describes:
- Helia + verified-fetch inside a Service Worker.
- Goals: shift block retrieval + hash verification to the client, reduce backend load.
- How the reverse proxy enables subdomain gateway URLs.
- CI/CD workflows to build TS code, compile Go, run tests, and deploy to staging/production.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Frontend Layer
    subgraph "Frontend: Browser"
        direction TB
        IndexHTML["public/index.html"]:::frontend
        ReactApp["React SPA (src/app.tsx)"]:::frontend
        SWRegister["SW Registration (src/ipfs-sw-first-hit.ts)"]:::frontend
    end

    %% Service Worker Layer
    subgraph "Service Worker"
        direction TB
        SWCore["SW Core (src/sw.ts)"]:::sw
        Utils["SW Utils (src/service-worker-utils.ts)"]:::sw
        Helia["Helia IPFS Node"]:::sw
        VF["Verified-Fetch (src/lib/get-verified-fetch.ts)"]:::sw
        Routing["Routing & Gateway Logic"]:::sw
        ConfigDB["Config & Storage (src/lib/config-db.ts)"]:::sw
    end

    %% Backend Layer
    subgraph "Backend: Static Server / Reverse Proxy"
        direction TB
        NodeServe["Node Server (serve.ts / build.js)"]:::backend
        GoServer["Go Server (main.go)"]:::backend
        PublicAssets["Public Assets (public/)"]:::backend
    end

    %% External Systems
    subgraph "External Systems"
        direction TB
        IPFSP2P["IPFS P2P Network"]:::external
        HTTPGW["HTTP Gateways"]:::external
        CI["CI/CD Pipeline (.github/workflows/)"]:::external
    end

    %% Data Flows
    ReactApp -->|"register SW"| SWRegister
    ReactApp -->|"GET /"| NodeServe
    NodeServe -->|"serves index.html & bundles"| IndexHTML
    GoServer -->|"serves assets & proxy"| PublicAssets
    NodeServe --> PublicAssets
    SWRegister -->|"activates"| SWCore
    SWCore --> VF
    VF --> Helia
    Helia --> IPFSP2P
    SWCore --> HTTPGW
    SWCore -->|"respond with content"| ReactApp
    ReactApp <-->|"postMessage: updateConfig"| SWCore
    NodeServe -->|"subdomain proxy requests"| GoServer
    CI --> ReactApp
    CI --> SWCore
    CI --> NodeServe
    CI --> GoServer

    %% Click Events
    click ReactApp "https://github.com/ipfs/service-worker-gateway/blob/main/src/app.tsx"
    click SWRegister "https://github.com/ipfs/service-worker-gateway/blob/main/src/ipfs-sw-first-hit.ts"
    click IndexHTML "https://github.com/ipfs/service-worker-gateway/blob/main/public/index.html"
    click SWCore "https://github.com/ipfs/service-worker-gateway/blob/main/src/sw.ts"
    click Utils "https://github.com/ipfs/service-worker-gateway/blob/main/src/service-worker-utils.ts"
    click VF "https://github.com/ipfs/service-worker-gateway/blob/main/src/lib/get-verified-fetch.ts"
    click ConfigDB "https://github.com/ipfs/service-worker-gateway/blob/main/src/lib/config-db.ts"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#0366d6,color:#000
    classDef sw fill:#FFECD0,stroke:#D9822B,color:#000
    classDef backend fill:#D0FFD6,stroke:#237E2E,color:#000
    classDef external fill:#EDEDED,stroke:#888888,color:#000
```
