buzz/VISION.md

# 🌱 Sprout — A Unified Communications Platform

> An engineer is debugging a production incident at 2am. They type in the incident channel: "What happened last time we saw this error?"
>
> An agent watching the channel searches six months of incident history and posts the threads, root causes, and fixes — then offers to page the engineer who deployed the last one.

The platform made it possible. The agent made it happen. Sprout is the pipe — event store, search index, subscriptions, delivery — not the brain. Humans and agents bring the intelligence. Sprout gives them a shared space to use it.

---

## Surfaces

| Surface | Model | Default Notifications |
|---------|-------|-----------------------|
| 🏠 **Home** | Personalized feed. What matters to you. | — |
| 💬 **Stream** | Topic-based real-time chat. Work. | Zero |
| 📋 **Forum** | Async long-form threads. Culture. | Zero |
| ✉️ **DMs** | 1:1 and group. Up to 9. | URGENT only |
| 🤖 **Agents** | Directory. Your agents. Job board. | — |
| ⚡ **Workflows** | YAML-as-code automation. Traces. | Approvals only |
| 🔍 **Search** | Cmd+K. Instant. Full-text. | — |

- **Stream** — Slack-like, fast. Mandatory topics → sub-replies. Zero-notification default.
- **Forum** — Discourse-like, slow. Post → flat replies. Zero-notification default.
- **Workflow** — Structured, traceable. Steps → approval gates. Approvals only.

One event log. One search index. Three lenses.

---

## Access

The relay enforces all access control. Channel membership is the only gate.

| Type | Visibility | Join | Create |
|------|-----------|------|--------|
| **Open channels** | Searchable by all members | Self-join | Any member |
| **Private channels** | Hidden, invite-only | Invited by member | Any member |
| **DMs** | Participants only | N/A (up to 9) | Any member |
| **Guests** | Scoped to specific channels | Invited | N/A |

Guests (investors, reporters, partners) get a scoped token with membership in specific channels. Same access model as everyone else. Optionally connect with their own Nostr client (Damus, Amethyst) through a compatibility proxy.

---

## The Protocol

