💬 cloudchat-v2

Next-generation messaging backend — DynamoDB, Serverless, and Python

cloudchat-v2 is the production-ready successor to cloudchat-lite. It implements a modern messaging backend, inspired by WhatsApp-scale design principles.

This repository focuses exclusively on the backend, with a placeholder for a future React client.

📑 Table of Contents

• ✨ Why this exists
• 🚀 Core Capabilities
• 🏗 Tech Stack
• 🧱 Architecture Overview
• ⚡ Real-Time Messaging Architecture
• 🔌 WebSocket Presence & Connection Lifecycle
• 📦 Quick Start (Optional)
• 🧪 Testing
• ⚡ Real-Time Messaging (Live Demo)
• 🏷️ License

✨ Why this exists

cloudchat-lite (v1) was a solid first iteration with a clean single-table DynamoDB design. As the project evolved and access patterns were examined more deeply, two schema issues emerged that would limit correctness and scalability in a real messaging workload.

This repository (cloudchat-v2) exists to correct those specific issues while preserving the original design philosophy.

🔮 v1 → v2 Schema Evolution

• Message ordering v1 relied on timestamp-based sort keys, which break under concurrent writes. v2 uses ULID-based ordering for guaranteed uniqueness and correct time sequencing.

• Inbox ordering v1’s GSI design prevented server-side sorting and pagination. v2 introduces a time-ordered inbox GSI.

v2 preserves the original single-table design and access philosophy — it is a targeted schema correction, not a rewrite.

📌 For the full breakdown, see docs/schema-evolution.md

🔁 Language Transition (v1 → v2)

While cloudchat-lite (v1) was implemented in Node.js, cloudchat-v2 was intentionally rebuilt in Python from the ground up.

Rather than reusing existing code, the v2 backend was rewritten entirely to:

• Practice production-grade async Python
• Explore Python’s ecosystem for serverless and data modeling
• Validate that the original design principles translate cleanly across languages

Only the architecture and access patterns were carried forward — all implementation details were rethought and reimplemented.

🚀 Core Capabilities

Message Write Path

• ULID-ordered message writes (collision-proof)
• Atomic metadata updates for all participants
• Correct inbox ordering guaranteed

Inbox (List Conversations)

• GSI sorted by <LastTimestamp>#<conversation_id>
• Server-side ordering and pagination
• Stable under concurrent message writes

Conversation History

• Query by conversation ID
• ULID-ordered messages
• Efficient pagination

Real-Time Delivery

• Online fanout via WebSockets
• Presence modeled as TTL-based soft state
• Decoupled from message persistence

🏗 Tech Stack

Technology	Usage
Python 3.13+	Core application language
AWS Lambda	Serverless compute runtime
AWS API Gateway	HTTP + WebSocket entry point
WebSockets (APIGW)	Real-time message delivery
DynamoDB (single table)	Messages, metadata, and presence (system of record)
DynamoDB Local	Local validation of single-table design and read receipts POC
DynamoDB Streams	Change data capture for real-time fanout
SNS	Decoupled event distribution for message delivery
aioboto3	Async DynamoDB client
Pydantic v2	Data validation and serialization
pytest	Testing framework
UV	Dependency and environment management
AWS SAM	Infrastructure-as-code, build, and deployment
IAM	Least-privilege access control between services

🧱 Architecture Overview

Serverless Backend

Client (future React)
      |
API Gateway (HTTP)
      |
Lambda Handlers
      |
DynamoDB (Single Table)
   ├─ Message rows
   └─ Per-user conversation metadata for n-way chats
        ↳ Inbox GSI (sorted by recency)

Design Highlights

• Fully async Python handlers
• DynamoDB schema designed for high write throughput

⚡ Real-Time Messaging Architecture

Implemented two real-time delivery pipelines to demonstrate scalable, decoupled fanout patterns.

Option 1 — Direct DDB Stream Fanout

• DynamoDB Streams trigger a Lambda on new messages

