Skip to content

ARCHITECTURE.md

Latest commit

 

History

History
211 lines (165 loc) · 5.25 KB

ARCHITECTURE.md

File metadata and controls

211 lines (165 loc) · 5.25 KB

Architecture Documentation

System Overview

The Real-Time Collaborative Document Editor is a distributed web application that enables multiple users to edit documents simultaneously with real-time synchronization. The system is built using a microservices architecture with clear separation between frontend, backend, and data layers.

Component Architecture

Frontend Layer

Technology Stack:

  • React 18.3 for UI components
  • Quill.js for rich text editing
  • WebSocket API for real-time communication
  • Axios for REST API calls

Key Components:

  • App.js: Main application router and entry point
  • TextEditor.js: Core editor component with WebSocket integration
  • Home.js: Landing page component

Responsibilities:

  • User interface rendering
  • Real-time document editing
  • WebSocket connection management
  • Document change broadcasting
  • Auto-save functionality

Backend Layer

Technology Stack:

  • FastAPI for REST and WebSocket endpoints
  • Python WebSockets for real-time communication
  • Boto3 for AWS service integration

Key Modules:

  • main.py: FastAPI application initialization
  • api/database_api.py: DynamoDB CRUD operations
  • api/socket_api.py: WebSocket endpoint handlers
  • api/SocketManager.py: WebSocket connection pool management
  • schema/Document.py: Data models and validation

Responsibilities:

  • REST API endpoint handling
  • WebSocket connection management
  • Document persistence operations
  • Real-time change broadcasting
  • Request validation and error handling

Data Layer

Technology:

  • AWS DynamoDB (NoSQL database)

Schema:

  • Table: SocketDocuments
  • Partition Key: id (String) - Document unique identifier
  • Attributes:
    • id: Document ID (UUID)
    • Data: Document content (JSON string)

Communication Patterns

REST API Communication

Client → Nginx → Backend → DynamoDB
Client ← Nginx ← Backend ← DynamoDB

Endpoints:

  • GET /api/database/documents/get/{id}: Retrieve document
  • GET /api/database/documents/getorcreate/{id}: Get or create document
  • POST /api/database/documents: Create new document
  • PUT /api/database/documents/{id}: Update document

WebSocket Communication

Client ←→ WebSocket ←→ Backend
              ↓
         SocketManager
              ↓
    Active Connections Pool

Message Types:

  1. get-document: Request document from database
  2. changes-received: Broadcast changes to other users
  3. save-changes: Persist document to database
  4. update-document: Receive updates from other users
  5. db-document: Receive document from database

Data Flow

Document Loading Flow

1. User opens document → Frontend connects to WebSocket
2. Frontend sends "get-document" message
3. Backend queries DynamoDB
4. Backend sends document data via WebSocket
5. Frontend renders document in Quill editor

Document Editing Flow

1. User types → Quill detects change
2. Frontend sends "changes-received" with delta
3. Backend broadcasts to all connected clients (except sender)
4. Other clients receive "update-document" message
5. Other clients apply delta to their Quill instance

Document Saving Flow

1. Auto-save timer triggers (every 2 seconds)
2. Frontend sends "save-changes" with full document content
3. Backend updates DynamoDB
4. Changes persisted to database

Scalability Considerations

Current Architecture

  • Single backend instance
  • In-memory WebSocket connection pool
  • Direct DynamoDB access

Potential Improvements

  • Horizontal scaling with multiple backend instances
  • Redis for shared WebSocket connection state
  • DynamoDB read/write capacity optimization
  • Load balancing across multiple instances
  • CDN for static frontend assets

Security Considerations

Current Implementation

  • CORS middleware configured
  • Environment variable-based AWS credentials
  • WebSocket connection validation

Recommended Enhancements

  • User authentication (JWT tokens)
  • Document access control
  • Rate limiting
  • Input sanitization
  • HTTPS/TLS encryption
  • AWS IAM role-based access

Deployment Architecture

Internet
   ↓
EC2 Instance / Server
   ↓
Docker Compose
   ├── Nginx Container (Port 80)
   ├── Frontend Container (Port 3000)
   └── Backend Container (Port 8000)
         ↓
    AWS DynamoDB

Performance Metrics

Expected Performance

  • WebSocket latency: < 100ms
  • Document load time: < 500ms
  • Auto-save interval: 2 seconds
  • Concurrent users per document: Tested up to 10+

Optimization Opportunities

  • Implement delta compression
  • Add document caching layer
  • Optimize DynamoDB query patterns
  • Implement connection pooling
  • Add CDN for static assets

Error Handling

Frontend

  • WebSocket reconnection logic
  • Error boundaries for React components
  • User-friendly error messages
  • Graceful degradation

Backend

  • Try-catch blocks for all operations
  • HTTP status code standardization
  • Detailed error logging
  • Database error handling

Monitoring and Logging

Current Logging

  • Python logging module
  • Console-based logging
  • Debug and info level logs

Recommended Monitoring

  • Application performance monitoring (APM)
  • Error tracking (Sentry, etc.)
  • WebSocket connection metrics
  • DynamoDB performance metrics
  • User activity analytics