316 lines
9.6 KiB
Markdown
316 lines
9.6 KiB
Markdown
# 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 authentic engagement 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 authentic engagement
|
||
- 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** – Authentic engagement 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 engagement 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)
|
||
|
||
- **Friendly retention:** Users return daily for genuine connection
|
||
- **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).
|