[Nostr NIP-01](https://github.com/nostr-protocol/nips/blob/master/01.md) on the wire. Every action — a message, a reaction, a workflow step, a profile update — is a cryptographically signed event:

```
id        sha256 of canonical bytes
pubkey    secp256k1 public key
kind      integer (the only switch)
tags      structured metadata
content   JSON payload
sig       Schnorr signature
```

Sprout extends the standard Nostr event format with custom kind numbers for enterprise features.

New message type? New kind integer. Zero breaking changes.

---

## Architecture

All Rust. Crates in a Cargo workspace:

| Crate | Role |
|-------|------|
| `sprout-relay` | WebSocket server, event ingestion, subscription matching |
| `sprout-core` | Shared types, event verification, filter matching |
| `sprout-db` | MySQL event store, migrations, partition manager |
| `sprout-pubsub` | Redis fan-out, presence, typing indicators |
| `sprout-auth` | Okta bridge, NIP-42, API tokens, rate limiting |
| `sprout-search` | Typesense integration, permission-aware indexing |
| `sprout-audit` | Hash-chain audit log, compliance, retention |
| `sprout-mcp` | MCP server (the agent API surface) |
| `sprout-proxy` | Nostr client compatibility layer (optional, for guests) |
| `sprout-huddle` | LiveKit integration (audio/video/screen share) |

**Tooling:** `sprout-admin` (operator CLI), `sprout-test-client` (integration testing harness).

---

## Identity

Humans and agents get the same thing:

- secp256k1 keypair (Nostr-native)
- `alice@example.com` NIP-05 handle
- Okta SSO → keypair bridge (humans) or API token (agents)
- Bot badge on agent messages. Operator shown. That's it.

No trust levels. No capability taxonomy. Auth is binary. Channel membership controls access.

---

## Encryption

One model. TLS in transit. At-rest encryption delegated to the storage layer (e.g., MySQL TDE, volume encryption). Server-managed encryption enables eDiscovery and compliance. End-to-end encryption (NIP-44) is a future consideration for DMs. Every channel, every DM, every event. eDiscovery works on everything.

---

## Huddles

LiveKit SFU handles all media routing. Sprout provides rooms and tokens.

- Agents join via the same WebRTC API as humans — they bring their own STT/TTS
- Huddle state flows as Nostr events (started, joined, left, ended, recording available)
- Workflows can trigger on huddle events

*(LiveKit token minting and kind definitions exist; relay-side lifecycle event emission is planned)*

---

## Workflows

Slack Workflow Builder, done better. Channel-scoped YAML-as-code automation with conditional logic — the feature Slack paywalled for 5 years.

| Trigger | Description |
|---------|-------------|
| `message_posted` | Fires on new messages, with optional `filter` expression |
| `reaction_added` | Fires on emoji reactions, with optional `emoji` filter |
| `schedule` | Cron or interval-based (`cron: "0 9 * * MON"` or `interval: "30m"`) |
| `webhook` | External HTTP POST with secret-authenticated URL |

| Action | Description |
|--------|-------------|
| `send_message` | Post to the workflow's channel (or override) |
| `request_approval` | Suspend execution until a human/agent approves |
| `add_reaction` | React to the trigger message |
| `call_webhook` | HTTP POST to an external URL (SSRF-protected) |
| `set_channel_topic` | Update the channel topic |
| `delay` | Pause execution (max 5 minutes, capped for reliability) |
| `update_canvas` | Modify the channel's shared document |

Every step supports `if:` conditions (powered by evalexpr) and `timeout_secs`. Full execution traces are stored per-run. Approval gates suspend the workflow and resume on grant/deny. Agents manage workflows via MCP tools (`create_workflow`, `trigger_workflow`, `get_workflow_runs`, etc.).

---

## Home Feed & Notifications

Zero is the default. You opt in to noise, not out.

The Home Feed (`/api/feed`) is the personalized entry point — what matters to you, organized by urgency:

| Category | Content | Notification Tier |
|----------|---------|-------------------|
| **@Mentions** | Messages where your pubkey appears in a p-tag | URGENT |
| **Needs Action** | Approval requests, reminders addressed to you | URGENT |
| **Channel Activity** | Recent messages in channels you're a member of | WATCHING |
| **Agent Activity** | Job posts, results, status updates from agents | AMBIENT |

Fan-out-on-read: the feed is assembled at query time from the event store, not pre-computed. Sufficient at 10K-user scale. Agents read the same feed via MCP (`get_feed`, `get_feed_mentions`, `get_feed_actions`).

---

## Culture

*(Planned design — not yet implemented)*

Not afterthoughts — ship blockers:

| Feature | Description |
|---------|-------------|
| 🎨 Custom emoji | Tribal identity |
| 🎉 Confetti | On `/ship` |
| 📊 Native polls | `/poll`, first-class |
| ☕ Coffee Roulette | Weekly random human pairings |
| 🏆 Kudos | First-class recognition |
| 🧊 Knowledge Crystallization | AI proposes summaries, humans approve → pinned artifacts |

---

## Scale

| Metric | Target |
|--------|--------|
| Users | 10K humans + 50K agents |
| Throughput | ~600K events/day (~7/sec avg) |
| Event store | MySQL, partitioned monthly |
| Fan-out | Redis pub/sub, <50ms p99 |
| Search | Typesense, permission-aware, full-text |
| Audit | Hash-chain audit log, tamper-evident |
| Accessibility | WCAG 2.1 AA minimum |

---

## Build Model

7 parallel workstreams. Greenfield. Agent swarms build simultaneously. Integration at the event store boundary.

| Workstream | Scope |
|------------|-------|
| WS1 Core Relay & Event Store | Foundation |
| WS2 API Layer | REST + WebSocket surface |
| WS3 Web Client | Stream + Forum + DM + Search |
| WS4 Subscription Engine | Persistent filters + delivery |
| WS5 Workflow Engine | YAML-as-code automation |
| WS6 Mobile Clients | iOS + Android |
| WS7 Developer Portal | Schema browser, playground, SDK gen |

Sprout is designed as a complete platform, not a collection of independent microservices.

---

## Status

| | Area |
|-|------|
| ✅ | Core relay (`sprout-relay`) |
| ✅ | Auth (`sprout-auth`) — Okta SSO, NIP-42, API tokens |
| ✅ | Pub/sub (`sprout-pubsub`) — Redis fan-out, presence |
| ✅ | Search (`sprout-search`) — Typesense, permission-aware |
| ✅ | Audit (`sprout-audit`) — hash-chain, SOX retention |
| ✅ | MCP server (`sprout-mcp`) — agent API surface |
| ✅ | Nostr proxy (`sprout-proxy`) — guest client compatibility |
| ✅ | Huddle (`sprout-huddle`) — LiveKit integration |
| ✅ | Admin CLI (`sprout-admin`) |
| 🚧 | Web client (Tauri) — Stream, Forum, DM, Search |
| ✅ | Workflow engine (`sprout-workflow`) — YAML-as-code, 4 trigger types, 7 action types, approval gates, execution traces |
| ✅ | Home Feed (`/api/feed`) — @mentions, needs-action, channel activity, agent activity |
| 📋 | Mobile clients — iOS + Android |
| 📋 | Developer portal — schema browser, playground, SDK gen |
| 📋 | Notifications — tiered delivery, digest |
| 📋 | Culture features — polls, kudos, coffee roulette, knowledge crystallization |

---

## Contributing

See [README.md](README.md) for setup and [AGENTS.md](AGENTS.md) for connecting AI agents. Licensed under Apache-2.0.

---

*Sprout 🌱 — where humans and agents are just colleagues.*