# StrategyStack Deployment Guide

## Customer-Ready Multi-Tenant Platform

This guide explains how to deploy and configure the StrategyStack Recovery, Enrichment & Outreach Platform for production use with Hugging Face Spaces.

---

## ✅ What's Already Implemented

The platform now includes:

### 1. **OAuth Authentication**
- 🔒 Sign in with Hugging Face button
- Automatic user authentication via `gr.OAuthProfile`
- All dashboard panels protected behind authentication
- Unauthenticated users see clear login prompts

### 2. **Per-User Data Isolation**
- Each user's data stored in `/data/users/{username}/`
- Zero data sharing between users
- Customer data ownership model (you don't hold their data)
- Automatic user directory creation on first access

### 3. **Multi-Tenant Architecture**
- Session-based data loading
- Username displayed in all panels
- Sample data for seamless new user onboarding
- Refresh buttons for manual data reloading

### 4. **Data Types Supported**
- Consent events (consent_events.json)
- Cadence branches (branches.json)
- Diagnostic logs (diagnostics.json)
- Extensible to any JSON-serializable data

---

## 🚀 Deployment Steps

### Step 1: Enable Persistent Storage

**CRITICAL**: Hugging Face Spaces must have persistent storage enabled for user data to persist between sessions.

1. Go to your Space: https://huggingface.co/spaces/StrategyStack/README
2. Click on **Settings** tab
3. Scroll to **Storage** section
4. Enable **Persistent storage**
5. Select storage size (recommended: 20GB minimum for multi-tenant use)
6. Save changes

**Note**: Persistent storage is mounted at `/data` and persists across Space restarts.

### Step 2: Configure Space Secrets (Optional)

If your application needs API keys for external services:

1. Go to **Settings** tab
2. Scroll to **Variables and secrets** section
3. Add secrets:
   - `LINKEDIN_API_KEY` (if using LinkedIn integration)
   - `TWILIO_API_KEY` (if using Twilio integration)
   - `SALESFORCE_API_KEY` (if using Salesforce integration)
   - Any other API keys your agents require

4. Access in code:
```python
import os
linkedin_key = os.getenv('LINKEDIN_API_KEY')
```

### Step 3: Verify OAuth Configuration

The OAuth setup is already complete:
- ✅ README.md has `hf_oauth: true` in metadata (line 9)
- ✅ app.py has `gr.LoginButton()` component
- ✅ All functions accept `gr.OAuthProfile` parameter

No additional OAuth configuration needed!

### Step 4: Test Multi-User Access

1. Open the Space: https://huggingface.co/spaces/StrategyStack/README
2. Click **Sign in with Hugging Face**
3. Verify you see:
   - Your username displayed in panels
   - Sample data (since you're a new user)
   - All four dashboard tabs accessible

4. Test with a second account:
   - Sign out
   - Sign in with different HF account
   - Verify data is separate from first account

---

## 📊 Monitoring & Operations

### Viewing Logs

1. Go to Space page
2. Click on **Logs** dropdown (top right)
3. Select:
   - **Build** - See build logs
   - **Container** - See runtime application logs

### Space Status

- 🟢 **Running** - Space is live and accepting users
- 🔵 **Building** - Space is being rebuilt after code changes
- 🔴 **Runtime Error** - Check container logs for errors

### Restarting the Space

If you need to restart:

1. Go to **Settings** tab
2. Scroll to **Sleep time settings**
3. Click **Restart Space**

**Note**: Persistent storage data survives restarts!

---

## 💾 Data Management

### User Data Structure

```
/data/
└── users/
    ├── username1/
    │   ├── consent_events.json
    │   ├── branches.json
    │   └── diagnostics.json
    ├── username2/
    │   ├── consent_events.json
    │   ├── branches.json
    │   └── diagnostics.json
    └── ...
```

### Accessing User Data

The app provides helper functions:

```python
# Load user data
user_events = load_user_data(username, "consent_events")

# Save user data
save_user_data(username, "consent_events", data)

# Get user directory
user_dir = get_user_dir(username)
```

### Backup Strategy

**Important**: While persistent storage is durable, implement regular backups:

1. **Option A - Manual Backup**:
   - Use Hugging Face Hub's file browser
   - Download `/data` directory contents
   - Store securely off-platform

2. **Option B - Automated Backup** (Future Enhancement):
   - Add scheduled backup function
   - Export to external cloud storage
   - Implement via Space cron or external scheduler

---

## ⚙️ Configuration Options

### Customizing Data Storage Location

Edit `app.py` line 9:

```python
DATA_DIR = Path("/data")  # Change if needed
```

### Adding New Data Types

1. Define new data structure (JSON-serializable)
2. Use existing functions:
```python
# Save new data type
save_user_data(username, "campaigns", campaign_data)

# Load new data type
campaigns = load_user_data(username, "campaigns")
```

3. Create UI panel to display/edit

### Customizing Authentication Messages

Edit the authentication check in panel functions (app.py):

```python
if profile is None:
    return "Your custom auth message here"
```

---

## 🛡️ Security Considerations

### Data Isolation

- ✅ Users cannot access other users' data
- ✅ File paths use username for isolation
- ✅ No centralized data storage (privacy by design)

### Authentication

- ✅ OAuth via Hugging Face (no password management needed)
- ✅ Profile information provided by HF OAuth
- ✅ Automatic session management

### API Keys

- ⚠️ Store API keys in Space Secrets (not in code)
- ⚠️ Never commit API keys to repository
- ⚠️ Use environment variables for all sensitive data

---

## 📝 Customer Setup Instructions

Provide these steps to your customers:

### For End Users:

1. **Access the Platform**:
   - Visit: https://huggingface.co/spaces/StrategyStack/README
   - Click "Sign in with Hugging Face"
   - Create free HF account if needed

2. **First Login**:
   - You'll see sample data to understand the interface
   - Your personal data directory is automatically created
   - All your data is isolated from other users

3. **Using the Dashboard**:
   - **Consent/Event Audit**: View compliance events
   - **Cadence Branching Composer**: Design outreach sequences
   - **Live Diagnostics**: Monitor system health
   - **Audit Trail Export**: Download compliance reports

4. **Data Refresh**:
   - Click "Refresh Data" button in any tab
   - Reloads your latest data from storage

### For Administrators:

1. Access Space settings for configuration
2. Monitor logs for user activity
3. Manage Space resources (storage, compute)
4. Configure API keys for integrations

---

## 🐞 Troubleshooting

### Issue: "Authentication Required" message persists

**Solution**:
- Ensure you've clicked "Sign in with Hugging Face"
- Check browser cookies are enabled
- Try hard refresh (Cmd+Shift+R / Ctrl+Shift+R)

### Issue: Data not persisting between sessions

**Solution**:
- Verify persistent storage is enabled in Space settings
- Check storage quota hasn't been exceeded
- Review container logs for write errors

### Issue: Space shows "Runtime Error"

**Solution**:
1. Click on "Logs" → "Container"
2. Look for Python errors or exceptions
3. Check if `/data` directory is accessible
4. Verify all dependencies in requirements.txt

### Issue: Slow performance

**Solution**:
- Upgrade Space hardware tier in Settings
- Optimize data loading (lazy loading)
- Implement caching for frequently accessed data

---

## 🚀 Next Steps / Future Enhancements

### Phase 1: Enhanced Data Management
- [ ] CSV export functionality
- [ ] Data import from external sources
- [ ] Bulk operations for large datasets
- [ ] Data visualization charts

### Phase 2: Integration Capabilities
- [ ] Connect actual LinkedIn API
- [ ] Twilio SMS integration
- [ ] Salesforce sync
- [ ] Email campaign management

### Phase 3: Advanced Features
- [ ] Team collaboration (share data with team members)
- [ ] Role-based access control
- [ ] Automated backup to cloud storage
- [ ] Advanced analytics dashboard

### Phase 4: Enterprise Features
- [ ] SSO integration
- [ ] Compliance certifications (SOC 2, GDPR)
- [ ] White-label branding
- [ ] Custom domain support

---

## 📞 Support

For technical support:

- **Documentation**: See README.md for API documentation
- **Issues**: Report bugs via Hugging Face Space discussions
- **Questions**: Contact via Space community tab

---

## 🎉 Summary

Your StrategyStack platform is now **customer-ready** with:

✅ **Zero-config deployment** - Works out of the box on HF Spaces
✅ **Secure authentication** - OAuth via Hugging Face
✅ **Data privacy** - Per-user isolated storage
✅ **Multi-tenant** - Unlimited users, isolated data
✅ **No external dependencies** - Everything on HF Spaces
✅ **Persistent storage** - Data survives restarts
✅ **Compliance-ready** - Full audit trails

Just enable persistent storage and you're ready to onboard customers!

---

**Last Updated**: 2025-01-06
**Platform Version**: 1.0.0 (OAuth-enabled)
**Hugging Face Spaces**: ✅ Production Ready