# paoloprandonitechnology/synthetic-substance-engine architecture

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

- Interactive diagram: https://gitdiagram.com/paoloprandonitechnology/synthetic-substance-engine
- Repository: https://github.com/paoloprandonitechnology/synthetic-substance-engine

## Overview

Synthetic Substance Engine is an OpenAI-compatible proxy that applies time- and dose-dependent profile effects to chat requests before forwarding them to a configured model provider. The main workflow is client request → profile/session resolution → effect calculation and request distortion → upstream response, with response headers reporting dose and effect phase. Separate API branches support substance editing, playground, model discovery, and trip reports. The README also documents a Cloudflare Worker variant with visitor-specific D1 catalog storage; its internal routing is not mapped in detail because the Worker source was not excerpted.

Main entry points: [`src/server/routes/chat-completions.ts`](https://github.com/paoloprandonitechnology/synthetic-substance-engine/blob/main/src/server/routes/chat-completions.ts) (Chat Completions), [`src/server/app.ts`](https://github.com/paoloprandonitechnology/synthetic-substance-engine/blob/main/src/server/app.ts) (Fastify App), [`src/server/routes/reports.ts`](https://github.com/paoloprandonitechnology/synthetic-substance-engine/blob/main/src/server/routes/reports.ts) (Trip Reports API), [`src/engine/registry.ts`](https://github.com/paoloprandonitechnology/synthetic-substance-engine/blob/main/src/engine/registry.ts) (Profile Registry)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Proxy API"]
  node_app["Fastify App<br/>[app.ts]"]
  node_chat["Chat Completions"]
  node_models["Model Listing<br/>[models.ts]"]
  node_catalog_routes["Substance API<br/>[substances.ts]"]
  node_playground["Playground<br/>[playground.ts]"]
  node_reports_route["Trip Reports API<br/>[reports.ts]"]
end

subgraph group_engine["Substance Engine"]
  node_registry["Profile Registry<br/>[registry.ts]"]
  node_profile["Profile Parser<br/>[substance.ts]"]
  node_profiles["Substance Profiles"]
  node_catalog_api["Catalog Operations<br/>[catalog-api.ts]"]
  node_sessions["Dose Sessions<br/>[session.ts]"]
  node_metabolism["Effect Curve<br/>[metabolism.ts]"]
  node_trip_report["Report Builder<br/>[trip-report.ts]"]
end

subgraph group_effects["Request Effects"]
  node_params["Sampling Parameters<br/>[params.ts]"]
  node_context["Context Distortion<br/>[context.ts]"]
  node_logit["Logit Distortion<br/>[logit.ts]"]
  node_streaming["Stream Jitter<br/>[streaming.ts]"]
end

subgraph group_integrations["Providers and Runtime"]
  node_provider_config["Provider Config<br/>[config.ts]"]
  node_provider_adapter["Provider Adapter"]
  node_upstream{{"Model Provider"}}
  node_worker["Worker Runtime<br/>[index.ts]"]
  node_d1[("Visitor Catalog")]
end

node_client(("OpenAI Client"))

node_client -->|"sends requests"| node_app
node_app -->|"registers route"| node_chat
node_app -->|"registers route"| node_models
node_app -->|"registers route"| node_catalog_routes
node_app -->|"registers route"| node_playground
node_app -->|"registers route"| node_reports_route
node_registry -->|"loads YAML"| node_profiles
node_registry -->|"parses profiles"| node_profile
node_catalog_routes -->|"uses operations"| node_catalog_api
node_chat -->|"looks up profile"| node_registry
node_chat -->|"resolves elapsed time"| node_sessions
node_chat -->|"computes factors"| node_metabolism
node_chat -->|"applies parameters"| node_params
node_chat -->|"rewrites context"| node_context
node_chat -->|"applies token bias"| node_logit
node_chat -->|"delays chunks"| node_streaming
node_chat -->|"uses effect phase"| node_trip_report
node_reports_route -->|"reads session"| node_sessions
node_reports_route -->|"builds report"| node_trip_report
node_models -->|"lists models"| node_provider_config
node_chat -->|"resolves model"| node_provider_config
node_chat -->|"creates client"| node_provider_adapter
node_provider_adapter -->|"forwards request"| node_upstream
node_worker -->|"stores visitor catalog"| node_d1
node_worker -->|"bundles profiles"| node_profiles

click node_app "https://github.com/paoloprandonitechnology/synthetic-substance-engine/blob/main/src/server/app.ts"
click node_chat "https://github.com/paoloprandonitechnology/synthetic-substance-engine/blob/main/src/server/routes/chat-completions.ts"
click node_models "https://github.com/paoloprandonitechnology/synthetic-substance-engine/blob/main/src/server/routes/models.ts"
click node_catalog_routes "https://github.com/paoloprandonitechnology/synthetic-substance-engine/blob/main/src/server/routes/substances.ts"
click node_playground "https://github.com/paoloprandonitechnology/synthetic-substance-engine/blob/main/src/server/routes/playground.ts"
click node_reports_route "https://github.com/paoloprandonitechnology/synthetic-substance-engine/blob/main/src/server/routes/reports.ts"
click node_registry "https://github.com/paoloprandonitechnology/synthetic-substance-engine/blob/main/src/engine/registry.ts"
click node_profile "https://github.com/paoloprandonitechnology/synthetic-substance-engine/blob/main/src/engine/substance.ts"
click node_profiles "https://github.com/paoloprandonitechnology/synthetic-substance-engine/tree/main/config/substances"
click node_catalog_api "https://github.com/paoloprandonitechnology/synthetic-substance-engine/blob/main/src/engine/catalog-api.ts"
click node_sessions "https://github.com/paoloprandonitechnology/synthetic-substance-engine/blob/main/src/engine/session.ts"
click node_metabolism "https://github.com/paoloprandonitechnology/synthetic-substance-engine/blob/main/src/engine/metabolism.ts"
click node_trip_report "https://github.com/paoloprandonitechnology/synthetic-substance-engine/blob/main/src/telemetry/trip-report.ts"
click node_params "https://github.com/paoloprandonitechnology/synthetic-substance-engine/blob/main/src/distorters/params.ts"
click node_context "https://github.com/paoloprandonitechnology/synthetic-substance-engine/blob/main/src/distorters/context.ts"
click node_logit "https://github.com/paoloprandonitechnology/synthetic-substance-engine/blob/main/src/distorters/logit.ts"
click node_streaming "https://github.com/paoloprandonitechnology/synthetic-substance-engine/blob/main/src/distorters/streaming.ts"
click node_provider_config "https://github.com/paoloprandonitechnology/synthetic-substance-engine/blob/main/src/providers/config.ts"
click node_provider_adapter "https://github.com/paoloprandonitechnology/synthetic-substance-engine/blob/main/src/providers/openai-compatible.ts"
click node_worker "https://github.com/paoloprandonitechnology/synthetic-substance-engine/blob/main/src/worker/index.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_app,node_chat,node_models,node_catalog_routes,node_playground,node_reports_route,node_client toneBlue
class node_registry,node_profile,node_profiles,node_catalog_api,node_sessions,node_metabolism,node_trip_report toneAmber
class node_params,node_context,node_logit,node_streaming toneMint
class node_provider_config,node_provider_adapter,node_upstream,node_worker,node_d1 toneRose
```

## Components

### Proxy API

- [Fastify App](https://github.com/paoloprandonitechnology/synthetic-substance-engine/blob/main/src/server/app.ts): `src/server/app.ts`
- [Chat Completions](https://github.com/paoloprandonitechnology/synthetic-substance-engine/blob/main/src/server/routes/chat-completions.ts): `src/server/routes/chat-completions.ts`
- [Model Listing](https://github.com/paoloprandonitechnology/synthetic-substance-engine/blob/main/src/server/routes/models.ts): `src/server/routes/models.ts`
- [Substance API](https://github.com/paoloprandonitechnology/synthetic-substance-engine/blob/main/src/server/routes/substances.ts): `src/server/routes/substances.ts`
- [Playground](https://github.com/paoloprandonitechnology/synthetic-substance-engine/blob/main/src/server/routes/playground.ts): `src/server/routes/playground.ts`
- [Trip Reports API](https://github.com/paoloprandonitechnology/synthetic-substance-engine/blob/main/src/server/routes/reports.ts): `src/server/routes/reports.ts`

### Substance Engine

- [Profile Registry](https://github.com/paoloprandonitechnology/synthetic-substance-engine/blob/main/src/engine/registry.ts): `src/engine/registry.ts`
- [Profile Parser](https://github.com/paoloprandonitechnology/synthetic-substance-engine/blob/main/src/engine/substance.ts): `src/engine/substance.ts`
- [Substance Profiles](https://github.com/paoloprandonitechnology/synthetic-substance-engine/tree/main/config/substances): `config/substances`
- [Catalog Operations](https://github.com/paoloprandonitechnology/synthetic-substance-engine/blob/main/src/engine/catalog-api.ts): `src/engine/catalog-api.ts`
- [Dose Sessions](https://github.com/paoloprandonitechnology/synthetic-substance-engine/blob/main/src/engine/session.ts): `src/engine/session.ts`
- [Effect Curve](https://github.com/paoloprandonitechnology/synthetic-substance-engine/blob/main/src/engine/metabolism.ts): `src/engine/metabolism.ts`
- [Report Builder](https://github.com/paoloprandonitechnology/synthetic-substance-engine/blob/main/src/telemetry/trip-report.ts): `src/telemetry/trip-report.ts`

### Request Effects

- [Sampling Parameters](https://github.com/paoloprandonitechnology/synthetic-substance-engine/blob/main/src/distorters/params.ts): `src/distorters/params.ts`
- [Context Distortion](https://github.com/paoloprandonitechnology/synthetic-substance-engine/blob/main/src/distorters/context.ts): `src/distorters/context.ts`
- [Logit Distortion](https://github.com/paoloprandonitechnology/synthetic-substance-engine/blob/main/src/distorters/logit.ts): `src/distorters/logit.ts`
- [Stream Jitter](https://github.com/paoloprandonitechnology/synthetic-substance-engine/blob/main/src/distorters/streaming.ts): `src/distorters/streaming.ts`

### Providers and Runtime

- [Provider Config](https://github.com/paoloprandonitechnology/synthetic-substance-engine/blob/main/src/providers/config.ts): `src/providers/config.ts`
- [Provider Adapter](https://github.com/paoloprandonitechnology/synthetic-substance-engine/blob/main/src/providers/openai-compatible.ts): `src/providers/openai-compatible.ts`
- **Model Provider**
- [Worker Runtime](https://github.com/paoloprandonitechnology/synthetic-substance-engine/blob/main/src/worker/index.ts): `src/worker/index.ts`
- **Visitor Catalog**

### Other components

- **OpenAI Client**

## Connections

- OpenAI Client → Fastify App: sends requests (evidence: `README.md`)
- Fastify App → Chat Completions: registers route (evidence: `src/server/app.ts`)
- Fastify App → Model Listing: registers route (evidence: `src/server/app.ts`)
- Fastify App → Substance API: registers route (evidence: `src/server/app.ts`)
- Fastify App → Playground: registers route (evidence: `src/server/app.ts`)
- Fastify App → Trip Reports API: registers route (evidence: `src/server/app.ts`)
- Profile Registry → Substance Profiles: loads YAML (evidence: `src/engine/registry.ts`)
- Profile Registry → Profile Parser: parses profiles (evidence: `src/engine/registry.ts`)
- Substance API → Catalog Operations: uses operations (evidence: `src/server/routes/substances.ts`)
- Chat Completions → Profile Registry: looks up profile (evidence: `src/server/routes/chat-completions.ts`)
- Chat Completions → Dose Sessions: resolves elapsed time (evidence: `src/server/routes/chat-completions.ts`)
- Chat Completions → Effect Curve: computes factors (evidence: `src/server/routes/chat-completions.ts`)
- Chat Completions → Sampling Parameters: applies parameters (evidence: `src/server/routes/chat-completions.ts`)
- Chat Completions → Context Distortion: rewrites context (evidence: `src/server/routes/chat-completions.ts`)
- Chat Completions → Logit Distortion: applies token bias (evidence: `src/server/routes/chat-completions.ts`)
- Chat Completions → Stream Jitter: delays chunks (evidence: `src/server/routes/chat-completions.ts`)
- Chat Completions → Report Builder: uses effect phase (evidence: `src/server/routes/chat-completions.ts`)
- Trip Reports API → Dose Sessions: reads session (evidence: `src/server/routes/reports.ts`)
- Trip Reports API → Report Builder: builds report (evidence: `src/server/routes/reports.ts`)
- Model Listing → Provider Config: lists models (evidence: `src/server/routes/models.ts`)
- Chat Completions → Provider Config: resolves model (evidence: `src/server/routes/chat-completions.ts`)
- Chat Completions → Provider Adapter: creates client (evidence: `src/server/routes/chat-completions.ts`)
- Provider Adapter → Model Provider: forwards request (evidence: `README.md`)
- Worker Runtime → Visitor Catalog: stores visitor catalog (evidence: `README.md`)
- Worker Runtime → Substance Profiles: bundles profiles (evidence: `README.md`)