# typicode/json-server architecture

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

- Interactive diagram: https://gitdiagram.com/typicode/json-server
- Repository: https://github.com/typicode/json-server

## Overview

JSON Server turns a JSON or JSON5 data file into a local REST API: the CLI loads and normalizes the file, creates the HTTP app, and serves requests. Routes delegate resource operations to a service that filters, sorts, paginates, embeds related records, and persists mutations. The CLI also watches the data file outside production. The README documents static serving and query capabilities; the graph reflects sampled calls and documented behavior, without assuming unsampled implementation details.

Main entry points: [`src/service.ts`](https://github.com/typicode/json-server/blob/main/src/service.ts) (Resource service), [`src/app.ts`](https://github.com/typicode/json-server/blob/main/src/app.ts) (HTTP app and routes), [`src/bin.ts`](https://github.com/typicode/json-server/blob/main/src/bin.ts) (CLI and watcher), [`src/adapters/normalized-adapter.ts`](https://github.com/typicode/json-server/blob/main/src/adapters/normalized-adapter.ts) (Data normalization)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Server runtime"]
  node_cli["CLI and watcher<br/>[bin.ts]"]
  node_index["Rendered index<br/>[index.html]"]
  node_public["Public static files"]
end

subgraph group_storage["Data loading and persistence"]
  node_dbfile[("JSON data file")]
  node_observer["Read/write observer<br/>[observer.ts]"]
  node_normalized["Data normalization"]
  node_ids["ID generation<br/>[random-id.ts]"]
end

subgraph group_api["REST and resource operations"]
  node_app["HTTP app and routes<br/>[app.ts]"]
  node_service["Resource service<br/>[service.ts]"]
end

subgraph group_query["Query processing"]
  node_parsewhere["Query parsing<br/>[parse-where.ts]"]
  node_operators["Where operators<br/>[where-operators.ts]"]
  node_matches["Filter matching<br/>[matches-where.ts]"]
  node_pagination["Pagination<br/>[paginate.ts]"]
end

node_user(("API client"))

node_user -->|"sends requests"| node_app
node_cli -->|"loads and watches"| node_dbfile
node_cli -->|"wraps adapter"| node_normalized
node_cli -->|"wraps adapter"| node_observer
node_observer -->|"delegates reads/writes"| node_normalized
node_normalized -->|"reads and writes"| node_dbfile
node_normalized -->|"generates missing IDs"| node_ids
node_cli -->|"creates and listens"| node_app
node_app -->|"dispatches resource operations"| node_service
node_app -->|"parses list filters"| node_parsewhere
node_parsewhere -->|"checks operators"| node_operators
node_service -->|"filters records"| node_matches
node_matches -->|"checks operators"| node_operators
node_service -->|"paginates results"| node_pagination
node_service -->|"generates record IDs"| node_ids
node_service -.->|"persists mutations"| node_dbfile
node_app -->|"serves static files"| node_public
node_app -->|"renders root page"| node_index
node_service -->|"embeds related resources"| node_service
node_service -->|"deletes dependents"| node_service

click node_cli "https://github.com/typicode/json-server/blob/main/src/bin.ts"
click node_app "https://github.com/typicode/json-server/blob/main/src/app.ts"
click node_index "https://github.com/typicode/json-server/blob/main/views/index.html"
click node_public "https://github.com/typicode/json-server/tree/main/public"
click node_observer "https://github.com/typicode/json-server/blob/main/src/adapters/observer.ts"
click node_normalized "https://github.com/typicode/json-server/blob/main/src/adapters/normalized-adapter.ts"
click node_service "https://github.com/typicode/json-server/blob/main/src/service.ts"
click node_parsewhere "https://github.com/typicode/json-server/blob/main/src/parse-where.ts"
click node_operators "https://github.com/typicode/json-server/blob/main/src/where-operators.ts"
click node_matches "https://github.com/typicode/json-server/blob/main/src/matches-where.ts"
click node_pagination "https://github.com/typicode/json-server/blob/main/src/paginate.ts"
click node_ids "https://github.com/typicode/json-server/blob/main/src/random-id.ts"

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_cli,node_index,node_public,node_user toneBlue
class node_dbfile,node_observer,node_normalized,node_ids toneAmber
class node_app,node_service toneMint
class node_parsewhere,node_operators,node_matches,node_pagination toneRose
```

## Components

### Server runtime

- [CLI and watcher](https://github.com/typicode/json-server/blob/main/src/bin.ts): `src/bin.ts`
- [Rendered index](https://github.com/typicode/json-server/blob/main/views/index.html): `views/index.html`
- [Public static files](https://github.com/typicode/json-server/tree/main/public): `public`

### Data loading and persistence

- **JSON data file**
- [Read/write observer](https://github.com/typicode/json-server/blob/main/src/adapters/observer.ts): `src/adapters/observer.ts`
- [Data normalization](https://github.com/typicode/json-server/blob/main/src/adapters/normalized-adapter.ts): `src/adapters/normalized-adapter.ts`
- [ID generation](https://github.com/typicode/json-server/blob/main/src/random-id.ts): `src/random-id.ts`

### REST and resource operations

- [HTTP app and routes](https://github.com/typicode/json-server/blob/main/src/app.ts): `src/app.ts`
- [Resource service](https://github.com/typicode/json-server/blob/main/src/service.ts): `src/service.ts`

### Query processing

- [Query parsing](https://github.com/typicode/json-server/blob/main/src/parse-where.ts): `src/parse-where.ts`
- [Where operators](https://github.com/typicode/json-server/blob/main/src/where-operators.ts): `src/where-operators.ts`
- [Filter matching](https://github.com/typicode/json-server/blob/main/src/matches-where.ts): `src/matches-where.ts`
- [Pagination](https://github.com/typicode/json-server/blob/main/src/paginate.ts): `src/paginate.ts`

### Other components

- **API client**

## Connections

- API client → HTTP app and routes: sends requests (evidence: `README.md`)
- CLI and watcher → JSON data file: loads and watches (evidence: `src/bin.ts`)
- CLI and watcher → Data normalization: wraps adapter (evidence: `src/bin.ts`)
- CLI and watcher → Read/write observer: wraps adapter (evidence: `src/bin.ts`)
- Read/write observer → Data normalization: delegates reads/writes (evidence: `src/adapters/observer.ts`)
- Data normalization → JSON data file: reads and writes
- Data normalization → ID generation: generates missing IDs (evidence: `src/adapters/normalized-adapter.ts`)
- CLI and watcher → HTTP app and routes: creates and listens (evidence: `src/bin.ts`)
- HTTP app and routes → Resource service: dispatches resource operations (evidence: `src/app.ts`)
- HTTP app and routes → Query parsing: parses list filters (evidence: `src/app.ts`)
- Query parsing → Where operators: checks operators (evidence: `src/parse-where.ts`)
- Resource service → Filter matching: filters records (evidence: `src/service.ts`)
- Filter matching → Where operators: checks operators (evidence: `src/matches-where.ts`)
- Resource service → Pagination: paginates results (evidence: `src/service.ts`)
- Resource service → ID generation: generates record IDs (evidence: `src/service.ts`)
- Resource service → JSON data file: persists mutations
- HTTP app and routes → Public static files: serves static files (evidence: `src/app.ts`)
- HTTP app and routes → Rendered index: renders root page (evidence: `src/app.ts`)
- Resource service → Resource service: embeds related resources (evidence: `README.md`)
- Resource service → Resource service: deletes dependents (evidence: `README.md`)
