# Sojorn - Project Status

**Last Updated:** January 6, 2026

---

## Overview

The **Supabase backend foundation** for Sojorn is complete. All core database schema, Row Level Security policies, Edge Functions, and moderation systems have been implemented.

---

## ✅ Completed

### Database Schema (5 Migrations)

1. **Core Identity and Boundaries** (`20260106000001`)
   - ✅ profiles
   - ✅ categories
   - ✅ user_category_settings
   - ✅ follows (with mutual follow checking)
   - ✅ blocks (bidirectional, complete separation)
   - ✅ Helper functions: `has_block_between()`, `is_mutual_follow()`

2. **Content and Engagement** (`20260106000002`)
   - ✅ posts (with tone labels and CIS scores)
   - ✅ post_metrics (likes, saves, views)
   - ✅ post_likes (boost-only, no downvotes)
   - ✅ post_saves (private bookmarks)
   - ✅ comments (mutual-follow-only)
   - ✅ comment_votes (helpful/unhelpful)
   - ✅ Automatic metric triggers

3. **Moderation and Trust** (`20260106000003`)
   - ✅ reports (strict reasons, immutable)
   - ✅ trust_state (harmony score, tier, counters)
   - ✅ audit_log (complete transparency trail)
   - ✅ Rate limiting functions: `can_post()`, `get_post_rate_limit()`
   - ✅ Trust adjustment: `adjust_harmony_score()`
   - ✅ Audit logging: `log_audit_event()`

4. **Row Level Security** (`20260106000004`)
   - ✅ RLS enabled on all tables
   - ✅ Policies enforce:
     - Block-based invisibility
     - Category opt-in filtering
     - Mutual-follow conversation gating
     - Private saves and blocks
     - Trust state privacy

5. **Trending System** (`20260106000005`)
   - ✅ trending_overrides (editorial picks with expiration)
   - ✅ RLS policies for override visibility

### Seed Data
- ✅ Default categories (12 categories, all opt-in except "general")

### Edge Functions (13 Functions)

1.  **publish-post** ✅
    - Validates auth, length, category settings
    - Runs tone detection
    - Rejects profanity/hostility immediately
    - Assigns CIS score
    - Enforces rate limits via `can_post()`
    - Logs audit events

2.  **publish-comment** ✅
    - Validates auth and mutual follow
    - Runs tone detection
    - Rejects hostile comments
    - Stores with tone metadata

3.  **block** ✅
    - One-tap blocking (POST) and unblocking (DELETE)
    - Removes follows automatically
    - Silent, complete separation
    - Logs audit events

4.  **report** ✅
    - Validates target existence
    - Prevents self-reporting
    - Prevents duplicate reports
    - Tracks reporter accuracy in trust counters

5.  **feed-personal** ✅
    - Chronological feed from followed accounts
    - RLS automatically filters blocked users and disabled categories
    - Returns posts with user-specific like/save flags

6.  **feed-sojorn** ✅
    - Algorithmic "For You" feed
    - Fetches 500 candidate posts (last 7 days)
    - Enriches with author trust and safety metrics
    - Ranks by calm velocity algorithm
    - Returns paginated, ranked results
    - Includes ranking explanation

7.  **trending** ✅
    - Category-scoped trending
    - Merges editorial overrides + algorithmic picks
    - Eligibility: Positive/Neutral tone, CIS >= 0.8, no safety issues
    - Ranks by calm velocity
    - Limited to last 48 hours

8.  **calculate-harmony** ✅
    - Cron job for daily harmony score recalculation
    - Gathers behavior metrics for all users
    - Calculates adjustments based on:
      - Blocks received (pattern-based)
      - Trusted reports
      - Content rejection rate
      - False reports filed
      - Validated reports filed
      - Natural decay over time
    - Updates trust_state
    - Logs adjustments to audit_log

9.  **signup** ✅
    - Handles user registration and profile creation
    - Creates profile and initializes trust_state via trigger

10. **profile** ✅
    - GET/PATCH user profiles
    - View other user profiles (public data only)
    - View and update your own profile

11. **follow** ✅
    - POST to follow a user
    - DELETE to unfollow a user
    - Enforces block constraints

12. **appreciate** ✅
    - POST to appreciate (like) a post
    - DELETE to remove appreciation

13. **save** ✅
    - POST to save a post (private bookmark)
    - DELETE to unsave a post

### Shared Utilities

- ✅ **supabase-client.ts** – Client creation helpers
- ✅ **tone-detection.ts** – Pattern-based tone classifier
- ✅ **validation.ts** – Input validation with custom errors
- ✅ **ranking.ts** – Calm velocity ranking algorithm
- ✅ **harmony.ts** – Harmony score calculation and effects

### Documentation

- ✅ **ARCHITECTURE.md** – How boundaries are enforced
- ✅ **HOW_SHARP_SPEECH_STOPS.md** – Deep dive on tone gating
- ✅ **README.md** – Complete project overview

---

## 🚧 In Progress / Not Started

