# Sojorn Backend - Build Summary

**Built:** January 6, 2026
**Status:** Backend foundation complete, ready for Flutter client integration

---

## What Was Built

A complete **Supabase backend** for Sojorn, a calm text-only social platform where **sharp speech stops quietly**.

### Core Philosophy Implemented

Every design choice encodes behavioral principles:

1. **Calm is structural** → RLS policies enforce boundaries at database level
2. **Consent is required** → Comments only work with mutual follows
3. **Exposure is opt-in** → Categories default to disabled, users choose what they see
4. **Influence is earned** → Harmony score determines reach and posting limits
5. **Sharp speech is contained** → Tone gates at creation, not post-hoc removal
6. **Nothing is permanent** → Feeds rotate, trends expire, scores decay naturally

---

## Technical Implementation

### 1. Database Schema (5 Migrations, 14 Tables)

**Identity & Boundaries:**
- profiles, categories, user_category_settings
- follows (mutual-follow checking), blocks (complete separation)

**Content & Engagement:**
- posts (tone-labeled, CIS-scored), post_metrics, post_likes, post_saves
- comments (mutual-follow-only), comment_votes

**Moderation & Trust:**
- reports, trust_state (harmony scoring), audit_log, trending_overrides

**All tables protected by Row Level Security (RLS)** that enforces:
- Blocked users are completely invisible to each other
- Category filtering happens at database level
- Comments require mutual follows structurally
- Trust state and reports are private

### 2. Edge Functions (8 Functions)

**Publishing Pipeline:**
- `publish-post` – Tone detection → CIS scoring → Rate limiting → Storage
- `publish-comment` – Mutual-follow check → Tone detection → Storage
- `block` – One-tap blocking with automatic follow removal
- `report` – Strict reporting with accuracy tracking

**Feed Systems:**
- `feed-personal` – Chronological feed from followed accounts
- `feed-sojorn` – Algorithmic FYP with calm velocity ranking
- `trending` – Category-scoped trending with editorial overrides

**Trust Management:**
- `calculate-harmony` – Daily cron job for harmony score recalculation

### 3. Shared Utilities (5 Modules)

- **tone-detection.ts** – Pattern-based classifier (positive, neutral, mixed, negative, hostile)
- **validation.ts** – Input validation with custom error types
- **ranking.ts** – Calm velocity algorithm (saves > likes, steady > spiky)
- **harmony.ts** – Trust score calculation and reach effects
- **supabase-client.ts** – Client configuration helpers

### 4. Database Functions (7 Functions)

- `has_block_between(user_a, user_b)` – Bidirectional block checking
- `is_mutual_follow(user_a, user_b)` – Mutual connection verification
- `can_post(user_id)` – Rate limit enforcement (3-25 posts/day by tier)
- `get_post_rate_limit(user_id)` – Get posting limit for user
- `adjust_harmony_score(user_id, delta, reason)` – Trust adjustments
- `log_audit_event(actor_id, event_type, payload)` – Audit logging
- Auto-initialization triggers for trust_state and post_metrics

---

## How Sharp Speech Stops

### Three Gates Before Amplification

1. **Tone Detection at Creation**
   - Pattern matching detects profanity, hostility, absolutism
   - Hostile/profane content is rejected immediately with rewrite suggestion
   - No post-hoc removal, no viral damage

2. **Content Integrity Score (CIS)**
   - Every post receives a score: 0.9 (positive) → 0.5 (negative)
   - Low-CIS posts have limited feed eligibility
   - Below 0.8 excluded from Trending
   - Still visible in Personal feeds (people you follow)

3. **Harmony Score (Author Trust)**
   - Private score (0-100) determines reach and posting limits
   - Tiers: New (3/day) → Trusted (10/day) → Established (25/day) → Restricted (1/day)
   - Low-Harmony authors have reduced reach multiplier
   - Scores decay naturally over time (recovery built-in)

**Result:** Sharp speech publishes but doesn't amplify. Hostility expires quietly.

---

## Behavioral Encoding

| Zen Principle | Sojorn Implementation |
|---------------|----------------------|
| Non-attachment | Boost-only (no downvotes), rotating feeds, expiring trends |
| Right speech | Tone gates, CIS scoring, harmony penalties |
| Sangha (community) | Mutual-follow conversations, category-based cohorts |
| Mindfulness | Friction before action (rate limits, rewrite prompts) |
| Impermanence | Natural decay, 7-day feed windows, trending expiration |

---

## Key Differentiators

### vs. Traditional Platforms

| Traditional | Sojorn |
|-------------|--------|
| Content spreads first, removed later | Stopped at creation |
| Bans create martyrs | Reduced reach creates natural exits |
| Shadowbanning (opaque) | Reach limits explained transparently |
| Algorithms amplify outrage | Algorithms deprioritize sharp speech |
| Moderation is reactive | Containment is structural |

