# devpath56/shipgate architecture

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

- Interactive diagram: https://gitdiagram.com/devpath56/shipgate
- Repository: https://github.com/devpath56/shipgate
- Video tour (about a minute): https://gitdiagram.com/devpath56/shipgate/video

## Overview

ShipGate is a release-governance application: users review a change, evaluate its findings against blocking policies, and submit, approve, or ship it through an enforced server-side gate. A blocked change is routed to its policy owner for a noted resolution, then can be re-evaluated and shipped. Transitions—including refusals—are recorded in a verifiable hash-chained ledger. The UI also exposes policy suggestions and deterministic explanations grounded in live application data. The findings feed is simulated; sampled source supports the web/API/engine flow, while some screen-to-endpoint details are documented rather than inspected directly.

Main entry points: [`web/src/App.tsx`](https://github.com/devpath56/shipgate/blob/main/web/src/App.tsx) (App shell), [`server/engine.ts`](https://github.com/devpath56/shipgate/blob/main/server/engine.ts) (Governance engine), [`web/src/api.ts`](https://github.com/devpath56/shipgate/blob/main/web/src/api.ts) (Typed API client), [`server/app.ts`](https://github.com/devpath56/shipgate/blob/main/server/app.ts) (Fastify API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web application"]
  node_app["App shell<br/>[App.tsx]"]
  node_dashboard["Change dashboard<br/>[Dashboard.tsx]"]
  node_detail["Change detail<br/>[ChangeDetail.tsx]"]
  node_policies["Policy screen<br/>[Policies.tsx]"]
  node_ledgerpage["Ledger screen<br/>[Ledger.tsx]"]
  node_legacy["Legacy view<br/>[Legacy.tsx]"]
  node_client["Typed API client<br/>[api.ts]"]
end

subgraph group_api["API and governance"]
  node_http["Fastify API<br/>[app.ts]"]
  node_engine["Governance engine<br/>[engine.ts]"]
  node_domain["Domain rules<br/>[domain.ts]"]
end

subgraph group_state["State and evidence"]
  node_seed["Demo seed data<br/>[seed.ts]"]
  node_memory["In-memory state<br/>[engine.ts]"]
  node_ledger["Hash-chained ledger<br/>[ledger.ts]"]
end

subgraph group_explain["Explanations"]
  node_ai["Deterministic reasoning<br/>[ai.ts]"]
end

node_roles(("Demo roles"))

node_roles -->|"select role"| node_app
node_app -->|"routes to"| node_dashboard
node_app -->|"routes to"| node_detail
node_app -->|"routes to"| node_policies
node_app -->|"routes to"| node_ledgerpage
node_app -->|"routes to"| node_legacy
node_dashboard -->|"fetches queue"| node_client
node_detail -->|"requests actions"| node_client
node_policies -->|"requests policies"| node_client
node_ledgerpage -->|"requests ledger"| node_client
node_legacy -->|"requests baseline"| node_client
node_client -->|"sends API requests"| node_http
node_http -->|"dispatches operations"| node_engine
node_engine -->|"applies rules"| node_domain
node_engine -->|"loads on reset"| node_seed
node_engine -->|"reads and updates"| node_memory
node_engine -->|"appends and verifies"| node_ledger
node_http -->|"requests explanations"| node_ai
node_ai -->|"reads live governance data"| node_engine

click node_app "https://github.com/devpath56/shipgate/blob/main/web/src/App.tsx"
click node_dashboard "https://github.com/devpath56/shipgate/blob/main/web/src/pages/Dashboard.tsx"
click node_detail "https://github.com/devpath56/shipgate/blob/main/web/src/pages/ChangeDetail.tsx"
click node_policies "https://github.com/devpath56/shipgate/blob/main/web/src/pages/Policies.tsx"
click node_ledgerpage "https://github.com/devpath56/shipgate/blob/main/web/src/pages/Ledger.tsx"
click node_legacy "https://github.com/devpath56/shipgate/blob/main/web/src/pages/Legacy.tsx"
click node_client "https://github.com/devpath56/shipgate/blob/main/web/src/api.ts"
click node_http "https://github.com/devpath56/shipgate/blob/main/server/app.ts"
click node_engine "https://github.com/devpath56/shipgate/blob/main/server/engine.ts"
click node_domain "https://github.com/devpath56/shipgate/blob/main/server/domain.ts"
click node_seed "https://github.com/devpath56/shipgate/blob/main/server/seed.ts"
click node_memory "https://github.com/devpath56/shipgate/blob/main/server/engine.ts"
click node_ledger "https://github.com/devpath56/shipgate/blob/main/server/ledger.ts"
click node_ai "https://github.com/devpath56/shipgate/blob/main/server/ai.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_dashboard,node_detail,node_policies,node_ledgerpage,node_legacy,node_client toneBlue
class node_http,node_engine,node_domain toneAmber
class node_seed,node_memory,node_ledger toneMint
class node_ai toneRose
class node_roles toneIndigo
```

## Components

### Web application

- [App shell](https://github.com/devpath56/shipgate/blob/main/web/src/App.tsx): `web/src/App.tsx`
- [Change dashboard](https://github.com/devpath56/shipgate/blob/main/web/src/pages/Dashboard.tsx): `web/src/pages/Dashboard.tsx`
- [Change detail](https://github.com/devpath56/shipgate/blob/main/web/src/pages/ChangeDetail.tsx): `web/src/pages/ChangeDetail.tsx`
- [Policy screen](https://github.com/devpath56/shipgate/blob/main/web/src/pages/Policies.tsx): `web/src/pages/Policies.tsx`
- [Ledger screen](https://github.com/devpath56/shipgate/blob/main/web/src/pages/Ledger.tsx): `web/src/pages/Ledger.tsx`
- [Legacy view](https://github.com/devpath56/shipgate/blob/main/web/src/pages/Legacy.tsx): `web/src/pages/Legacy.tsx`
- [Typed API client](https://github.com/devpath56/shipgate/blob/main/web/src/api.ts): `web/src/api.ts`

### API and governance

- [Fastify API](https://github.com/devpath56/shipgate/blob/main/server/app.ts): `server/app.ts`
- [Governance engine](https://github.com/devpath56/shipgate/blob/main/server/engine.ts): `server/engine.ts`
- [Domain rules](https://github.com/devpath56/shipgate/blob/main/server/domain.ts): `server/domain.ts`

### State and evidence

- [Demo seed data](https://github.com/devpath56/shipgate/blob/main/server/seed.ts): `server/seed.ts`
- [In-memory state](https://github.com/devpath56/shipgate/blob/main/server/engine.ts): `server/engine.ts`
- [Hash-chained ledger](https://github.com/devpath56/shipgate/blob/main/server/ledger.ts): `server/ledger.ts`

### Explanations

- [Deterministic reasoning](https://github.com/devpath56/shipgate/blob/main/server/ai.ts): `server/ai.ts`

### Other components

- **Demo roles**

## Connections

- Demo roles → App shell: select role
- App shell → Change dashboard: routes to
- App shell → Change detail: routes to
- App shell → Policy screen: routes to
- App shell → Ledger screen: routes to
- App shell → Legacy view: routes to
- Change dashboard → Typed API client: fetches queue
- Change detail → Typed API client: requests actions
- Policy screen → Typed API client: requests policies
- Ledger screen → Typed API client: requests ledger
- Legacy view → Typed API client: requests baseline
- Typed API client → Fastify API: sends API requests
- Fastify API → Governance engine: dispatches operations
- Governance engine → Domain rules: applies rules
- Governance engine → Demo seed data: loads on reset
- Governance engine → In-memory state: reads and updates
- Governance engine → Hash-chained ledger: appends and verifies
- Fastify API → Deterministic reasoning: requests explanations
- Deterministic reasoning → Governance engine: reads live governance data