patrick/sojorn
1
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity
sojorn/sojorn_docs/reference/SUMMARY.md

9.6 KiB
Raw Blame History

Sojorn Backend - Build Summary

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

What Was Built

A complete Go backend for Sojorn, a friends-first social platform where genuine connections thrive.

Core Philosophy Implemented

Every design choice encodes behavioral principles:

  1. Connection 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 authentic engagement 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 – Authentic engagement 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 Friendly Platforms

Other Friendly Apps Sojorn
Performative friendliness (aesthetics) Structural friendliness (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 positive 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 engagement 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 friendliness 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 friendliness accessible.

Backend complete. Ready for frontend integration.