### vs. Other Calm Platforms

| Other Calm Apps | Sojorn |
|-----------------|--------|
| Performative calm (aesthetics) | Structural calm (RLS, tone gates) |
| Mindfulness focus | Social connection focus |
| Content curation (passive) | Content creation (active) |
| Wellness angle | Social infrastructure angle |

---

## What Makes This Work

### 1. Database-Level Enforcement
- Boundaries aren't suggestions enforced by client code
- RLS policies make certain behaviors **structurally impossible**
- Blocking, category filtering, mutual-follow requirements cannot be bypassed

### 2. Tone Gating at Creation
- No viral damage, no post-hoc cleanup
- Users get immediate feedback (rewrite prompts)
- Hostility never enters the system

### 3. Transparent Reach Model
- Users know why their reach changes (CIS, Harmony, tone)
- No hidden algorithms or shadow penalties
- Audit log tracks all trust adjustments

### 4. Natural Fit Over Forced Moderation
- People who don't fit experience friction, not bans
- Influence diminishes naturally for hostile users
- Recovery is automatic with calm participation

---

## Architecture Highlights

### Performance
- RLS policies indexed for fast filtering
- Feed ranking uses candidate pools (500 posts max)
- Harmony calculation batched daily, not per-request
- Metrics updated via triggers (no N+1 queries)

### Security
- All tables have RLS enabled
- Service role used only in Edge Functions
- Anon key safe for client exposure
- Audit log captures sensitive actions
- Blocks enforced bidirectionally

### Scalability
- Stateless Edge Functions (Deno runtime)
- Postgres with connection pooling
- Materialized views ready for feed caching
- Trending results cacheable (15-min TTL)

---

## Next Steps

### Immediate
1. **Build Flutter client** – Onboarding, feeds, posting, blocking
2. **User signup flow** – Profile creation + trust state initialization
3. **Deploy to production** – Push migrations, deploy functions
4. **Schedule harmony cron** – Daily recalculation at 2 AM
5. **Write transparency pages** – "How Reach Works", "Rules"

### Soon After
1. **Admin tooling** – Report review, trending overrides
2. **Security audit** – RLS bypass testing, SQL injection review
3. **Load testing** – Feed performance under 10k users
4. **Data export/deletion** – GDPR compliance
5. **Beta launch** – Invite-only testing

### Future Enhancements
1. **ML-based tone detection** – Replace pattern matching
2. **Read completion tracking** – Factor into ranking
3. **Post view logging** – Dwell time analysis
4. **Analytics dashboard** – Harmony trends, category health
5. **A/B testing framework** – Optimize calm velocity parameters

---

## Files Created

### Database
- `supabase/migrations/20260106000001_core_identity_and_boundaries.sql`
- `supabase/migrations/20260106000002_content_and_engagement.sql`
- `supabase/migrations/20260106000003_moderation_and_trust.sql`
- `supabase/migrations/20260106000004_row_level_security.sql`
- `supabase/migrations/20260106000005_trending_system.sql`
- `supabase/seed/seed_categories.sql`

### Edge Functions
- `supabase/functions/_shared/supabase-client.ts`
- `supabase/functions/_shared/tone-detection.ts`
- `supabase/functions/_shared/validation.ts`
- `supabase/functions/_shared/ranking.ts`
- `supabase/functions/_shared/harmony.ts`
- `supabase/functions/publish-post/index.ts`
- `supabase/functions/publish-comment/index.ts`
- `supabase/functions/block/index.ts`
- `supabase/functions/report/index.ts`
- `supabase/functions/feed-personal/index.ts`
- `supabase/functions/feed-sojorn/index.ts`
- `supabase/functions/trending/index.ts`
- `supabase/functions/calculate-harmony/index.ts`

### Documentation
- `README.md` – Project overview
- `ARCHITECTURE.md` – How boundaries are enforced
- `HOW_SHARP_SPEECH_STOPS.md` – Tone gating deep dive
- `PROJECT_STATUS.md` – What's done, what's next
- `DEPLOYMENT.md` – Deployment guide
- `SUMMARY.md` – This file

---

## Metrics for Success

When Sojorn is working:

- **Users pause** before posting (friction is working)
- **Block rate is low** (< 1% of connections)
- **Save-to-like ratio is high** (thoughtful engagement)
- **Trending is diverse** (no single voice dominates)
- **Average harmony grows** (community trust increases)
- **Report rate is low** (< 0.1% of posts)
- **Report accuracy is high** (> 80% validated)

---

## Final Note

This backend encodes **calm as infrastructure, not aspiration**.

The database will not allow:
- Unwanted replies
- Viral hostility
- Invisible blocking
- Unconsented conversations
- Permanent influence
- Opaque reach changes

**Sojorn is structurally incapable of being an outrage machine.**

Now build the client that makes this calm accessible.

---

**Backend complete. Ready for frontend integration.**