• Lambda:

  • Hydrates message from DynamoDB
  • Resolves online recipients via Presence table
  • Sends directly over WebSocket

• Simple, low latency, tightly coupled

Option 2 — SNS-Based Fanout (Current)

• DDB Stream Lambda publishes MessageSent events to SNS

• SNS consumer Lambda:

  • Hydrates message from DynamoDB
  • Resolves online recipients via Presence table
  • Fans out to active WebSocket connections

Benefits

• Independent scaling
• Failure isolation and retries
• Extensible to analytics, notifications, moderation

Why SNS?

• Clean separation of persistence vs delivery
• Stream processing never blocks on fanout
• Proven production chat pattern

┌────────┐   ┌──────────────┐   ┌────────────────┐   ┌───────────────────┐   ┌──────────────────┐
│ Client │ → │ API / Lambda │ → │ DDB (Messages) │ → │ DDB Stream Lambda │ → │      SNS         │
│        │   │(send message)│   │                │   │  (publish event)  │   │ MessageSentTopic │
└────────┘   └──────────────┘   └────────────────┘   └───────────────────┘   └──────────────────┘

┌────────────────────────────────┐   ┌────────────────────────┐   ┌──────────────────┐
│     SNS Consumer Lambda        │ → │     WebSocket API      │ → │  Online Clients  │
│  - hydrate message from DDB    │   │                        │   │                  │
│  - lookup presence             │   └────────────────────────┘   └──────────────────┘
│  - fanout to connections       │
└────────────────────────────────┘

🔌 WebSocket Presence & Connection Lifecycle

Presence Refresh

        ┌─────────┐
        │  Client │
        └────┬────┘
             │  connect / heartbeat
             v
   ┌──────────────────┐
   │  WebSocket API   │
   └─────────┬────────┘
             │
             │ refresh ttl
             v
 ┌────────────────────────┐
 │ DDB (Presence / TTL)   │
 │  ttl = now + interval  │
 └────────────────────────┘

Presence Leverage

 ┌────────────────────────┐
 │   Fanout / Send Logic  │
 └──────────┬─────────────┘
            │
            │ check ttl > now
            v
  ┌───────────────────┐
  │   WebSocket API   │
  └─────────┬─────────┘
            │
            │ 410 Gone
            v
  ┌───────────────────────────┐
  │    Connection Cleanup     │
  │ (defensive / future hook) │
  └───────────────────────────┘

IAM permissions are tightly scoped so Lambdas can only be invoked by the specific WebSocket API routes.
WebSockets are used for delivery only; DynamoDB TTL-based presence is the source of truth.

📦 Quick Start (Optional)

cd backend
uv sync
sam build
sam deploy --guided

This provisions:

• Lambda functions
• DynamoDB message table (single-table design)
• DynamoDB presence table (TTL-based)
• Inbox GSI (sorted by recency)
• API Gateway (HTTP + WebSocket)
• IAM roles and permissions

📌 AWS credentials and SAM CLI required.

🧪 Testing

The backend includes a focused test suite covering core correctness and edge cases:

• Unit tests

  • DynamoDB key construction and schema models
  • ULID ordering and timestamp extraction
  • Message fanout recipient parsing

• Integration tests

  • TTL-based presence behavior

Tests are written using pytest with strict async validation.

cd backend
uv run pytest -q tests
.........................  [100%]
25 passed in 6.60s

✅ AWS Integration Validation

Manual AWS test scripts were used to validate live DynamoDB access patterns, Lambda execution, inbox ordering, and real-time fanout behavior against deployed infrastructure.

These scripts live under:

backend/aws_tests/

⚡ Real-Time Messaging (Live Demo)

The system supports live WebSocket message delivery to online users, driven by DynamoDB Streams and SNS-based fanout.

Messages are delivered asynchronously; ordering is preserved at the data layer and resolved client-side.

🏷️ License

MIT — free for personal and professional use.