# sidekik-live/sidekik-platform architecture

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

- Interactive diagram: https://gitdiagram.com/sidekik-live/sidekik-platform
- Repository: https://github.com/sidekik-live/sidekik-platform

## Overview

sidekik-platform is a shared TypeScript contract and runtime library for Sidekik services, not the services that perform capture, coaching, or tutoring. Its main workflow is that a service imports shared schemas and stream definitions to validate events, then uses the Redis Streams bus to publish or consume them; auth helpers and fail-closed PII redaction support integrations. The README also documents Supabase schema/seed data and fixture replay. Service behavior and several links to the database are not shown in the sampled source, so those relationships are omitted.

Main entry points: [`src/streams.ts`](https://github.com/sidekik-live/sidekik-platform/blob/main/src/streams.ts) (Stream registry), [`src/contracts/api.ts`](https://github.com/sidekik-live/sidekik-platform/blob/main/src/contracts/api.ts) (HTTP and WS schemas), [`src/contracts/commands.ts`](https://github.com/sidekik-live/sidekik-platform/blob/main/src/contracts/commands.ts) (Agent commands), [`src/bus.ts`](https://github.com/sidekik-live/sidekik-platform/blob/main/src/bus.ts) (Redis Streams bus)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_contracts["Shared contracts"]
  node_envelopes["Event envelopes<br/>[envelope.ts]"]
  node_lifecycle["Session lifecycle<br/>[lifecycle.ts]"]
  node_transcript["Transcript events<br/>[transcript.ts]"]
  node_screen["Screen events<br/>[screen.ts]"]
  node_commands["Agent commands<br/>[commands.ts]"]
  node_decisions["Decision specs<br/>[decisions.ts]"]
  node_workmap["Work Maps<br/>[workmap.ts]"]
  node_api["HTTP and WS schemas<br/>[api.ts]"]
  node_usage["Usage records<br/>[usage.ts]"]
end

subgraph group_runtime["Runtime utilities"]
  node_streams["Stream registry<br/>[streams.ts]"]
  node_bus["Redis Streams bus<br/>[bus.ts]"]
  node_auth["Auth helpers<br/>[auth.ts]"]
  node_redaction["PII redaction<br/>[presidio.ts]"]
end

subgraph group_data["Platform data"]
  node_database[("Supabase schema")]
end

subgraph group_devtools["Demo and replay"]
  node_demo["Demo Work Map data<br/>[demo.ts]"]
  node_seedrender["Seed SQL renderer<br/>[render.ts]"]
  node_replay["Fixture replay<br/>[replay.ts]"]
end

node_services(("Sidekik services"))
node_presidio["Presidio service"]
node_redis[("Redis Streams")]

node_services -->|"import contracts"| node_envelopes
node_services -->|"import stream names"| node_streams
node_services -->|"publish or consume"| node_bus
node_bus -->|"validates stream payloads"| node_streams
node_streams -->|"wraps payloads"| node_envelopes
node_streams -->|"maps event schema"| node_lifecycle
node_streams -->|"maps event schema"| node_transcript
node_streams -->|"maps event schema"| node_screen
node_streams -->|"maps event schema"| node_commands
node_streams -->|"maps event schema"| node_workmap
node_streams -->|"maps event schema"| node_usage
node_api -->|"uses schemas"| node_decisions
node_api -->|"uses schemas"| node_lifecycle
node_api -->|"uses schemas"| node_screen
node_api -->|"uses schemas"| node_transcript
node_commands -->|"uses phase schema"| node_lifecycle
node_commands -->|"uses mastery schema"| node_workmap
node_redaction -->|"analyzes and anonymizes"| node_presidio
node_replay -->|"publishes events"| node_bus
node_replay -->|"writes streams"| node_redis
node_seedrender -->|"renders demo data"| node_demo
node_seedrender -->|"generates seed SQL"| node_database

click node_envelopes "https://github.com/sidekik-live/sidekik-platform/blob/main/src/contracts/envelope.ts"
click node_lifecycle "https://github.com/sidekik-live/sidekik-platform/blob/main/src/contracts/lifecycle.ts"
click node_transcript "https://github.com/sidekik-live/sidekik-platform/blob/main/src/contracts/transcript.ts"
click node_screen "https://github.com/sidekik-live/sidekik-platform/blob/main/src/contracts/screen.ts"
click node_commands "https://github.com/sidekik-live/sidekik-platform/blob/main/src/contracts/commands.ts"
click node_decisions "https://github.com/sidekik-live/sidekik-platform/blob/main/src/contracts/decisions.ts"
click node_workmap "https://github.com/sidekik-live/sidekik-platform/blob/main/src/contracts/workmap.ts"
click node_api "https://github.com/sidekik-live/sidekik-platform/blob/main/src/contracts/api.ts"
click node_usage "https://github.com/sidekik-live/sidekik-platform/blob/main/src/contracts/usage.ts"
click node_streams "https://github.com/sidekik-live/sidekik-platform/blob/main/src/streams.ts"
click node_bus "https://github.com/sidekik-live/sidekik-platform/blob/main/src/bus.ts"
click node_auth "https://github.com/sidekik-live/sidekik-platform/blob/main/src/auth.ts"
click node_redaction "https://github.com/sidekik-live/sidekik-platform/blob/main/src/presidio.ts"
click node_database "https://github.com/sidekik-live/sidekik-platform/tree/main/supabase/migrations"
click node_demo "https://github.com/sidekik-live/sidekik-platform/blob/main/dev/seed/demo.ts"
click node_seedrender "https://github.com/sidekik-live/sidekik-platform/blob/main/dev/seed/render.ts"
click node_replay "https://github.com/sidekik-live/sidekik-platform/blob/main/dev/replay.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_envelopes,node_lifecycle,node_transcript,node_screen,node_commands,node_decisions,node_workmap,node_api,node_usage toneBlue
class node_streams,node_bus,node_auth,node_redaction,node_redis toneAmber
class node_database toneMint
class node_demo,node_seedrender,node_replay toneRose
class node_services,node_presidio toneIndigo
```

## Components

### Shared contracts

- [Event envelopes](https://github.com/sidekik-live/sidekik-platform/blob/main/src/contracts/envelope.ts): `src/contracts/envelope.ts`
- [Session lifecycle](https://github.com/sidekik-live/sidekik-platform/blob/main/src/contracts/lifecycle.ts): `src/contracts/lifecycle.ts`
- [Transcript events](https://github.com/sidekik-live/sidekik-platform/blob/main/src/contracts/transcript.ts): `src/contracts/transcript.ts`
- [Screen events](https://github.com/sidekik-live/sidekik-platform/blob/main/src/contracts/screen.ts): `src/contracts/screen.ts`
- [Agent commands](https://github.com/sidekik-live/sidekik-platform/blob/main/src/contracts/commands.ts): `src/contracts/commands.ts`
- [Decision specs](https://github.com/sidekik-live/sidekik-platform/blob/main/src/contracts/decisions.ts): `src/contracts/decisions.ts`
- [Work Maps](https://github.com/sidekik-live/sidekik-platform/blob/main/src/contracts/workmap.ts): `src/contracts/workmap.ts`
- [HTTP and WS schemas](https://github.com/sidekik-live/sidekik-platform/blob/main/src/contracts/api.ts): `src/contracts/api.ts`
- [Usage records](https://github.com/sidekik-live/sidekik-platform/blob/main/src/contracts/usage.ts): `src/contracts/usage.ts`

### Runtime utilities

- [Stream registry](https://github.com/sidekik-live/sidekik-platform/blob/main/src/streams.ts): `src/streams.ts`
- [Redis Streams bus](https://github.com/sidekik-live/sidekik-platform/blob/main/src/bus.ts): `src/bus.ts`
- [Auth helpers](https://github.com/sidekik-live/sidekik-platform/blob/main/src/auth.ts): `src/auth.ts`
- [PII redaction](https://github.com/sidekik-live/sidekik-platform/blob/main/src/presidio.ts): `src/presidio.ts`

### Platform data

- [Supabase schema](https://github.com/sidekik-live/sidekik-platform/tree/main/supabase/migrations): `supabase/migrations`

### Demo and replay

- [Demo Work Map data](https://github.com/sidekik-live/sidekik-platform/blob/main/dev/seed/demo.ts): `dev/seed/demo.ts`
- [Seed SQL renderer](https://github.com/sidekik-live/sidekik-platform/blob/main/dev/seed/render.ts): `dev/seed/render.ts`
- [Fixture replay](https://github.com/sidekik-live/sidekik-platform/blob/main/dev/replay.ts): `dev/replay.ts`

### Other components

- **Sidekik services**
- **Presidio service**
- **Redis Streams**

## Connections

- Sidekik services → Event envelopes: import contracts (evidence: `README.md`)
- Sidekik services → Stream registry: import stream names (evidence: `README.md`)
- Sidekik services → Redis Streams bus: publish or consume (evidence: `README.md`)
- Redis Streams bus → Stream registry: validates stream payloads (evidence: `src/bus.ts`)
- Stream registry → Event envelopes: wraps payloads (evidence: `src/streams.ts`)
- Stream registry → Session lifecycle: maps event schema (evidence: `src/streams.ts`)
- Stream registry → Transcript events: maps event schema (evidence: `src/streams.ts`)
- Stream registry → Screen events: maps event schema (evidence: `src/streams.ts`)
- Stream registry → Agent commands: maps event schema (evidence: `src/streams.ts`)
- Stream registry → Work Maps: maps event schema (evidence: `src/streams.ts`)
- Stream registry → Usage records: maps event schema (evidence: `src/streams.ts`)
- HTTP and WS schemas → Decision specs: uses schemas (evidence: `src/contracts/api.ts`)
- HTTP and WS schemas → Session lifecycle: uses schemas (evidence: `src/contracts/api.ts`)
- HTTP and WS schemas → Screen events: uses schemas (evidence: `src/contracts/api.ts`)
- HTTP and WS schemas → Transcript events: uses schemas (evidence: `src/contracts/api.ts`)
- Agent commands → Session lifecycle: uses phase schema (evidence: `src/contracts/commands.ts`)
- Agent commands → Work Maps: uses mastery schema (evidence: `src/contracts/commands.ts`)
- PII redaction → Presidio service: analyzes and anonymizes (evidence: `README.md`)
- Fixture replay → Redis Streams bus: publishes events (evidence: `dev/replay.ts`)
- Fixture replay → Redis Streams: writes streams (evidence: `dev/replay.ts`)
- Seed SQL renderer → Demo Work Map data: renders demo data (evidence: `dev/seed/render.ts`)
- Seed SQL renderer → Supabase schema: generates seed SQL (evidence: `README.md`)
