# PulseFeed Backend Architecture Plan

## Executive Summary

Transform the localStorage demo into production-ready enterprise software with real-time features, AI sentiment analysis, and compliance-ready infrastructure.

**Timeline:** 8-12 weeks MVP → 16-20 weeks full feature parity  
**Cost:** ~$100-300/month at launch → $500-2000/month at scale  
**Stack:** Supabase (Postgres + Auth + Realtime), Node.js API, Hugging Face NLP, Vercel/Railway

---

## Current State vs. Target State

### What Works Now (localStorage Demo)
- ✅ Anonymous posting with emoji reactions
- ✅ Basic sentiment badges (hardcoded)
- ✅ Tag system
- ✅ Content moderation flags
- ✅ Admin dashboard UI
- ✅ Real-time UI updates (fake, in-memory only)

### What's Missing (Promises We Can't Keep)
- ❌ No database (data disappears on page refresh)
- ❌ No real authentication (admin.html is public)
- ❌ No AI sentiment analysis (badges are hardcoded)
- ❌ No actual real-time updates (no WebSockets)
- ❌ No multi-tenancy (can't have separate orgs)
- ❌ No data persistence beyond browser
- ❌ No compliance infrastructure (SOC 2, HIPAA claims are false)
- ❌ No API for integrations

---

## Tech Stack Decision

### Core Infrastructure: Supabase (Recommended)
**Why Supabase:**
- Postgres database (proven, reliable)
- Built-in authentication + RLS (Row Level Security)
- Real-time subscriptions (WebSocket out of the box)
- Edge functions for serverless logic
- Storage for file uploads
- Free tier: 500MB database, 2GB bandwidth, 50K monthly users
- Paid: $25/mo (Pro) → $599/mo (Team) → Custom (Enterprise)

**Alternative: Firebase**
- Pros: Easier real-time, better DX
- Cons: NoSQL (bad for complex queries), vendor lock-in, expensive at scale

**Why NOT a custom backend:**
- 4-6 weeks just to build auth + real-time infrastructure
- Security vulnerabilities if done wrong
- Maintenance burden
- Supabase gives you this for $25/mo

### AI/ML: Hugging Face Inference API
**For sentiment analysis:**
- Model: `distilbert-base-uncased-finetuned-sst-2-english`
- Cost: FREE for 30K requests/month, then $0.06/1K requests
- Latency: 200-500ms per request
- Accuracy: 92%+ on workplace feedback

**Alternative: OpenAI GPT-4o-mini**
- Better nuance detection (sarcasm, burnout signals)
- $0.15 per 1M input tokens (~$0.0001 per post)
- Can extract themes, not just positive/negative
- Worth it for Professional/Enterprise tiers

### Frontend Deployment: Vercel (Current Static Site)
- Keep current GitHub Pages setup for marketing site
- Move demo app to `/app` subdomain with Vercel
- Static export for marketing, dynamic for app

### API Layer: Edge Functions (Supabase) + Node.js (Optional)
- Supabase Edge Functions for simple operations (Deno runtime)
- Separate Node.js API (Railway/Render) for complex logic:
  - Batch sentiment analysis
  - Webhook processing
  - Report generation
  - Third-party integrations

---

## Database Schema

### Core Tables

```sql
-- Organizations (multi-tenancy)
CREATE TABLE organizations (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  name TEXT NOT NULL,
  slug TEXT UNIQUE NOT NULL,
  plan TEXT NOT NULL DEFAULT 'starter', -- starter, professional, enterprise
  settings JSONB DEFAULT '{}',
  created_at TIMESTAMPTZ DEFAULT NOW(),
  updated_at TIMESTAMPTZ DEFAULT NOW()
);

-- Users (employees + admins)
CREATE TABLE users (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  org_id UUID REFERENCES organizations(id) ON DELETE CASCADE,
  email TEXT UNIQUE,
  role TEXT NOT NULL DEFAULT 'employee', -- employee, admin, owner
  anonymous_token TEXT UNIQUE, -- for zero-knowledge auth
  last_seen TIMESTAMPTZ,
  created_at TIMESTAMPTZ DEFAULT NOW()
);

-- Posts (anonymous feedback)
CREATE TABLE posts (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  org_id UUID REFERENCES organizations(id) ON DELETE CASCADE,
  content TEXT NOT NULL,
  sentiment TEXT, -- positive, negative, neutral, urgent
  sentiment_score FLOAT, -- -1.0 to 1.0
  ai_themes JSONB, -- extracted themes/keywords
  status TEXT DEFAULT 'pending', -- pending, approved, flagged, archived
  is_anonymous BOOLEAN DEFAULT true,
  metadata JSONB DEFAULT '{}', -- no PII, just timezone/dept if volunteered
  created_at TIMESTAMPTZ DEFAULT NOW(),
  updated_at TIMESTAMPTZ DEFAULT NOW()
);

-- Reactions (emoji responses)
CREATE TABLE reactions (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  post_id UUID REFERENCES posts(id) ON DELETE CASCADE,
  reaction_type TEXT NOT NULL, -- thumbs_up, heart, eyes, etc
  anonymous_token TEXT, -- to prevent duplicate reactions
  created_at TIMESTAMPTZ DEFAULT NOW(),
  UNIQUE(post_id, anonymous_token, reaction_type)
);

-- Tags (categorization)
CREATE TABLE tags (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  org_id UUID REFERENCES organizations(id) ON DELETE CASCADE,
  name TEXT NOT NULL,
  color TEXT,
  created_at TIMESTAMPTZ DEFAULT NOW(),
  UNIQUE(org_id, name)
);

-- Post Tags (many-to-many)
CREATE TABLE post_tags (
  post_id UUID REFERENCES posts(id) ON DELETE CASCADE,
  tag_id UUID REFERENCES tags(id) ON DELETE CASCADE,
  PRIMARY KEY (post_id, tag_id)
);

-- Analytics snapshots (daily aggregations)
CREATE TABLE analytics_snapshots (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  org_id UUID REFERENCES organizations(id) ON DELETE CASCADE,
  date DATE NOT NULL,
  metrics JSONB NOT NULL, -- {avg_sentiment, post_count, engagement_rate, etc}
  created_at TIMESTAMPTZ DEFAULT NOW(),
  UNIQUE(org_id, date)
);

-- Admin actions (audit log)
CREATE TABLE admin_actions (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  org_id UUID REFERENCES organizations(id) ON DELETE CASCADE,
  admin_id UUID REFERENCES users(id) ON DELETE SET NULL,
  action_type TEXT NOT NULL, -- flagged_post, archived_post, changed_settings
  target_id UUID, -- post_id or user_id
  details JSONB,
  created_at TIMESTAMPTZ DEFAULT NOW()
);
```

### Row Level Security (RLS) Policies

```sql
-- Enable RLS on all tables
ALTER TABLE posts ENABLE ROW LEVEL SECURITY;
ALTER TABLE organizations ENABLE ROW LEVEL SECURITY;
ALTER TABLE users ENABLE ROW LEVEL SECURITY;

-- Employees can read all posts in their org
CREATE POLICY "Employees can read org posts"
  ON posts FOR SELECT
  USING (org_id = (SELECT org_id FROM users WHERE id = auth.uid()));

-- Employees can insert anonymous posts
CREATE POLICY "Employees can create posts"
  ON posts FOR INSERT
  WITH CHECK (org_id = (SELECT org_id FROM users WHERE id = auth.uid()));

-- Only admins can update post status
CREATE POLICY "Admins can update posts"
  ON posts FOR UPDATE
  USING (
    org_id IN (
      SELECT org_id FROM users 
      WHERE id = auth.uid() AND role IN ('admin', 'owner')
    )
  );
```

---

## Authentication Architecture

### Zero-Knowledge Anonymous Posting

**Problem:** Employees must be truly anonymous, but we need to prevent spam.

**Solution: Anonymous Tokens**

1. **Employee onboarding:**
   - Admin invites employee via email
   - Employee clicks link → generates `anonymous_token` (UUID)
   - Token stored in browser localStorage only
   - Token is the ONLY identifier for anonymous posts

2. **Posting flow:**
   ```javascript
   // Frontend
   const token = localStorage.getItem('pulsefeed_anon_token');
   await supabase.from('posts').insert({
     org_id: CURRENT_ORG,
     content: postContent,
     anonymous_token: token // NOT sent to database
   });
   ```

3. **Server-side anonymization:**
   - Edge function intercepts insert
   - Hashes `anonymous_token` with org salt
   - Stores only hash (for spam prevention)
   - Drops original token before database write

**Result:** 
- ✅ Employees can post without auth
- ✅ Spam prevention (one token = one identity)
- ✅ Zero PII in database
- ✅ Admin can never trace posts to individuals

### Admin Authentication

**Standard Supabase Auth:**
- Email + password (Magic link optional)
- MFA required for admin/owner roles
- JWT tokens with role claims
- Session expires after 7 days

---

## Real-Time Features

### Supabase Realtime Subscriptions

```javascript
// Employee portal - live feed updates
const subscription = supabase
  .channel('posts')
  .on('postgres_changes', 
    { event: 'INSERT', schema: 'public', table: 'posts' },
    (payload) => {
      // New post appears instantly
      addPostToFeed(payload.new);
    }
  )
  .on('postgres_changes',
    { event: 'UPDATE', schema: 'public', table: 'posts' },
    (payload) => {
      // Status changes (approved/flagged) update UI
      updatePostStatus(payload.new);
    }
  )
  .subscribe();

// Admin dashboard - live sentiment gauge
const analyticsSubscription = supabase
  .channel('analytics')
  .on('postgres_changes',
    { event: '*', schema: 'public', table: 'posts' },
    async () => {
      // Recalculate metrics on any post change
      await refreshDashboardMetrics();
    }
  )
  .subscribe();
```

**Cost:** Included in Supabase Pro ($25/mo) for up to 200 concurrent connections.

---

## AI Sentiment Analysis Pipeline

### Option A: Hugging Face (MVP - Free)

```javascript
// Edge Function: analyzeSentiment
import { HfInference } from '@huggingface/inference';

const hf = new HfInference(process.env.HUGGINGFACE_API_KEY);

export async function analyzeSentiment(text) {
  const result = await hf.textClassification({
    model: 'distilbert-base-uncased-finetuned-sst-2-english',
    inputs: text
  });
  
  // result: [{ label: 'POSITIVE', score: 0.9998 }]
  return {
    sentiment: result[0].label.toLowerCase(),
    confidence: result[0].score
  };
}
```

**Limitations:**
- Only positive/negative (no "urgent" or "burnout" signals)
- English only
- Doesn't understand workplace context

### Option B: OpenAI GPT-4o-mini (Production)

```javascript
// Edge Function: advancedSentimentAnalysis
import OpenAI from 'openai';

const openai = new OpenAI(process.env.OPENAI_API_KEY);

export async function advancedSentimentAnalysis(text) {
  const response = await openai.chat.completions.create({
    model: 'gpt-4o-mini',
    messages: [{
      role: 'system',
      content: `You are analyzing anonymous employee feedback. Extract:
1. Overall sentiment (positive/neutral/negative/urgent)
2. Key themes (max 3 tags)
3. Burnout indicators (true/false)
4. Safety concerns (true/false)
5. Confidence score (0-1)

Return JSON only.`
    }, {
      role: 'user',
      content: text
    }],
    response_format: { type: 'json_object' },
    temperature: 0.3
  });
  
  return JSON.parse(response.choices[0].message.content);
  // Returns: { sentiment: 'urgent', themes: ['safety', 'management'], burnout: false, safety: true, confidence: 0.95 }
}
```

**Cost:** ~$0.0001 per post (100K posts = $10)  
**Speed:** 500-1000ms  
**Accuracy:** 95%+

### Hybrid Approach (Recommended)

- **Starter plan:** Hugging Face only (free)
- **Professional plan:** GPT-4o-mini for all posts
- **Enterprise plan:** GPT-4o-mini + custom fine-tuned model

---

## API Architecture

### Edge Functions (Supabase Deno)

```
/functions/
  ├── create-post/          # POST /posts (with sentiment analysis)
  ├── react-to-post/        # POST /posts/:id/reactions
  ├── admin-update-post/    # PATCH /posts/:id (flag/approve)
  ├── get-analytics/        # GET /analytics (cached snapshots)
  └── invite-employee/      # POST /invites (send anonymous token)
```

### External Node.js API (Optional, for complex ops)

```
/api/
  ├── /webhooks/            # Slack, Teams integrations
  ├── /reports/             # PDF generation (weekly summaries)
  ├── /batch/               # Bulk sentiment re-analysis
  └── /export/              # Data export for compliance
```

**Why separate?**
- Edge functions timeout at 60s
- Node.js for long-running tasks
- Better library ecosystem (Puppeteer, PDFKit)

---

## Security & Compliance

### SOC 2 Type II Readiness (6-12 months)

**What's required:**
1. ✅ Encryption at rest (Supabase: AES-256)
2. ✅ Encryption in transit (HTTPS/TLS 1.3)
3. ✅ Audit logging (admin_actions table)
4. ✅ Access controls (RLS + MFA)
5. ⚠️ Penetration testing ($5K-15K)
6. ⚠️ Security policies documentation
7. ⚠️ Third-party audit ($20K-50K)

**Honest timeline:** 12+ months + $30K-80K  
**Marketing fix:** Remove "We are SOC 2 compliant" → "SOC 2 Type II available on request (Enterprise plan)"

### HIPAA Compliance (Healthcare customers)

**What's required:**
1. ✅ Business Associate Agreement (BAA)
2. ✅ Encrypted data at rest + in transit
3. ✅ Audit logs
4. ⚠️ PHI de-identification (no health data in feedback)
5. ⚠️ Breach notification procedures
6. ⚠️ Annual risk assessments

**Supabase can provide BAA** (available on Pro+ plans)  
**Marketing fix:** "HIPAA-ready infrastructure available (Enterprise plan with BAA)"

---

## Deployment Strategy

### Phase 1: Infrastructure (Week 1-2)
- ✅ Supabase project setup
- ✅ Database schema + RLS policies
- ✅ Authentication flows
- ✅ Deploy to staging

### Phase 2: Core Features (Week 3-6)
- ✅ Anonymous posting API
- ✅ Admin dashboard backend
- ✅ Real-time subscriptions
- ✅ Basic sentiment analysis (Hugging Face)

### Phase 3: Advanced Features (Week 7-10)
- ✅ GPT-4o-mini sentiment upgrade
- ✅ Analytics aggregation (daily snapshots)
- ✅ Admin moderation queue
- ✅ Reaction system

### Phase 4: Polish (Week 11-12)
- ✅ Performance optimization
- ✅ Security audit
- ✅ Load testing (10K users)
- ✅ Production deployment

### Phase 5: Enterprise Features (Week 13-20)
- ✅ Multi-org support (white-label)
- ✅ SSO (SAML, OAuth)
- ✅ Advanced analytics (burnout detection)
- ✅ Webhook integrations
- ✅ Data export / compliance reports

---

## Cost Breakdown

### Monthly Operating Costs

**Starter Tier (up to 50 users):**
- Supabase Pro: $25/mo
- Hugging Face: FREE
- Vercel: FREE (or $20/mo Pro)
- Domain + SSL: $2/mo
- **Total: $27-47/mo**

**Professional Tier (up to 200 users):**
- Supabase Pro: $25/mo
- OpenAI GPT-4o-mini: ~$10-50/mo (varies by volume)
- Vercel Pro: $20/mo
- Node.js API (Railway): $5-10/mo
- **Total: $60-105/mo**

**Enterprise Tier (1000+ users):**
- Supabase Team: $599/mo (or custom)
- OpenAI: $100-500/mo
- Vercel Pro: $20/mo
- Node.js API: $20-50/mo
- CDN (Cloudflare): $20-100/mo
- **Total: $759-1,269/mo**

### One-Time Costs
- Compliance audit (SOC 2): $30K-80K (optional, year 2)
- Security penetration test: $5K-15K (optional, year 2)
- Custom AI model training: $5K-20K (Enterprise only)

---

## Migration Plan: Demo → Production

### Keep Demo for Marketing
```
pulsefeed.software/          → Marketing site (current)
pulsefeed.software/demo/     → localStorage demo (keep this!)
app.pulsefeed.software/      → Real product (new)
```

### Why Keep Demo?
- ✅ Instant gratification (no signup friction)
- ✅ Shows full product before commitment
- ✅ Drives qualified leads

### Add Demo → Signup Flow
```javascript
// After 3 posts in demo
showModal({
  title: "Want to save your feedback?",
  message: "This demo resets when you refresh. Get the real version with your team.",
  cta: "Start Free Trial",
  link: "app.pulsefeed.software/signup"
});
```

---

## Success Metrics

### Technical KPIs
- API latency: <200ms (p95)
- Real-time message delivery: <500ms
- Uptime: 99.9%
- Sentiment analysis accuracy: >90%

### Business KPIs
- Demo → Signup conversion: >5%
- Trial → Paid conversion: >20%
- Churn rate: <5% monthly
- NPS: >50

---

## Risks & Mitigations

### Risk 1: Anonymous system gets abused (spam, harassment)
**Mitigation:**
- Rate limiting (5 posts/hour per token)
- Admin moderation queue
- Content filters (profanity, hate speech)
- Ability to revoke anonymous tokens

### Risk 2: AI sentiment is wrong (misclassifies burnout as positive)
**Mitigation:**
- Show confidence scores to admins
- Allow manual sentiment override
- Log AI predictions for retraining
- Use GPT-4o-mini for nuanced cases (Professional+)

### Risk 3: Real-time doesn't scale (1000+ concurrent users)
**Mitigation:**
- Supabase Realtime handles 10K+ connections on Team plan
- Implement connection pooling
- Fallback to polling if WebSocket fails
- Cache analytics snapshots (don't recompute on every post)

### Risk 4: Compliance claims get us sued
**Mitigation:**
- Remove "We are SOC 2 compliant" immediately
- Change to "SOC 2 Type II infrastructure available (Enterprise)"
- Work with legal counsel on BAA terms
- Get actual audit before selling to healthcare/government

---

## Recommendation

### MVP Scope (12 weeks)
1. ✅ Supabase backend with auth + database
2. ✅ Anonymous posting with token system
3. ✅ Real-time updates (posts + reactions)
4. ✅ Hugging Face sentiment (basic)
5. ✅ Admin dashboard with moderation
6. ✅ Demo → signup conversion flow

**Cost:** $50-100/mo to run  
**Revenue:** $499/mo (first customer) = 5-10x ROI immediately  

### What to Defer
- ❌ SOC 2 compliance (wait until 10+ enterprise customers)
- ❌ Custom AI models (use GPT-4o-mini)
- ❌ White-label/multi-org (add when needed)
- ❌ Advanced analytics (daily snapshots are enough)

### What to Fix NOW
Update marketing site to be honest:
- "SOC 2-ready infrastructure" (not "SOC 2 compliant")
- "Coming soon: AI sentiment analysis" (in demo banner)
- "HIPAA-ready deployments available" (not "HIPAA compliant")

This buys you 12 weeks to build without lying to customers.

---

## Next Steps

1. **Week 1:** Set up Supabase project + deploy database schema
2. **Week 2:** Implement anonymous auth + posting API
3. **Week 3:** Connect frontend to real backend (remove localStorage)
4. **Week 4:** Add Hugging Face sentiment analysis
5. **Week 5-8:** Build admin dashboard features
6. **Week 9-10:** Implement real-time subscriptions
7. **Week 11-12:** QA, security review, production launch

**Start Date:** Tomorrow  
**Launch Date:** March 15, 2026 (12 weeks)  
**First Paying Customer:** April 2026 (hopefully)
