# xeravax/pishock-discord-activity architecture

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

- Interactive diagram: https://gitdiagram.com/xeravax/pishock-discord-activity
- Repository: https://github.com/xeravax/pishock-discord-activity
- Video tour (about a minute): https://gitdiagram.com/xeravax/pishock-discord-activity/video

## Overview

PiShock Discord Activity is a React-based Discord Activity and Fastify API for consensual, multiplayer control of users’ linked PiShock devices. Users enter the Activity, link PiShock accounts, configure per-device limits and safety settings, then issue shock, vibrate, or beep commands; participants can share devices, with live updates and command logging. The server mediates control through PiShock APIs while persisting account/session and safety state. The map preserves documented sharing, announcements, and emergency-stop capabilities. Some route and client internals were not excerpted, so uncertain connections are omitted.

Main entry points: [`src/client/App.tsx`](https://github.com/xeravax/pishock-discord-activity/blob/develop/src/client/App.tsx) (Activity shell), [`src/server/routes/control.ts`](https://github.com/xeravax/pishock-discord-activity/blob/develop/src/server/routes/control.ts) (Control routes), [`src/server/index.ts`](https://github.com/xeravax/pishock-discord-activity/blob/develop/src/server/index.ts) (Fastify app), [`src/client/components/OfficialController.tsx`](https://github.com/xeravax/pishock-discord-activity/blob/develop/src/client/components/OfficialController.tsx) (Device controller)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Activity experience"]
  node_activity_ui["Activity shell<br/>[App.tsx]"]
  node_controller["Device controller"]
  node_device_cards["Device cards<br/>[ShockerCard.tsx]"]
  node_share_ui["Shares panel<br/>[SharesPanel.tsx]"]
  node_announcement_ui["Announcements"]
  node_version_ui["Version badge"]
end

subgraph group_identity["Identity and sharing"]
  node_auth_routes["Discord auth<br/>[auth.ts]"]
  node_link_ui["PiShock linking"]
  node_link_routes["Account linking<br/>[pishock-session.ts]"]
  node_auth_api["PiShock auth API<br/>[auth-api.ts]"]
  node_participants["Participant routes<br/>[participants.ts]"]
end

subgraph group_control["Safety and control"]
  node_control_routes["Control routes<br/>[control.ts]"]
  node_policy["Operate policy<br/>[operate-policy.ts]"]
  node_limits["Activity limits<br/>[limit-bands.ts]"]
  node_queue["Command queue<br/>[command-queue.ts]"]
  node_broker["PiShock broker<br/>[broker.ts]"]
  node_pishock_client["PiShock client<br/>[client.ts]"]
end

subgraph group_platform["Server platform"]
  node_session["Session and safety state<br/>[session.ts]"]
  node_database[("PostgreSQL<br/>[db.ts]")]
  node_realtime["Realtime hub<br/>[realtime.ts]"]
  node_server["Fastify app<br/>[index.ts]"]
end

node_discord_user(("Discord user"))
node_pishock["PiShock services"]

node_discord_user -->|"opens"| node_activity_ui
node_activity_ui -->|"renders"| node_controller
node_controller -->|"renders"| node_device_cards
node_activity_ui -->|"renders"| node_share_ui
node_controller -->|"renders"| node_announcement_ui
node_controller -->|"renders"| node_version_ui
node_activity_ui -.->|"authenticates via"| node_auth_routes
node_activity_ui -.->|"presents linking"| node_link_ui
node_link_ui -.->|"submits login"| node_link_routes
node_link_routes -->|"validates account"| node_auth_api
node_link_routes -->|"saves session"| node_session
node_activity_ui -->|"loads roster"| node_participants
node_controller -.->|"sends commands"| node_control_routes
node_control_routes -->|"checks policy"| node_policy
node_control_routes -->|"checks limits"| node_limits
node_control_routes -->|"dispatches commands"| node_queue
node_control_routes -->|"operates devices"| node_broker
node_broker -->|"calls API"| node_pishock_client
node_pishock_client -->|"requests device operations"| node_pishock
node_participants -->|"uses broker"| node_broker
node_participants -->|"checks limits"| node_limits
node_participants -->|"reads state"| node_session
node_session -->|"persists state"| node_database
node_server -->|"registers"| node_auth_routes
node_server -->|"registers"| node_link_routes
node_server -->|"registers"| node_control_routes
node_server -->|"registers"| node_participants
node_server -->|"attaches"| node_realtime
node_realtime -.->|"pushes live updates"| node_discord_user

click node_activity_ui "https://github.com/xeravax/pishock-discord-activity/blob/develop/src/client/App.tsx"
click node_controller "https://github.com/xeravax/pishock-discord-activity/blob/develop/src/client/components/OfficialController.tsx"
click node_device_cards "https://github.com/xeravax/pishock-discord-activity/blob/develop/src/client/components/ShockerCard.tsx"
click node_share_ui "https://github.com/xeravax/pishock-discord-activity/blob/develop/src/client/components/SharesPanel.tsx"
click node_announcement_ui "https://github.com/xeravax/pishock-discord-activity/blob/develop/src/client/components/AnnouncementBanner.tsx"
click node_version_ui "https://github.com/xeravax/pishock-discord-activity/blob/develop/src/client/components/AppVersionBadge.tsx"
click node_auth_routes "https://github.com/xeravax/pishock-discord-activity/blob/develop/src/server/routes/auth.ts"
click node_link_ui "https://github.com/xeravax/pishock-discord-activity/blob/develop/src/client/components/PiShockLinkingScreen.tsx"
click node_link_routes "https://github.com/xeravax/pishock-discord-activity/blob/develop/src/server/routes/pishock-session.ts"
click node_auth_api "https://github.com/xeravax/pishock-discord-activity/blob/develop/src/server/pishock/auth-api.ts"
click node_participants "https://github.com/xeravax/pishock-discord-activity/blob/develop/src/server/routes/participants.ts"
click node_control_routes "https://github.com/xeravax/pishock-discord-activity/blob/develop/src/server/routes/control.ts"
click node_policy "https://github.com/xeravax/pishock-discord-activity/blob/develop/src/server/operate-policy.ts"
click node_limits "https://github.com/xeravax/pishock-discord-activity/blob/develop/src/server/limit-bands.ts"
click node_queue "https://github.com/xeravax/pishock-discord-activity/blob/develop/src/server/pishock/command-queue.ts"
click node_broker "https://github.com/xeravax/pishock-discord-activity/blob/develop/src/server/pishock/broker.ts"
click node_pishock_client "https://github.com/xeravax/pishock-discord-activity/blob/develop/src/server/pishock/client.ts"
click node_session "https://github.com/xeravax/pishock-discord-activity/blob/develop/src/server/session.ts"
click node_database "https://github.com/xeravax/pishock-discord-activity/blob/develop/src/server/db.ts"
click node_realtime "https://github.com/xeravax/pishock-discord-activity/blob/develop/src/server/realtime.ts"
click node_server "https://github.com/xeravax/pishock-discord-activity/blob/develop/src/server/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_activity_ui,node_controller,node_device_cards,node_share_ui,node_announcement_ui,node_version_ui,node_discord_user toneBlue
class node_auth_routes,node_link_ui,node_link_routes,node_auth_api,node_participants toneAmber
class node_control_routes,node_policy,node_limits,node_queue,node_broker,node_pishock_client toneMint
class node_session,node_database,node_realtime,node_server toneRose
class node_pishock toneIndigo
```

## Components

### Activity experience

- [Activity shell](https://github.com/xeravax/pishock-discord-activity/blob/develop/src/client/App.tsx): `src/client/App.tsx`
- [Device controller](https://github.com/xeravax/pishock-discord-activity/blob/develop/src/client/components/OfficialController.tsx): `src/client/components/OfficialController.tsx`
- [Device cards](https://github.com/xeravax/pishock-discord-activity/blob/develop/src/client/components/ShockerCard.tsx): `src/client/components/ShockerCard.tsx`
- [Shares panel](https://github.com/xeravax/pishock-discord-activity/blob/develop/src/client/components/SharesPanel.tsx): `src/client/components/SharesPanel.tsx`
- [Announcements](https://github.com/xeravax/pishock-discord-activity/blob/develop/src/client/components/AnnouncementBanner.tsx): `src/client/components/AnnouncementBanner.tsx`
- [Version badge](https://github.com/xeravax/pishock-discord-activity/blob/develop/src/client/components/AppVersionBadge.tsx): `src/client/components/AppVersionBadge.tsx`

### Identity and sharing

- [Discord auth](https://github.com/xeravax/pishock-discord-activity/blob/develop/src/server/routes/auth.ts): `src/server/routes/auth.ts`
- [PiShock linking](https://github.com/xeravax/pishock-discord-activity/blob/develop/src/client/components/PiShockLinkingScreen.tsx): `src/client/components/PiShockLinkingScreen.tsx`
- [Account linking](https://github.com/xeravax/pishock-discord-activity/blob/develop/src/server/routes/pishock-session.ts): `src/server/routes/pishock-session.ts`
- [PiShock auth API](https://github.com/xeravax/pishock-discord-activity/blob/develop/src/server/pishock/auth-api.ts): `src/server/pishock/auth-api.ts`
- [Participant routes](https://github.com/xeravax/pishock-discord-activity/blob/develop/src/server/routes/participants.ts): `src/server/routes/participants.ts`

### Safety and control

- [Control routes](https://github.com/xeravax/pishock-discord-activity/blob/develop/src/server/routes/control.ts): `src/server/routes/control.ts`
- [Operate policy](https://github.com/xeravax/pishock-discord-activity/blob/develop/src/server/operate-policy.ts): `src/server/operate-policy.ts`
- [Activity limits](https://github.com/xeravax/pishock-discord-activity/blob/develop/src/server/limit-bands.ts): `src/server/limit-bands.ts`
- [Command queue](https://github.com/xeravax/pishock-discord-activity/blob/develop/src/server/pishock/command-queue.ts): `src/server/pishock/command-queue.ts`
- [PiShock broker](https://github.com/xeravax/pishock-discord-activity/blob/develop/src/server/pishock/broker.ts): `src/server/pishock/broker.ts`
- [PiShock client](https://github.com/xeravax/pishock-discord-activity/blob/develop/src/server/pishock/client.ts): `src/server/pishock/client.ts`

### Server platform

- [Session and safety state](https://github.com/xeravax/pishock-discord-activity/blob/develop/src/server/session.ts): `src/server/session.ts`
- [PostgreSQL](https://github.com/xeravax/pishock-discord-activity/blob/develop/src/server/db.ts): `src/server/db.ts`
- [Realtime hub](https://github.com/xeravax/pishock-discord-activity/blob/develop/src/server/realtime.ts): `src/server/realtime.ts`
- [Fastify app](https://github.com/xeravax/pishock-discord-activity/blob/develop/src/server/index.ts): `src/server/index.ts`

### Other components

- **Discord user**
- **PiShock services**

## Connections

- Discord user → Activity shell: opens (evidence: `README.md`)
- Activity shell → Device controller: renders (evidence: `src/client/App.tsx`)
- Device controller → Device cards: renders (evidence: `src/client/components/OfficialController.tsx`)
- Activity shell → Shares panel: renders (evidence: `src/client/App.tsx`)
- Device controller → Announcements: renders (evidence: `src/client/components/OfficialController.tsx`)
- Device controller → Version badge: renders (evidence: `src/client/components/OfficialController.tsx`)
- Activity shell → Discord auth: authenticates via (evidence: `README.md`)
- Activity shell → PiShock linking: presents linking (evidence: `README.md`)
- PiShock linking → Account linking: submits login (evidence: `README.md`)
- Account linking → PiShock auth API: validates account (evidence: `src/server/routes/pishock-session.ts`)
- Account linking → Session and safety state: saves session (evidence: `src/server/routes/pishock-session.ts`)
- Activity shell → Participant routes: loads roster (evidence: `src/client/App.tsx`)
- Device controller → Control routes: sends commands (evidence: `README.md`)
- Control routes → Operate policy: checks policy (evidence: `src/server/routes/control.ts`)
- Control routes → Activity limits: checks limits (evidence: `src/server/routes/control.ts`)
- Control routes → Command queue: dispatches commands (evidence: `src/server/routes/control.ts`)
- Control routes → PiShock broker: operates devices (evidence: `src/server/routes/control.ts`)
- PiShock broker → PiShock client: calls API (evidence: `src/server/pishock/broker.ts`)
- PiShock client → PiShock services: requests device operations (evidence: `README.md`)
- Participant routes → PiShock broker: uses broker (evidence: `src/server/routes/participants.ts`)
- Participant routes → Activity limits: checks limits (evidence: `src/server/routes/participants.ts`)
- Participant routes → Session and safety state: reads state (evidence: `src/server/routes/participants.ts`)
- Session and safety state → PostgreSQL: persists state (evidence: `src/server/session.ts`)
- Fastify app → Discord auth: registers (evidence: `src/server/index.ts`)
- Fastify app → Account linking: registers (evidence: `src/server/index.ts`)
- Fastify app → Control routes: registers (evidence: `src/server/index.ts`)
- Fastify app → Participant routes: registers (evidence: `src/server/index.ts`)
- Fastify app → Realtime hub: attaches (evidence: `src/server/index.ts`)
- Realtime hub → Discord user: pushes live updates (evidence: `README.md`)
