sojorn/sojorn_docs

Sojorn Documentation Hub

Overview

This directory contains comprehensive documentation for the Sojorn platform, covering all aspects of development, deployment, and maintenance.

Document Structure

📚 Core Documentation

E2EE_COMPREHENSIVE_GUIDE.md

Complete end-to-end encryption implementation guide, covering the evolution from simple stateless encryption to production-ready X3DH system.

FCM_COMPREHENSIVE_GUIDE.md

Comprehensive Firebase Cloud Messaging setup and troubleshooting guide for both Web and Android platforms.

BACKEND_MIGRATION_COMPREHENSIVE.md

Complete migration documentation from Supabase to self-hosted Golang backend, including planning, execution, and validation.

TROUBLESHOOTING_COMPREHENSIVE.md

Comprehensive troubleshooting guide covering authentication, notifications, E2EE chat, backend services, and deployment issues.

DEVELOPMENT_COMPREHENSIVE.md

Complete development and architecture guide, covering design patterns, code organization, testing strategies, and performance optimization.

DEPLOYMENT_COMPREHENSIVE.md

Comprehensive deployment and operations guide, covering infrastructure setup, deployment procedures, monitoring, and maintenance.

📋 Organized Documentation

Deployment Guides (deployment/)

• QUICK_START.md - Quick start guide for new developers
• SETUP.md - Complete environment setup
• VPS_SETUP_GUIDE.md - Server infrastructure setup
• SEEDING_SETUP.md - Database seeding and test data
• R2_CUSTOM_DOMAIN_SETUP.md - Cloudflare R2 configuration
• DEPLOYMENT.md - Deployment procedures
• DEPLOYMENT_STEPS.md - Step-by-step deployment

Feature Documentation (features/)

• IMAGE_UPLOAD_IMPLEMENTATION.md - Image upload system
• notifications-troubleshooting.md - Notification system issues
• posting-and-appreciate-fix.md - Post interaction fixes

Design & Architecture (design/)

• DESIGN_SYSTEM.md - Visual design system and UI guidelines
• CLIENT_README.md - Flutter client architecture
• database_architecture.md - Database schema and design

Reference Materials (reference/)

• PROJECT_STATUS.md - Current project status and roadmap
• NEXT_STEPS.md - Planned features and improvements
• SUMMARY.md - Project overview and summary

Platform Philosophy (philosophy/)

• CORE_VALUES.md - Core platform values
• UX_GUIDE.md - UX design principles
• FOURTEEN_PRECEPTS.md - Platform precepts
• HOW_SHARP_SPEECH_STOPS.md - Communication guidelines
• SEEDING_PHILOSOPHY.md - Content seeding philosophy

Troubleshooting Archive (troubleshooting/)

• JWT_401_FIX_2026-01-11.md - JWT authentication fixes
• JWT_ERROR_RESOLUTION_2025-12-30.md - JWT error resolution
• TROUBLESHOOTING_JWT_2025-12-30.md - JWT troubleshooting
• image-upload-fix-2025-01-08.md - Image upload fixes
• search_function_debugging.md - Search debugging
• test_image_upload_2025-01-05.md - Image upload testing

Archive Materials (archive/)

• ARCHITECTURE.md - Original architecture documentation
• EDGE_FUNCTIONS.md - Edge functions reference
• DEPLOY_EDGE_FUNCTIONS.md - Edge function deployment
• Various logs and historical files

📋 Historical Documentation (Legacy)

Migration Records

• BACKEND_MIGRATION_RUNBOOK.md - Original migration runbook
• MIGRATION_PLAN.md - Initial migration planning
• MIGRATION_VALIDATION_REPORT.md - Final validation results

FCM Implementation

• FCM_DEPLOYMENT.md - Original deployment guide
• FCM_SETUP_GUIDE.md - Initial setup instructions
• ANDROID_FCM_TROUBLESHOOTING.md - Android-specific issues

E2EE Development

• E2EE_IMPLEMENTATION_COMPLETE.md - Original implementation notes

Platform Features

