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

8.2 KiB
Raw Blame History

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