Epic 1.2: OrbitDB Data Management

[ldaIas]

Overview

This epic builds on the IPFS foundation from Epic 1.1 to implement stateful data management using OrbitDB. OrbitDB provides a distributed database layer on top of IPFS, enabling multiple users to create, update, and synchronize activity posts across the network.

Problem Statement

While IPFS allows us to store immutable content, we need a way to:

• Manage collections of posts that can be discovered by other users
• Handle post state changes (creation, RSVPs, expiration)
• Synchronize data across multiple clients in real-time
• Maintain data integrity in a distributed environment

Solution

OrbitDB provides a peer-to-peer database built on IPFS that gives us:

• Distributed databases: Multiple users can read/write to shared databases
• Automatic synchronization: Changes propagate across the network
• Conflict resolution: Built-in handling of concurrent updates
• IPFS integration: Seamless integration with our existing Helia setup

Technical Requirements

Core Functionality

• Initialize OrbitDB instance using existing Helia node
• Create and manage activity post databases
• Implement post creation, reading, and listing operations
• Handle database synchronization across multiple clients

Data Schema

<Original>
Activity posts will include:

{
  "id": "unique-post-id",
  "type": "activity",
  "title": "Grab coffee and work",
  "description": "Looking for someone to co-work at Blue Bottle",
  "location": "Blue Bottle Coffee, Downtown",
  "proposedTime": "2025-07-28T14:00:00Z",
  "creator": "user-id",
  "maxParticipants": 2,
  "genderBalance": "balanced",
  "category": "coffee",
  "status": "active",
  "createdAt": "2025-07-27T20:00:00Z",
  "expiresAt": "2025-07-28T14:00:00Z"
}

Post implementation design:
#49 (comment)

Success Criteria

• Multiple browser instances can create and view the same posts
• Posts synchronize reliably across the network
• Database operations integrate smoothly with Elm UI
• No data loss or corruption during sync operations

Integration with Existing Code

• Builds on Helia IPFS node from Epic 1.1
• Uses existing Elm port architecture for JS interop
• Maintains same UI patterns and error handling approaches

Future Considerations

This epic establishes the foundation for:

• User profiles and authentication (Epic 2.1)
• RSVP and interest tracking (Epic 2.3)
• Direct messaging between users (Epic 3.1)
• Geographic filtering of posts (Epic 1.4)

Risk Mitigation

• OrbitDB is a mature library with good documentation
• Test synchronization thoroughly with multiple browser instances
• Implement proper error handling for network partitions
• Plan for database migration if schema changes are needed

Definition of Done

• OrbitDB successfully integrated with Helia
• Activity posts can be created and stored in distributed database
• Posts synchronize across multiple clients reliably
• All functionality accessible through Elm UI via ports
• Comprehensive error handling for database operations
• Basic post listing and discovery functionality working