# omaraziz99/stooges architecture

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

- Interactive diagram: https://gitdiagram.com/omaraziz99/stooges
- Repository: https://github.com/omaraziz99/stooges

## Overview

Stooges combines a Nostr-based team chat web app and relay with a separate KPI agent that produces AI-drafted, evidence-linked reviews. The main user path is sign-in, connect to the relay, browse or post in channels and threads, then open a KPI report or a person-specific review. Groups reflect those product domains and the frontend layers. Backend source excerpts were not provided, so backend links below rely on README statements; other unverified implementation links are omitted.

Main entry points: [`fe/src/App.tsx`](https://github.com/omaraziz99/stooges/blob/main/fe/src/App.tsx) (App workspace), [`fe/src/components/KpiDashboard.tsx`](https://github.com/omaraziz99/stooges/blob/main/fe/src/components/KpiDashboard.tsx) (KPI dashboard), [`fe/src/components/Composer.tsx`](https://github.com/omaraziz99/stooges/blob/main/fe/src/components/Composer.tsx) (Message composer), [`fe/src/components/ChannelView.tsx`](https://github.com/omaraziz99/stooges/blob/main/fe/src/components/ChannelView.tsx) (Channel view)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web app"]
  node_app["App workspace<br/>[App.tsx]"]
  node_login["Sign-in<br/>[Login.tsx]"]
  node_auth["Account auth<br/>[auth.ts]"]
  node_relaystate["Relay state<br/>[relay.tsx]"]
  node_relayclient["Relay client<br/>[relay.ts]"]
end

subgraph group_chat["Chat experience"]
  node_channelview["Channel view<br/>[ChannelView.tsx]"]
  node_composer["Message composer<br/>[Composer.tsx]"]
  node_threads["Threads<br/>[ThreadPanel.tsx]"]
  node_messages["Message list<br/>[MessageList.tsx]"]
  node_sidebar["Workspace sidebar<br/>[Sidebar.tsx]"]
  node_chatmodel["Chat events<br/>[chat.ts]"]
  node_fileuploads["File attachments<br/>[files.ts]"]
end

subgraph group_relay["Relay and accounts"]
  node_relayserver["Chat relay<br/>[main.go]"]
  node_relaylogic["Relay service<br/>[relay.go]"]
  node_policy["Relay policy<br/>[policy.go]"]
  node_accounts["Account service<br/>[accounts.go]"]
  node_store[("SQLite store<br/>[store.go]")]
end

subgraph group_insights["KPI insights"]
  node_kpiagent["KPI agent<br/>[main.go]"]
  node_kpipipeline["Evidence and report generation"]
  node_framework["KPI framework<br/>[framework.go]"]
  node_kpidashboard["KPI dashboard<br/>[KpiDashboard.tsx]"]
  node_kpireview["Person review<br/>[KpiReviewPanel.tsx]"]
  node_kpimodel["Report parsing and commands<br/>[kpi.ts]"]
  node_kpiparts["Evidence and review views<br/>[KpiParts.tsx]"]
end

node_member(("Team member"))

node_member -->|"signs in"| node_login
node_login -->|"authenticates"| node_auth
node_app -->|"shows signed out"| node_login
node_app -->|"provides session"| node_relaystate
node_relaystate -->|"connects"| node_relayclient
node_member -->|"uses"| node_app
node_app -->|"renders"| node_channelview
node_app -->|"renders"| node_sidebar
node_channelview -->|"renders"| node_composer
node_channelview -->|"renders"| node_messages
node_app -->|"opens"| node_threads
node_composer -->|"uploads"| node_fileuploads
node_composer -->|"publishes messages"| node_chatmodel
node_chatmodel -->|"publishes events"| node_relayclient
node_relayclient -->|"connects"| node_relayserver
node_relayserver -->|"starts"| node_relaylogic
node_relaylogic -.->|"persists chat data"| node_store
node_relaylogic -.->|"enforces policy"| node_policy
node_auth -->|"calls account API"| node_accounts
node_accounts -.->|"stores accounts"| node_store
node_member -->|"sets channel and consent"| node_sidebar
node_member -->|"posts chat"| node_composer
node_member -->|"views insights"| node_kpidashboard
node_app -->|"renders"| node_kpidashboard
node_app -->|"opens KPI command"| node_kpireview
node_kpidashboard -->|"uses report model"| node_kpimodel
node_kpireview -->|"uses report model"| node_kpimodel
node_kpidashboard -->|"renders evidence"| node_kpiparts
node_kpireview -->|"renders evidence"| node_kpiparts
node_kpiagent -->|"reads channels and publishes reports"| node_relayserver
node_kpiagent -->|"generates reports"| node_kpipipeline
node_kpipipeline -->|"assesses against"| node_framework
node_kpipipeline -->|"report appears live"| node_kpidashboard

click node_app "https://github.com/omaraziz99/stooges/blob/main/fe/src/App.tsx"
click node_login "https://github.com/omaraziz99/stooges/blob/main/fe/src/components/Login.tsx"
click node_auth "https://github.com/omaraziz99/stooges/blob/main/fe/src/lib/auth.ts"
click node_relaystate "https://github.com/omaraziz99/stooges/blob/main/fe/src/state/relay.tsx"
click node_channelview "https://github.com/omaraziz99/stooges/blob/main/fe/src/components/ChannelView.tsx"
click node_composer "https://github.com/omaraziz99/stooges/blob/main/fe/src/components/Composer.tsx"
click node_threads "https://github.com/omaraziz99/stooges/blob/main/fe/src/components/ThreadPanel.tsx"
click node_messages "https://github.com/omaraziz99/stooges/blob/main/fe/src/components/MessageList.tsx"
click node_sidebar "https://github.com/omaraziz99/stooges/blob/main/fe/src/components/Sidebar.tsx"
click node_chatmodel "https://github.com/omaraziz99/stooges/blob/main/fe/src/lib/chat.ts"
click node_fileuploads "https://github.com/omaraziz99/stooges/blob/main/fe/src/lib/files.ts"
click node_relayclient "https://github.com/omaraziz99/stooges/blob/main/fe/src/lib/relay.ts"
click node_relayserver "https://github.com/omaraziz99/stooges/blob/main/be/cmd/relay/main.go"
click node_relaylogic "https://github.com/omaraziz99/stooges/blob/main/be/internal/relay/relay.go"
click node_policy "https://github.com/omaraziz99/stooges/blob/main/be/internal/relay/policy.go"
click node_accounts "https://github.com/omaraziz99/stooges/blob/main/be/internal/accounts/accounts.go"
click node_store "https://github.com/omaraziz99/stooges/blob/main/be/internal/store/store.go"
click node_kpiagent "https://github.com/omaraziz99/stooges/blob/main/be/cmd/kpi/main.go"
click node_kpipipeline "https://github.com/omaraziz99/stooges/tree/main/be/internal/kpi"
click node_framework "https://github.com/omaraziz99/stooges/blob/main/be/internal/kpi/framework.go"
click node_kpidashboard "https://github.com/omaraziz99/stooges/blob/main/fe/src/components/KpiDashboard.tsx"
click node_kpireview "https://github.com/omaraziz99/stooges/blob/main/fe/src/components/KpiReviewPanel.tsx"
click node_kpimodel "https://github.com/omaraziz99/stooges/blob/main/fe/src/lib/kpi.ts"
click node_kpiparts "https://github.com/omaraziz99/stooges/blob/main/fe/src/components/KpiParts.tsx"

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_login,node_auth,node_relaystate,node_relayclient toneBlue
class node_channelview,node_composer,node_threads,node_messages,node_sidebar,node_chatmodel,node_fileuploads toneAmber
class node_relayserver,node_relaylogic,node_policy,node_accounts,node_store toneMint
class node_kpiagent,node_kpipipeline,node_framework,node_kpidashboard,node_kpireview,node_kpimodel,node_kpiparts toneRose
class node_member toneIndigo
```

## Components

### Web app

- [App workspace](https://github.com/omaraziz99/stooges/blob/main/fe/src/App.tsx): `fe/src/App.tsx`
- [Sign-in](https://github.com/omaraziz99/stooges/blob/main/fe/src/components/Login.tsx): `fe/src/components/Login.tsx`
- [Account auth](https://github.com/omaraziz99/stooges/blob/main/fe/src/lib/auth.ts): `fe/src/lib/auth.ts`
- [Relay state](https://github.com/omaraziz99/stooges/blob/main/fe/src/state/relay.tsx): `fe/src/state/relay.tsx`
- [Relay client](https://github.com/omaraziz99/stooges/blob/main/fe/src/lib/relay.ts): `fe/src/lib/relay.ts`

### Chat experience

- [Channel view](https://github.com/omaraziz99/stooges/blob/main/fe/src/components/ChannelView.tsx): `fe/src/components/ChannelView.tsx`
- [Message composer](https://github.com/omaraziz99/stooges/blob/main/fe/src/components/Composer.tsx): `fe/src/components/Composer.tsx`
- [Threads](https://github.com/omaraziz99/stooges/blob/main/fe/src/components/ThreadPanel.tsx): `fe/src/components/ThreadPanel.tsx`
- [Message list](https://github.com/omaraziz99/stooges/blob/main/fe/src/components/MessageList.tsx): `fe/src/components/MessageList.tsx`
- [Workspace sidebar](https://github.com/omaraziz99/stooges/blob/main/fe/src/components/Sidebar.tsx): `fe/src/components/Sidebar.tsx`
- [Chat events](https://github.com/omaraziz99/stooges/blob/main/fe/src/lib/chat.ts): `fe/src/lib/chat.ts`
- [File attachments](https://github.com/omaraziz99/stooges/blob/main/fe/src/lib/files.ts): `fe/src/lib/files.ts`

### Relay and accounts

- [Chat relay](https://github.com/omaraziz99/stooges/blob/main/be/cmd/relay/main.go): `be/cmd/relay/main.go`
- [Relay service](https://github.com/omaraziz99/stooges/blob/main/be/internal/relay/relay.go): `be/internal/relay/relay.go`
- [Relay policy](https://github.com/omaraziz99/stooges/blob/main/be/internal/relay/policy.go): `be/internal/relay/policy.go`
- [Account service](https://github.com/omaraziz99/stooges/blob/main/be/internal/accounts/accounts.go): `be/internal/accounts/accounts.go`
- [SQLite store](https://github.com/omaraziz99/stooges/blob/main/be/internal/store/store.go): `be/internal/store/store.go`

### KPI insights

- [KPI agent](https://github.com/omaraziz99/stooges/blob/main/be/cmd/kpi/main.go): `be/cmd/kpi/main.go`
- [Evidence and report generation](https://github.com/omaraziz99/stooges/tree/main/be/internal/kpi): `be/internal/kpi`
- [KPI framework](https://github.com/omaraziz99/stooges/blob/main/be/internal/kpi/framework.go): `be/internal/kpi/framework.go`
- [KPI dashboard](https://github.com/omaraziz99/stooges/blob/main/fe/src/components/KpiDashboard.tsx): `fe/src/components/KpiDashboard.tsx`
- [Person review](https://github.com/omaraziz99/stooges/blob/main/fe/src/components/KpiReviewPanel.tsx): `fe/src/components/KpiReviewPanel.tsx`
- [Report parsing and commands](https://github.com/omaraziz99/stooges/blob/main/fe/src/lib/kpi.ts): `fe/src/lib/kpi.ts`
- [Evidence and review views](https://github.com/omaraziz99/stooges/blob/main/fe/src/components/KpiParts.tsx): `fe/src/components/KpiParts.tsx`

### Other components

- **Team member**

## Connections

- Team member → Sign-in: signs in
- Sign-in → Account auth: authenticates (evidence: `fe/src/components/Login.tsx`)
- App workspace → Sign-in: shows signed out (evidence: `fe/src/App.tsx`)
- App workspace → Relay state: provides session (evidence: `fe/src/App.tsx`)
- Relay state → Relay client: connects (evidence: `fe/src/state/relay.tsx`)
- Team member → App workspace: uses
- App workspace → Channel view: renders (evidence: `fe/src/App.tsx`)
- App workspace → Workspace sidebar: renders (evidence: `fe/src/App.tsx`)
- Channel view → Message composer: renders (evidence: `fe/src/components/ChannelView.tsx`)
- Channel view → Message list: renders (evidence: `fe/src/components/ChannelView.tsx`)
- App workspace → Threads: opens (evidence: `fe/src/App.tsx`)
- Message composer → File attachments: uploads (evidence: `fe/src/components/Composer.tsx`)
- Message composer → Chat events: publishes messages (evidence: `fe/src/components/Composer.tsx`)
- Chat events → Relay client: publishes events (evidence: `fe/src/lib/chat.ts`)
- Relay client → Chat relay: connects
- Chat relay → Relay service: starts
- Relay service → SQLite store: persists chat data
- Relay service → Relay policy: enforces policy
- Account auth → Account service: calls account API (evidence: `fe/src/lib/auth.ts`)
- Account service → SQLite store: stores accounts
- Team member → Workspace sidebar: sets channel and consent (evidence: `fe/src/components/Sidebar.tsx`)
- Team member → Message composer: posts chat
- Team member → KPI dashboard: views insights
- App workspace → KPI dashboard: renders (evidence: `fe/src/App.tsx`)
- App workspace → Person review: opens KPI command (evidence: `fe/src/App.tsx`)
- KPI dashboard → Report parsing and commands: uses report model (evidence: `fe/src/components/KpiDashboard.tsx`)
- Person review → Report parsing and commands: uses report model (evidence: `fe/src/components/KpiReviewPanel.tsx`)
- KPI dashboard → Evidence and review views: renders evidence (evidence: `fe/src/components/KpiDashboard.tsx`)
- Person review → Evidence and review views: renders evidence (evidence: `fe/src/components/KpiReviewPanel.tsx`)
- KPI agent → Chat relay: reads channels and publishes reports
- KPI agent → Evidence and report generation: generates reports
- Evidence and report generation → KPI framework: assesses against
- Evidence and report generation → KPI dashboard: report appears live