# 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](./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](./FCM_COMPREHENSIVE_GUIDE.md)**
Comprehensive Firebase Cloud Messaging setup and troubleshooting guide for both Web and Android platforms.

#### **[BACKEND_MIGRATION_COMPREHENSIVE.md](./BACKEND_MIGRATION_COMPREHENSIVE.md)**
Complete migration documentation from Supabase to self-hosted Golang backend, including planning, execution, and validation.

#### **[TROUBLESHOOTING_COMPREHENSIVE.md](./TROUBLESHOOTING_COMPREHENSIVE.md)**
Comprehensive troubleshooting guide covering authentication, notifications, E2EE chat, backend services, and deployment issues.

#### **[DEVELOPMENT_COMPREHENSIVE.md](./DEVELOPMENT_COMPREHENSIVE.md)**
Complete development and architecture guide, covering design patterns, code organization, testing strategies, and performance optimization.

#### **[DEPLOYMENT_COMPREHENSIVE.md](./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