• CHAT_DELETE_DEPLOYMENT.md - Chat feature deployment
• MEDIA_EDITOR_MIGRATION.md - Media editor migration
• PRO_VIDEO_EDITOR_CONFIG.md - Video editor configuration

Reference Materials

• SUPABASE_REMOVAL_INTEL.md - Supabase cleanup information
• LINKS_FIX.md - Link resolution fixes
• LEGACY_README.md - Historical project information

---

Quick Reference

🔧 Development Setup

1. Backend: Go with Gin framework, PostgreSQL database
2. Frontend: Flutter with Riverpod state management
3. Infrastructure: Ubuntu VPS with Nginx reverse proxy
4. Database: PostgreSQL with PostGIS for location features

🔐 Security Features

• E2EE Chat: X3DH key agreement with AES-GCM encryption
• Authentication: JWT-based auth with refresh tokens
• Push Notifications: FCM for Web and Android
• Data Protection: Encrypted storage and secure key management

🚀 Deployment Architecture

Internet
    ↓
Nginx (SSL Termination, Static Files)
    ↓
Go Backend (API, Business Logic)
    ↓
PostgreSQL (Data, PostGIS)
    ↓
File System (Uploads) / Cloudflare R2

📱 Platform Support

• Web: Chrome, Firefox, Safari, Edge
• Mobile: Android (iOS planned)
• Notifications: Web push via FCM, Android native
• Storage: Local uploads + Cloudflare R2

---

Current Status

✅ Production Ready

• Backend API with full feature parity
• E2EE chat system (X3DH implementation)
• FCM notifications (Web + Android)
• Media upload and serving
• User authentication and profiles
• Post feed and search functionality

🚧 In Development

• iOS mobile application
• Advanced E2EE features (key recovery)
• Real-time collaboration features
• Advanced analytics and monitoring

📋 Planned Features

• Multi-device E2EE sync
• Advanced moderation tools
• Enhanced privacy controls
• Performance optimizations

---

Getting Started

For Developers

1. Clone Repository: git clone <repo-url>
2. Backend Setup: Follow BACKEND_MIGRATION_COMPREHENSIVE.md
3. Frontend Setup: Standard Flutter development environment
4. Database: PostgreSQL with required extensions
5. Configuration: Copy .env.example to .env and configure

For System Administrators

1. Server Setup: Ubuntu 22.04 LTS recommended
2. Dependencies: PostgreSQL, Nginx, Certbot
3. Deployment: Use provided deployment scripts
4. Monitoring: Set up logging and alerting
5. Maintenance: Follow troubleshooting guide for issues

For Security Review

1. E2EE Implementation: Review E2EE_COMPREHENSIVE_GUIDE.md
2. Authentication: JWT implementation and token management
3. Data Protection: Encryption at rest and in transit
4. Access Control: User permissions and data isolation

---

Support & Maintenance

Regular Tasks

• Weekly: Review logs and performance metrics
• Monthly: Update dependencies and security patches
• Quarterly: Backup verification and disaster recovery testing
• Annually: Security audit and architecture review

Emergency Procedures

1. Service Outage: Follow troubleshooting guide
2. Security Incident: Immediate investigation and containment
3. Data Loss: Restore from recent backups
4. Performance Issues: Monitor and scale resources

Contact Information

• Technical Issues: Refer to troubleshooting guide first
• Security Concerns: Immediate escalation required
• Feature Requests: Submit through project management system
• Documentation Updates: Pull requests welcome

---

Document Maintenance

Version Control

• All documentation is version-controlled with the main repository
• Major updates should reference specific code versions
• Historical documents preserved for reference

Update Process

1. Review: Regular review for accuracy and completeness
2. Update: Modify as features and architecture evolve
3. Test: Verify instructions and commands work correctly
4. Version: Update version numbers and dates

Contribution Guidelines

• Use clear, concise language
• Include code examples and commands
• Add troubleshooting sections for complex features
• Maintain consistent formatting and structure

---

Last Updated: January 30, 2026 Documentation Version: 1.0 Platform Version: 2.0 (Post-Migration) Next Review: February 15, 2026