Locorda — the rope that connects and weaves local data together.
⚠️ PROJECT UNDER CRITICAL ASSESSMENTIMPORTANT: This project is currently undergoing a fundamental reassessment of its direction and viability. Active development is paused while critical questions about the architecture and approach are being evaluated.
Assessment Status:
- 🔴 Project continuation decision pending - See STATUS.md for informal assessment
- 🔴 Specification outdated - Implementation has diverged significantly from documented spec
- 🔴 Not recommended for production use - Architecture under review
For Current Status:
- Informal assessment: STATUS.md - Critical reflections and analysis
- Formal decision record: ADR-0004 - Project assessment ADR
If you're interested in this project's goals or considering similar work, please review the status documents first.
⚠️ EARLY EXPERIMENTAL VERSION - SPECIFICATION OUTDATEDWARNING: This specification represents an early experimental design that has been superseded during actual implementation of the locorda libraries. The documented architecture, algorithms, and APIs do not reflect the current implementation and require significant updates.
Current Status:
- ❌ Specification is NOT implementation-ready - contains theoretical concepts that proved impractical
- ❌ Examples and code patterns do not match the actual library implementation
- ❌ Architecture decisions have evolved significantly during development
- 🚧 Active implementation work is discovering and resolving specification gaps and inconsistencies
If you're considering using or implementing this specification: Please contact the project maintainers first to understand the current state and planned updates. Do not rely on the documented specification for production use.
A comprehensive specification and Dart/Flutter implementation for building offline-first applications that sync seamlessly with passive storage backends like Solid Pods, Google Drive, or any file storage system. Users bring their own backend, developers get easy cross-device sync.
This project addresses the fundamental challenge of creating applications that are both conflict-free (using CRDT algorithms) and semantically interoperable (using standard RDF vocabularies) while maintaining high performance regardless of dataset size. The system works with passive storage backends, with Solid Pods being the primary focus but not the only option.
- 🔄 Conflict-Free Synchronization: State-based CRDT algorithms ensure safe collaboration without coordination
- 🌐 Semantic Interoperability: All data stored as clean, standard RDF for maximum compatibility
- ⚡ Performance at Scale: Flexible indexing (Full vs. Grouped) and fetch strategies (Prefetch vs. OnDemand) handle datasets from 100 to 100,000+ resources with smart sharding and header properties
- 📱 Offline-First: Full offline functionality with sync when connectivity is available
- 🔒 Privacy-Preserving: Maintains user data ownership with pluggable access control systems
The complete architecture is documented in spec/docs/ARCHITECTURE.md.
The Dart implementation is in early development. The current focus is on establishing the core architecture and interfaces.
📋 For package structure, current status, and development workflow, see IMPLEMENTATION.md
This specification is designed to be language-agnostic. The Dart implementation serves as a reference, but the architecture supports implementations in JavaScript, Python, Java, etc.
This repository serves dual purposes:
Complete architectural documentation for building CRDT-enabled applications with passive storage backends across any programming language. The specification lives in the spec/ directory and includes:
- Complete CRDT-RDF architecture with formal vocabulary definitions
- Language-agnostic design patterns for implementers
- Performance analysis and optimization strategies
- Interoperability contracts for cross-application compatibility
A multipackage Dart library that aims to become production-ready for real-world applications. The implementation will provide:
- Full-featured library for building collaborative applications with passive storage backends
- Complete API coverage of the specification's capabilities
- Performance-optimized implementation suitable for mobile and web applications
- Reference example for implementers in other languages
Note: Implementation is currently in early development - the specification came first to ensure a solid foundation.
📋 For implementation details, package structure, and development workflow, see IMPLEMENTATION.md
| Document | Purpose | Audience |
|---|---|---|
| ARCHITECTURE.md | Complete specification | Implementers, standards bodies |
| PERFORMANCE.md | Performance analysis & optimization | Developers, system architects |
| ERROR-HANDLING.md | Error scenarios & recovery | Implementation teams |
| FUTURE-TOPICS.md | Roadmap & open questions | Contributors, researchers |
| Resource | Purpose | Audience |
|---|---|---|
| 📋 RDF Vocabularies & Mappings | Web access to RDF vocabularies and semantic mappings | Developers, semantic web tools |
| Document | Purpose | Audience |
|---|---|---|
| IMPLEMENTATION.md | Package structure & development workflow | Dart developers & contributors |
| CLAUDE.md | Development guidelines | Contributors to Dart implementation |
| examples/ | Usage patterns & API examples | Dart developers |
The framework uses a 4-layer architecture:
- Data Resource Layer: Clean RDF resources using standard vocabularies
- Merge Contract Layer: Public CRDT rules for conflict resolution
- Indexing Layer: Efficient change detection and performance optimization
- Sync Strategy Layer: Application-specific performance trade-offs
# Example: Recipe with automatic conflict resolution
<#recipe> a schema:Recipe;
schema:name "Tomato Soup"; # LWW-Register (last writer wins)
schema:keywords "vegan", "soup"; # OR-Set (additions/removals merge)
schema:cookTime "PT30M" . # Immutable (cannot be changed)
<> a sync:ManagedDocument;
sync:isGovernedBy <https://app.example/contracts/recipe-v1>;
foaf:primaryTopic <#recipe> .This work aligns with and wants to eventually contribute to:
- W3C CRDT for RDF Community Group
- RDF and Linked Data principles
- Solid Protocol ecosystem (as one supported backend)
⚠️ Note: The specification status below does not reflect that the documented specification is outdated. See warning at top of document.
| Component | Status | Notes |
|---|---|---|
| Specification | Superseded during implementation - major revision needed | |
| Dart Library | 🚧 In Development | Implementation revealing specification gaps |
| JavaScript Library | 📋 Future | Awaiting specification stabilization |
- Issues & Suggestions: GitHub Issues
- Architectural Discussions: W3C CRDT for RDF Community Group
- Pull Requests: Documentation improvements and clarifications welcome
- Dart Implementation: See IMPLEMENTATION.md for package structure and development workflow
- Tests: Specification compliance tests across package directories
- Examples: Real-world usage patterns in
examples/
Interested in implementing this specification in other languages? We'd love to collaborate! The architecture is designed to be language-agnostic.
This project is licensed under the MIT License - see the LICENSE file for details.
If you use this work in academic research, please cite:
@misc{kalaß2025locorda,
title={locorda: Passive Storage Collaborative RDF Sync System},
author={Klas Kalaß},
year={2025},
url={https://github.com/klaaskalass/locorda}
}- Discussions: GitHub Discussions
- W3C Community Group: CRDT for RDF
- Matrix Chat: #locorda:matrix.org (planned)
This specification was developed with assistance from large language models (Claude, Gemini) for:
- Research assistance: Exploring CRDT literature, Solid ecosystem standards, and related work
- Technical writing and editing: Improving clarity, consistency, and professional formatting
- Architecture review: Identifying gaps, inconsistencies, and improvement opportunities
- Documentation structure: Organizing complex technical concepts for multiple audiences
Human oversight: All architectural decisions, technical approaches, and conceptual frameworks remain under full human authorship and responsibility. AI tools served as sophisticated writing and analysis assistants, not as sources of technical authority.
Quality assurance: The specification's technical validity comes from careful review, implementation experience, and community feedback - not from AI generation.
This project bridges the gap between theoretical CRDT research and practical application development with passive storage backends, enabling a new generation of truly collaborative, interoperable applications.