# Shadow Org: High-Level Implementation Plan

## 🧭 Overview
Shadow Org is a Discord-based AI assistant platform that allows communities (especially DAOs) to hire customizable personas that automate community tasks like onboarding, announcements, and proposal alerts. Each persona operates within a focused scope and leverages contextual knowledge to enhance communication, reduce overhead, and drive engagement.

## 🛠️ Architecture Summary

### 1. **Frontend Dashboard (Admin Interface)**
- **Framework**: Next.js (Typescript)
- **Database**: Supabase (PostgreSQL + Auth + Storage)
- **Key Features**:
- Server registration & authentication (via Discord OAuth)
- Persona hiring interface (gallery of roles)
- Context upload system (Markdown, PDFs)
- Channel assignment per persona
- Event scheduler (cron-like reminders)
- Billing integration (Stripe + Crypto optional)

### 2. **Bot Infrastructure**
- **Framework**: Node.js + `discord.js`
- **Deployment**: Single global bot serving multiple servers
- **Core Logic**:
- Listen to `messageCreate` events
- Identify server/channel/persona
- Load persona traits, static context, and short-term memory from Supabase
- Build prompt → call LLM API (OpenAI, Fleek, etc.)
- Respond in channel with persona tone/voice

---

### 🔁 Bot Infrastructure (WebSocket + HTTP API)

In addition to listening for real-time messages via Discord’s gateway, the bot service also exposes an HTTP API. This allows for internal communication from the dashboard, schedulers, and other tools.

#### HTTP Endpoints (examples):

- `POST /simulate-chat` – used by the dashboard for admin persona testing
- `POST /persona-webhook/:id` – for webhook-based persona behavior
- `POST /notify-channel` – used by Supabase Edge Functions or cron jobs

This structure keeps persona logic centralized in one service while enabling external modules (frontend, Edge, external integrations) to trigger it safely.

---

### 3. **Scheduled Services**
- **Framework**: Node.js script or Supabase Edge Function
- **Trigger**: Cron job (e.g., Railway, Upstash Scheduler)
- **Functionality**:
- Look for scheduled reminders/events
- Look for onchain events (via The Graph or Ethers.js)
- Generate message and push to Discord via bot

---

## 🧩 Data Models

### Supabase Tables
1. **personas**
- id, name, tone, trigger_type, default_prompt, avatar_url, webhook_url *(optional)*

2. **conversation_log**
- id, server_id, channel_id, persona_id, user_id, message, is_bot, created_at

3. **persona_context_chunks**
- id, persona_id, server_id, title, content, chunk_index, created_at

4. **scheduled_events**
- id, title, event_date, remind_at, channel_id, persona_id, notified

5. **watched_contracts** *(future)*
- id, chain_id, contract_address, event_name, last_processed_block, server_id, persona_id

6. **user_org_personas** *(proposed)*
- id, server_id, channel_id, user_id, persona_id, custom_name, custom_description, avatar_override_url, notification_settings (JSON), created_at

> This table tracks which personas are active in a given user org (Discord server), with overrides for name, avatar, description, and notification preferences.

---

## 🤖 AI Agent Behavior

### On Message:
1. Bot receives message via `discord.js`
2. Lookup server/channel → determine persona
3. Load static prompt + context chunks + last 5–10 messages
4. Construct LLM prompt
5. Send to model (OpenAI, Fleek, etc.)
6. Send response to Discord with persona styling

### On Schedule/Event:
1. Cron job fetches scheduled events (or watches chain)
2. Finds persona + context + channel
3. Formats a message
4. Sends via bot

> Note: Some personas may define an external `webhook_url` for custom implementation logic. In these cases, the scheduler will forward relevant data to the webhook and expect a formatted message in return, enabling flexible, decoupled persona logic.

---

## 💸 Monetization Strategy
- Base subscription per server (e.g., $20/mo)
- Add-on: "Hire new persona" with refillable credits
- Premium persona packs
- Optional: Onchain payment flow (Stripe + WalletConnect)

---

## 🧠 MVP Personas
- **Larry the Onboarder**: Greets members, answers FAQ
- **Frank the Announcer**: Posts proposal + town hall alerts
- **Ada the Accountant**: Treasury updates
- **Felix the Funmaker**: Games, XP rolls

---

## 🛣️ Roadmap

### Phase 1a: Discord Chat System
- Admin dashboard (server setup, persona hiring, file upload)
- Discord bot integration with LLM response
- Context + memory builder
- Persona simulation interface (`/simulate-chat`)

### Phase 1b: Webhook Infrastructure
- Scheduled reminders (via cron → webhook)
- Admin-scheduled messages (via Edge Function → webhook)
- Webhook support per persona
- Moloch onchain watcher (SubmitProposal)

> These features allow non-chat-based triggers to activate persona behavior and messages.

### Phase 2:
- Multi-persona management
- Upload Discord events
- Simple onchain watcher (e.g. Moloch SubmitProposal)
- Persona marketplace experience

### Phase 3:
- Persona analytics
- Vector memory & semantic search
- Voice & avatar customization
- Farcaster & Twitter bot interfaces

---

## ☁️ Hosting & Deployment Strategy

### Frontend (Admin Dashboard)
- **Hosted on**: Vercel
- **Reason**: Best-in-class for open source projects, great DX, free tier, serverless API support

### Database & Storage
- **Hosted on**: Supabase
- **Reason**: Combines Postgres, Auth, Storage, and Functions — ideal for MVPs

### Bot Infrastructure
- **Hosted on**: Railway (Node.js background worker)
- **Reason**: Persistent WebSocket support, GitHub integration, supports Docker, simple environment and logging tools

### Scheduler / Cron Jobs
- **Hosted on**: Supabase Edge Functions or Upstash Scheduler
- **Reason**: Handles reminders and onchain checks, minimal cost for MVP

> This setup separates frontend and real-time bot logic, while keeping infra low-cost and easy to scale independently.

---

## 🧪 Supabase Edge Function Integration

Supabase Edge Functions are Deno-based serverless functions ideal for short-lived, event-triggered tasks. They can interact directly with Supabase tables and call external services like the bot infra via HTTP.

### Recommended Uses:
- Triggering bot actions from dashboard buttons ("Send Test Message")
- Lightweight webhook endpoints
- Scheduled reminders that forward to the bot

### Example Workflow:
1. Supabase Edge Function runs on a schedule or admin trigger
2. Queries relevant data (e.g. reminder content, Discord channel)
3. Sends HTTP POST to bot service hosted on Railway
4. Bot receives and formats a message in persona style, sends to Discord

### Benefits:
- Decouples dashboard and bot infrastructure cleanly
- Ideal for lightweight, short-duration logic
- Keeps secure Supabase access within the edge

### Example Languages:
- Written in **TypeScript** with **Deno runtime**
- Uses native `fetch()` and web APIs

This hybrid model allows scheduled and ad-hoc actions without tightly binding bot logic into the main dashboard codebase.