sojorn/sojorn_docs/deployment/QUICK_START.md

# Sojorn - Quick Start Guide

## Step 1: Inject Test Data

Before running the app, you'll want some content to view. Run this SQL in your Supabase SQL Editor:

### 1.1 First, create a test user account

You can do this two ways:

**Option A: Via the Flutter app**
```bash
cd sojorn_app
flutter run -d chrome
```
Then sign up with any email/password.

**Option B: Via Supabase Dashboard**
1. Go to https://app.supabase.com/project/zwkihedetedlatyvplyz/auth/users
2. Click "Add user" → "Create new user"
3. Enter email and password
4. Then call the signup Edge Function to create the profile (see below)

### 1.2 Create a profile for the user

If you created the user via Dashboard, call the signup function:

```bash
curl -X POST "https://zwkihedetedlatyvplyz.supabase.co/functions/v1/signup" \
  -H "Authorization: Bearer YOUR_USER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "handle": "sojorn_poet",
    "display_name": "Sojorn Poet",
    "bio": "Sharing calm words for a busy world"
  }'
```

### 1.3 Inject the poetry posts

Go to https://app.supabase.com/project/zwkihedetedlatyvplyz/sql/new

Paste the contents of `supabase/seed/seed_test_posts.sql` and run it.

This will inject 20 beautiful, calm posts with poetry and wisdom.

---

## Step 2: Disable Email Confirmation (For Development)

1. Go to https://app.supabase.com/project/zwkihedetedlatyvplyz/auth/providers
2. Click on "Email" provider
3. Toggle **OFF** "Confirm email"
4. Click "Save"

This allows immediate sign-in during development.

---

## Step 3: Run the Flutter App

```bash
cd sojorn_app
flutter pub get
flutter run -d chrome
```

Or for mobile:
```bash
flutter run -d android
# or
flutter run -d ios
```

---

## Step 4: Test the Flow

### 4.1 Sign Up
1. Click "Create an account"
2. Enter email/password
3. Create your profile (handle, display name, bio)
4. You'll be redirected to the home screen

### 4.2 View Feeds
- **Following** tab: Will be empty until you follow someone
- **Sojorn** tab: Shows all posts ranked by calm velocity
- **Profile** tab: Shows your profile, trust tier, and posting limits

### 4.3 Create a Post
1. Tap the floating (+) button
2. Select a category
3. Write your post (500 char max)
4. Tap "Publish"
5. Tone detection will analyze and either accept or reject

### 4.4 Check Your Profile
- View your trust tier (starts at "New")
- See daily posting limit (3/day for new users)
- View harmony score (starts at 50)

---

## Common Issues & Fixes

### Issue: "Failed to get profile"

**Cause**: Profile wasn't created after signup

**Fix**:
```sql
-- Check if profile exists
SELECT * FROM profiles WHERE id = 'YOUR_USER_ID';

-- If missing, the signup Edge Function didn't run
-- You can manually insert:
INSERT INTO profiles (id, handle, display_name, bio)
VALUES ('YOUR_USER_ID', 'your_handle', 'Your Name', 'Bio here');

-- Also create trust_state:
INSERT INTO trust_state (user_id)
VALUES ('YOUR_USER_ID');
```

### Issue: "Error loading categories"

**Cause**: Categories table is empty

**Fix**:
```bash
# Run the category seed:
cd supabase
cat seed/seed_categories.sql | # paste into SQL Editor
```

### Issue: Posts not showing in feed

**Cause**: No posts exist or RLS is blocking

**Fix**:
```sql
-- Check if posts exist:
SELECT COUNT(*) FROM posts WHERE status = 'active';

-- Check if you can see them:
SELECT * FROM posts WHERE status = 'active' LIMIT 5;

-- If posts exist but RLS blocks, check:
SELECT * FROM categories;
-- Make sure 'general' category exists and is not default_off
```

### Issue: Can't publish posts - "Please select a category"

**Cause**: Categories aren't loading

**Fix**:
1. Open browser dev tools (F12)
2. Check Network tab for errors
3. Verify categories table has data:
```sql
SELECT * FROM categories ORDER BY name;
```

### Issue: Post rejected with "Sharp speech"

**Cause**: Tone detection flagged the content

**Fix**: This is working as intended! Try softer language:
- ❌ "This is stupid and wrong!"
- ✅ "I respectfully disagree with this approach."

---

## Next Steps

### Add More Users
1. Sign up multiple accounts
2. Follow each other
3. Test mutual-follow commenting
4. Test blocking

### Test Edge Functions Directly

```bash
# Get your auth token:
# Sign in to the app, then in browser dev tools:
localStorage.getItem('supabase.auth.token')

export TOKEN="your_token_here"

# Test profile:
curl "https://zwkihedetedlatyvplyz.supabase.co/functions/v1/profile" \
  -H "Authorization: Bearer $TOKEN"

# Test feed:
curl "https://zwkihedetedlatyvplyz.supabase.co/functions/v1/feed-sojorn" \
  -H "Authorization: Bearer $TOKEN"

# Test posting:
curl -X POST "https://zwkihedetedlatyvplyz.supabase.co/functions/v1/publish-post" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "category_id": "CATEGORY_UUID",
    "body": "A calm, thoughtful post."
  }'
```

### Test Tone Detection

Try posting these to see how tone detection works:

**Will be accepted (CIS 1.0):**
- "I'm grateful for this moment."
- "Sometimes the most productive thing you can do is rest."
- "Growth is uncomfortable because you've never been here before."

**Will be accepted (CIS 0.9-0.95):**
- "I disagree with that approach, but I understand the reasoning."
- "This is challenging, but we can work through it."

**Will be rejected:**
- "This is stupid and you're an idiot!"
- "What the hell were you thinking?"
- Any profanity or aggressive language

---

## Checking Logs

### View Edge Function Logs
https://app.supabase.com/project/zwkihedetedlatyvplyz/logs/edge-functions

### View Database Logs
https://app.supabase.com/project/zwkihedetedlatyvplyz/logs/postgres-logs

### View Auth Logs
https://app.supabase.com/project/zwkihedetedlatyvplyz/logs/auth-logs

---

## Development Workflow

1. **Make backend changes**: Edit Edge Functions in `supabase/functions/`
2. **Deploy**: `npx supabase functions deploy FUNCTION_NAME`
3. **Test**: Use curl or the Flutter app
4. **Make frontend changes**: Edit Flutter code in `sojorn_app/lib/`
5. **Hot reload**: Press `r` in the Flutter terminal
6. **Full restart**: Press `R` in the Flutter terminal

---

## Production Checklist

Before going live:

- [ ] Enable email confirmation
- [ ] Set up custom domain
- [ ] Configure email templates with calm copy
- [ ] Set up SMTP for transactional emails
- [ ] Enable RLS on all tables (already done)
- [ ] Set up monitoring and alerts
- [ ] Schedule harmony cron job
- [ ] Create admin dashboard for report review
- [ ] Write transparency pages ("How Reach Works")
- [ ] Set up error tracking (Sentry)
- [ ] Configure rate limiting
- [ ] Set up CDN for assets

---

**You're all set! Enjoy building Sojorn - a calm corner of the internet.**