# muze-nl/metro architecture

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

- Interactive diagram: https://gitdiagram.com/muze-nl/metro
- Repository: https://github.com/muze-nl/metro

## Overview

##### Project Type and Purpose
- This is an open-source JavaScript/TypeScript library (published on npm as @muze-nl/metro) that provides an HTTPS/Fetch client with a middleware pipeline (a Chain of Responsibility pattern) for both browser and Node environments.

##### File-Structure Analysis
- Top-level directories:
- src/ – ES module source files:
– api.mjs: exposes client() factory, HTTP verbs (get, post, etc.)
– browser.mjs: adapter for window.fetch in browsers
– metro.mjs: core orchestration of middleware + fetch
– everything.mjs: single entry bundling of all exports
– mw/: built-in middleware implementations (json, echo.mock, error.mock, thrower)
- dist/ – bundled distributables: browser.js (for CDN/UMD), everything.js
- test/ – TAP-based unit tests for each module
- docs/ – user docs, tutorials, API reference
- esbuild.mjs – build script using esbuild
- package.json & .terserrc – packaging, versioning, minification
- Patterns and choices:
- Middleware pipeline (ordered stack of functions)
- Immutable Request/Response wrappers with .with() clone API
- Separate entry points for Node vs. browser (adapter pattern)

##### README Insights
- Purpose: extend standard Fetch API calls with user-provided or built-in middleware
- Usage examples show: client() factory → .with(middleware) → .get/.post → Promise<wrapped Response>
- Core concepts: middleware signature async (req, next) ⇒ res

1. Application Code (user’s script importing Metro)
2. Metro Client Factory (src/api.mjs)
3. Middleware Pipeline (ordered list of middleware modules)
– Built-in (json, echo.mock, error.mock, thrower)
– User-supplied functions
4. Core Orchestrator (src/metro.mjs)
5. Environment Adapter
– Browser (browser.mjs using window.fetch)
– Node (fallback to global.fetch or node-fetch)
6. Network Layer (actual HTTP request over TLS)
7. Build & Distribution
– esbuild bundler (esbuild.mjs) → dist/browser.js / dist/everything.js
– NPM package & CDN (jsdelivr)
- App Code → calls client() → returns Client Instance
- Client Instance → invokes HTTP verb method (get/post) → creates immutable Request
- Request enters Middleware Pipeline:
Middleware₁ → Middleware₂ → … → Middlewareₙ → Core Orchestrator
- Core Orchestrator → calls environment adapter → fetch(Request) → Promise<Response>
- Response returns → flows back through middleware chain in reverse → final Response to App
c. Architectural Patterns and Principles:
- Chain of Responsibility / Pipeline for middleware
- Immutability: every mutation via .with() produces a new object
- Adapter pattern: abstract over browser vs. Node fetch implementations
- Modular bundling: separate source modules, then single-file bundles in dist/
d. Key Technologies and Libraries:
- ES Modules (src/*.mjs)
- Fetch API (native in browser, polyfillable in Node)
- esbuild for bundling/minification
- TAP tests (test/*.mjs)
- NPM publishing, UMD/ESM distribution (dist/)

## Diagram (Mermaid)

```mermaid
graph TD
    %% Source Entry Points
    subgraph "Source Entry Points"
        direction TB
        API["Metro Client Factory"]:::user
        Core["Core Orchestrator"]:::core
        BA["Browser Adapter"]:::core
        EE["Everything Entry"]:::user
    end

    Application["Application Code"]:::user
    Application -->|"calls client()"| API
    API -->|"returns Client Instance"| ClientInst["Client Instance"]:::user
    ClientInst -->|"client.get/post"| Req["Immutable Request"]:::user

    %% Middleware Pipeline
    Req --> PipeStart["<b>Enter Middleware Pipeline</b>"]:::user
    subgraph "Middleware Pipeline"
        direction TB
        MW1["JSON Middleware"]:::user
        MW2["Echo Mock Middleware"]:::user
        MW3["Error Mock Middleware"]:::user
        MW4["Thrower Middleware"]:::user
        UMW["User Middleware"]:::user
    end
    PipeStart --> MW1 --> MW2 --> MW3 --> MW4 --> UMW --> EndPipe["<b>Exit Middleware Pipeline</b>"]:::user

    %% Core and Adapters
    EndPipe --> Core
    subgraph "Environment Adapters"
        direction TB
        BA
        NA["Node Adapter"]:::core
    end
    Core -->|"fetch(req)"| BA --> FetchAPI["window.fetch / node-fetch"]:::external --> Network["Network Layer (HTTPS/TLS)"]:::external
    Network -->|"Response"| BA
    BA --> Core
    Core --> EndPipeBack["(Response)"]:::core

    %% Response flows back
    EndPipeBack --> MW4 --> MW3 --> MW2 --> MW1 --> ClientInst
    ClientInst --> Application

    %% Build & Distribution
    subgraph "Build & Distribution"
        direction TB
        ES["esbuild Build Script"]:::build
        B1["Browser UMD Bundle"]:::build
        B2["Everything Bundle"]:::build
        NPM["NPM/CDN Publish"]:::build
    end
    EE --> ES
    ES --> B1 --> NPM
    ES --> B2 --> NPM

    %% Click Events
    click API "https://github.com/muze-nl/metro/blob/main/src/api.mjs"
    click Core "https://github.com/muze-nl/metro/blob/main/src/metro.mjs"
    click BA "https://github.com/muze-nl/metro/blob/main/src/browser.mjs"
    click EE "https://github.com/muze-nl/metro/blob/main/src/everything.mjs"
    click MW1 "https://github.com/muze-nl/metro/blob/main/src/mw/json.mjs"
    click MW2 "https://github.com/muze-nl/metro/blob/main/src/mw/echo.mock.mjs"
    click MW3 "https://github.com/muze-nl/metro/blob/main/src/mw/error.mock.mjs"
    click MW4 "https://github.com/muze-nl/metro/blob/main/src/mw/thrower.mjs"
    click ES "https://github.com/muze-nl/metro/blob/main/esbuild.mjs"
    click B1 "https://github.com/muze-nl/metro/blob/main/dist/browser.js"
    click B2 "https://github.com/muze-nl/metro/blob/main/dist/everything.js"

    %% Styles
    classDef user fill:#D0E8FF,stroke:#0366d6,color:#0366d6;
    classDef core fill:#D0FFD0,stroke:#228B22,color:#228B22;
    classDef external fill:#E0E0E0,stroke:#555,color:#555;
    classDef build fill:#FFE0B2,stroke:#d2691e,color:#d2691e;
```