### Frontend (Flutter Client)
- ❌ Project setup
- ❌ Onboarding flow
- ❌ Category selection screen
- ❌ Personal feed
- ❌ Sojorn feed
- ❌ Trending view
- ❌ Post composer with tone nudges
- ❌ Post detail with comments
- ❌ Profile view with block/filter controls
- ❌ Reporting flow
- ❌ Settings (data export, delete account)

### Admin Tooling
- ❌ Report review dashboard
- ❌ Content moderation interface
- ❌ Trending override management
- ❌ Brigading pattern detection
- ❌ Role-based access control

### Additional Edge Functions
- ❌ Post view tracking (dwell time)
- ❌ Category management endpoints
- ❌ Data export endpoint
- ❌ Account deletion endpoint

### Transparency Pages
- ❌ "How Reach Works" (user-facing)
- ❌ "Community Rules" (tone and consent guidelines)
- ❌ "Privacy Policy"
- ❌ "Terms of Service"

### Infrastructure
- ❌ Cloudflare configuration
- ❌ Rate limiting at edge
- ❌ Monitoring and alerting
- ❌ Backup and recovery procedures

### Testing
- ❌ Unit tests for tone detection
- ❌ Unit tests for harmony calculation
- ❌ Unit tests for ranking algorithm
- ❌ Integration tests for Edge Functions
- ❌ RLS policy tests
- ❌ Load testing

### Enhancements
- ❌ Replace pattern-based tone detection with ML model
- ❌ Read completion tracking
- ❌ Post view logging with minimum dwell time
- ❌ Analytics dashboard for harmony trends
- ❌ A/B testing framework for ranking algorithms

---

## Decision Log

### Completed Decisions

1. **Text-only at MVP** – No images, video, or links
2. **Supabase Edge Functions** – No long-running servers
3. **Pattern-based tone detection** – Simple, replaceable, transparent
4. **Harmony score is private** – Users see tier effects, not numbers
5. **All categories opt-in** – Except "general"
6. **Boost-only engagement** – No downvotes or burying
7. **Mutual follow for comments** – Consent is structural
8. **Trending is category-scoped** – No global trending wars
9. **Editorial overrides expire** – Nothing trends forever
10. **Blocks are complete** – Bidirectional invisibility

### Open Decisions

- **ML model for tone detection** – Which provider? Cost? Latency?
- **Flutter state management** – Riverpod? Bloc? Provider?
- **Admin authentication** – Separate admin portal or in-app roles?
- **Data export format** – JSON? CSV? Both?
- **Monitoring stack** – Sentry? Custom logging?

---

## Deployment Checklist

Before public beta:

- [ ] All Edge Functions deployed to production
- [ ] Database migrations applied
- [ ] Categories seeded
- [ ] RLS policies verified with security audit
- [ ] Rate limiting enabled at Cloudflare
- [ ] Harmony calculation cron job scheduled
- [ ] Transparency pages published
- [ ] Rules and guidelines finalized
- [ ] Data export functional
- [ ] Account deletion functional
- [ ] Flutter app submitted to app stores (if mobile)
- [ ] Beta signup flow ready
- [ ] Monitoring and alerting configured
- [ ] Backup procedures tested

---

## Performance Considerations

### Current State
- **RLS policies may be slow** on large datasets (needs indexing review)
- **Feed ranking is CPU-intensive** (candidate pool of 500 posts)
- **Harmony recalculation is O(n users)** (may need batching)

### Optimization Opportunities
- Add materialized views for feed candidate queries
- Cache trending results per category (15-min TTL)
- Batch harmony calculations (process 100 users at a time)
- Add Redis for session and feed caching
- Pre-compute calm velocity scores on post creation

---

## Security Audit Needed

- [ ] Review all RLS policies for bypass vulnerabilities
- [ ] Test block enforcement across all endpoints
- [ ] Verify mutual-follow checking cannot be gamed
- [ ] Audit SQL injection risks in dynamic queries
- [ ] Test rate limiting under load
- [ ] Review audit log for PII leaks
- [ ] Verify trust score cannot be manipulated directly

---

## Next Immediate Steps

1. **Build Flutter client MVP** (onboarding, feeds, posting)
2. **Implement user signup flow** (Edge Function + profile creation)
3. **Deploy Edge Functions to Supabase production**
4. **Write transparency pages** ("How Reach Works", "Rules")
5. **Add basic admin tooling** (report review, trending overrides)
6. **Security audit of RLS policies**
7. **Load testing of feed endpoints**
8. **Schedule harmony calculation cron job**

---

## Success Metrics (Future)

- **Calm retention:** Users return daily without compulsion
- **Low block rate:** < 1% of relationships result in blocks
- **High save-to-like ratio:** Thoughtful curation > quick reactions
- **Diverse trending:** No single author/topic dominates
- **Trust growth:** Average harmony score increases over time
- **Low report rate:** < 0.1% of posts reported
- **High report accuracy:** > 80% of reports validated

---

## Contact

For implementation questions or contributions, see [README.md](README.md).