{"id":39738275,"url":"https://github.com/saorsa-labs/communitas","last_synced_at":"2026-05-08T19:33:35.482Z","repository":{"id":310038849,"uuid":"1038421463","full_name":"saorsa-labs/communitas","owner":"saorsa-labs","description":"Communitas: A decentralized collaboration platform built on the Saorsa P2P ecosystem. Features four-word addresses, end-to-end encryption, and distributed storage","archived":false,"fork":false,"pushed_at":"2026-04-24T13:09:45.000Z","size":601132,"stargazers_count":5,"open_issues_count":3,"forks_count":2,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-24T14:34:42.403Z","etag":null,"topics":["collaboration","decentralized","desktop-app","distributed-storage","encryption","four-word-addresses","p2p","rust","tauri"],"latest_commit_sha":null,"homepage":null,"language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/saorsa-labs.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE-APACHE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":".github/SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-08-15T07:00:29.000Z","updated_at":"2026-04-24T13:09:48.000Z","dependencies_parsed_at":"2025-10-23T22:29:33.794Z","dependency_job_id":null,"html_url":"https://github.com/saorsa-labs/communitas","commit_stats":null,"previous_names":["dirvine/communitas","saorsa-labs/communitas"],"tags_count":88,"template":false,"template_full_name":null,"purl":"pkg:github/saorsa-labs/communitas","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/saorsa-labs%2Fcommunitas","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/saorsa-labs%2Fcommunitas/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/saorsa-labs%2Fcommunitas/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/saorsa-labs%2Fcommunitas/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/saorsa-labs","download_url":"https://codeload.github.com/saorsa-labs/communitas/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/saorsa-labs%2Fcommunitas/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32794716,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-08T08:22:46.396Z","status":"ssl_error","status_checked_at":"2026-05-08T08:22:45.650Z","response_time":54,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["collaboration","decentralized","desktop-app","distributed-storage","encryption","four-word-addresses","p2p","rust","tauri"],"created_at":"2026-01-18T11:10:34.086Z","updated_at":"2026-05-08T19:33:35.474Z","avatar_url":"https://github.com/saorsa-labs.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Communitas — The Unstoppable Collaboration Platform\n\n[![Release](https://img.shields.io/github/v/release/saorsalabs/communitas)](https://github.com/saorsalabs/communitas/releases/latest)\n[![Build](https://img.shields.io/github/actions/workflow/status/saorsalabs/communitas/ci.yml)](https://github.com/saorsalabs/communitas/actions)\n[![License](https://img.shields.io/badge/license-MIT%20OR%20Apache--2.0-blue.svg)](LICENSE-MIT)\n\n\u003e **A partition-tolerant, post-quantum secure, peer-to-peer collaboration network that works when the internet doesn't.**\n\n## Download\n\n**[Download Communitas v0.11.8 for macOS →](https://github.com/saorsalabs/communitas/releases/latest)**\n\n- **macOS (Universal)**: Supports Intel (x86_64) and Apple Silicon (M1/M2/M3/M4)\n- Signed and notarized by Apple\n- Auto-updates enabled\n\n## Why Communitas?\n\nMost modern collaboration tools (Slack, Discord, Google Docs) rely on a fragile assumption: **that you always have a perfect connection to a central server.** If the internet goes down, or a cable is cut, or a server outage occurs, you stop working.\n\n**Communitas is different.** It flips the model:\n\n1.  **Internet-Optional**: It prioritizes **local-first** connectivity. If the global internet fails, Communitas automatically switches to your local LAN, mesh network, or direct device-to-device links. Teams in the same building can keep chatting and editing documents even if the outside world is cut off.\n2.  **Post-Quantum Security**: We don't just use standard encryption. We use **NIST-standard Post-Quantum Cryptography** (ML-DSA, ML-KEM) to protect your identity and data against future threats that could break today's encryption.\n3.  **True Peer-to-Peer**: There are no central servers to hack, subpoena, or crash. **You are the server.** Your data lives on your device and syncs directly with your peers.\n4.  **Conflict-Free**: Using advanced **CRDTs (Conflict-free Replicated Data Types)**, you can edit documents offline or on a split network, and they will mathematically merge perfectly when you reconnect—no \"merge conflicts\" or lost work.\n\n---\n\n## Network Resilience Architecture\n\nCommunitas implements a hierarchical resilience model spanning process-local to global internet connectivity, with automatic degradation and recovery:\n\n- **Partition Tolerance**: Groups may fragment into isolated subnetworks and automatically reconverge when connectivity restores\n- **CRDT Synchronization**: Conflict-free replicated data types ensure eventual consistency across network partitions without coordination\n- **Post-Quantum Security**: ML-DSA-87/ML-DSA-65 signatures and ML-KEM-768 key exchange provide quantum-resistant cryptographic verification\n- **Multi-Transport Discovery**: Operates across loopback, LAN broadcast, NAT-traversed WAN, and direct public IP without central coordination\n- **Catastrophic Failure Recovery**: System continues operation in local-only mode during global infrastructure failures, automatically resuming WAN operations upon restoration\n\nTechnical implementation verified through comprehensive integration testing (watchdog monitoring, exponential backoff retry, and resource limit enforcement). See [Offline Handling](docs/architecture/offline-handling.md) and [Networking](docs/architecture/networking.md) for formal specifications.\n\n---\n\n## Quick Start\n\n### Prerequisites\n\n**All Platforms:**\n- Rust 1.85+\n- `dx` CLI 0.7.3 (`scripts/install_dx.sh` installs the pinned release)\n- Node.js 18+ (Tailwind/Vite asset bundling)\n\n**Windows Additional Requirements:**\n- Visual Studio 2022 Build Tools (C++ workload)\n- Edge WebView2 runtime (Tauri uses system WebView; installer enforces `minimumWebview2Version`)\n- See [Windows Build Guide](docs/development/windows-build.md) for detailed setup\n\n**Linux:**\n- GTK3/WebKitGTK runtime (Tauri WebView dependency)\n- Build essentials, CMake, and platform libraries\n- Refer to [docs/development/prerequisites.md](docs/development/prerequisites.md) for current dependency matrix\n\n### Development Setup\n```bash\ngit clone https://github.com/saorsalabs/communitas.git\ncd communitas\n\nscripts/install_dx.sh       # installs dx 0.7.3\n\n# Dioxus app development\ncd communitas-dioxus\ndx serve --platform desktop --hotpatch\n```\n\n### Testing\n```bash\n# UI smoke + lint\ncd communitas-dioxus\ndx check --platform desktop\n\n# Rust linting (strict policy)\ncargo clippy --all-features -- -D clippy::panic -D clippy::unwrap_used -D clippy::expect_used\n\n# Rust unit tests\ncargo test\n```\n\nTo simulate authentication failures during QA, set `COMMUNITAS_UI_FORCE_AUTH_ERROR=1` before running the UI (`COMMUNITAS_UI_FORCE_AUTH_ERROR=1 dx serve --platform desktop`). This flag exercises the error-handling paths wired into `communitas-ui-service`.\n\n\n---\n\n## Technical Capabilities\n\n### Partition Tolerance \u0026 Failure Recovery\n- **Network Partition Healing**: CRDT-based automatic state reconciliation across partition boundaries\n- **Internet Collapse Detection**: 10-second watchdog monitoring with automatic local-only mode activation\n- **Exponential Backoff Retry**: Jittered retry strategies prevent thundering herd during recovery (100ms → 60s backoff)\n- **Multi-Layer Connectivity**: Hierarchical degradation from global internet → NAT-traversed WAN → LAN broadcast → loopback\n- **Resource Limits (Partial Enforcement)**: Configurable peer connection limits (default: 50), memory caps (2GB), and connection timeouts; enforcement is being integrated across subsystems\n\n### Cryptographic Security (Post-Quantum)\n- **ML-DSA-87 Signatures**: NIST FIPS 204 quantum-resistant digital signatures for user identity (192-bit quantum security, Level 5)\n- **ML-DSA-65 Signatures**: NIST FIPS 204 signatures for site/gossip identity (128-bit quantum security, Level 3)\n- **ML-KEM-768 Key Exchange**: NIST FIPS 203 quantum-resistant key encapsulation for session establishment\n- **ChaCha20-Poly1305 AEAD**: Authenticated encryption for all data at rest and in transit\n- **Connection Words (four-word networking)**: Human-memorable encoding of IP:port for sharing peer connection info\n- **Zero Central Authority**: Fully decentralized trust model with cryptographic verification replacing DNS/PKI\n\n### CRDT-Based Eventual Consistency\n- **Yrs CRDT (v0.19)**: Conflict-free replicated data types for documents, messages, and shared state\n- **Operation-Based Synchronization**: Delta-based sync protocol minimizes bandwidth during partition healing\n- **Anti-Entropy Reconciliation**: Set-difference based background synchronization for automatic partition recovery with adaptive intervals\n- **Tombstone Compaction**: Configurable retention policies with background compaction tasks to bound CRDT growth\n- **Causal Consistency**: Vector clocks ensure causal ordering of operations across partitioned replicas\n- **Automatic Merge**: Conflict-free convergence without manual intervention or consensus protocols\n\n### Decentralized Network Architecture\n- **QUIC Transport**: saorsa-gossip-transport (UdpTransportAdapter on ant-quic v0.18)\n- **Gossip Overlay (saorsa-gossip v0.5.0)**: HyParView membership + SWIM failure detection + Plumtree broadcast\n- **SWIM Failure Detection**: Complete protocol with K-peer probing, indirect probes, and suspect-to-dead state transitions\n- **Signed Presence Beacons**: ML-DSA signed presence broadcasts with per-peer rate limiting\n- **Peer Scoring**: Quality-based peer selection for Plumtree broadcast tree optimization\n- **FOAF Discovery**: Friend-of-a-friend peer discovery without DHT or global indexing\n- **Rendezvous Shards**: 65,536-shard distributed discovery system for global user location\n- **Prometheus Metrics**: `/metrics` endpoint exposing peer counts, membership views, CRDT state, and uptime gauges\n- **No Single Point of Failure**: Operates without bootstrap nodes after initial peer cache seeding\n\n### Entity-Based Collaboration\n- **Individuals**: Personal identity with ML-DSA-87 keypairs, encrypted local storage\n- **Groups**: CRDT-synchronized shared state, partition-tolerant membership, member management (add/remove/roles)\n- **Organizations**: Multi-channel hierarchy with admin delegation\n- **Projects**: Version-controlled workspaces with conflict-free document merging\n- **Channels**: Topic-scoped pubsub with message anti-entropy\n- **Entity Tabs**: Board, Chat, Call, Canvas, Drive, Documents, and Details views per entity type\n- **Messaging**: Message editing, deletion with confirmation, pinning, threading, inline quotes/replies, and message search\n- **Reactions**: Emoji reactions with quick-reaction bar and full emoji picker (categorized with search)\n- **Markdown Rendering**: Full in-message markdown with syntax highlighting\n- **@Mentions**: Autocomplete mention picker with inline user tagging\n- **Typing Indicators**: Real-time per-user typing status in channels\n- **Presence**: Online/away/offline status badges per peer\n- **Onboarding Gate**: First-run flow that auto-installs and starts x0xd if not present\n- **Member Management**: Add/remove members with role display and permission controls\n\n### UI Components (Dioxus)\n- **VirtualList**: Windowed rendering for large datasets with configurable item heights and smooth scrolling\n- **SearchBar**: Global and contextual search with debounced input\n- **FilterChips**: Composable filter controls for lists and feeds\n- **Pagination**: Page-based navigation for large result sets\n- **ConfirmDialog**: Modal confirmation for destructive actions (delete, leave, remove member)\n- **ErrorBanner**: Contextual error recovery with retry actions\n- **Loading States**: Skeleton screens and spinners for async data fetching\n- **Empty States**: Contextual guidance when lists or views have no content\n\n---\n\n## Documentation\n\n### Product \u0026 Architecture\n- **[App Specification](docs/APP_SPECIFICATION.md)**: Product requirements and UX expectations\n- **[Architecture Overview](docs/architecture/README.md)**: System architecture (Dioxus + Rust core + gossip)\n- **[CRDT System](docs/architecture/crdt-system.md)**: Yrs document model and sync\n- **[Gossip Protocol](docs/architecture/gossip-protocol.md)**: P2P membership + dissemination\n- **[Networking](docs/architecture/networking.md)**: QUIC transport, NAT traversal, resilience\n- **[Offline Handling](docs/architecture/offline-handling.md)**: Auto-queue and recovery flow\n- **[Security](docs/architecture/security.md)**: PQC, vaults, threat model\n- **[Storage](docs/architecture/storage.md)**: Virtual disks and content addressing\n- **[ADR Index](docs/adr/README.md)**: Architecture decisions\n\n### API Reference\n- **[API Overview](docs/api/README.md)**: Core API surfaces\n- **[Core API](docs/api/core-api.md)**: Rust core library API\n\n### Deployment \u0026 Ops\n- **Testnet Deployment**: See [saorsa-testnet](https://github.com/saorsa-labs/saorsa-testnet) repository\n- **[Infrastructure](docs/infrastructure/INFRASTRUCTURE.md)**: Infra layout and environments\n\n### Development\n- **[Contributing Guide](CONTRIBUTING.md)**: How to contribute\n- **[Windows Build](docs/development/windows-build.md)**: Windows setup notes\n- **[CLAUDE.md](CLAUDE.md)**: Project context for LLM helpers\n\n---\n\n## Project Structure\n\n### Applications\n- **[communitas-dioxus/](communitas-dioxus/)**: Cross-platform Dioxus + Tauri application (desktop-first, experimental mobile runners)\n- **[communitas-apple/](communitas-apple/)**: Native macOS Swift application (SwiftUI, requires x0xd)\n\nLegacy thin-client assets remain in the archive solely for historical reference.\n\n### Core Libraries\n- **[communitas-core/](communitas-core/)**: Shared Rust business logic and P2P networking\n- **[communitas-kanban/](communitas-kanban/)**: CRDT-based collaborative Kanban system\n- **[communitas-ui-api/](communitas-ui-api/)**: Strongly-typed UI service trait definitions\n- **[communitas-ui-service/](communitas-ui-service/)**: Shared Rust UI service implementations (ADR-019)\n- **[communitas-x0x-client/](communitas-x0x-client/)**: x0xd daemon discovery, HTTP client, and WebSocket transport\n\n### Documentation\n- **[docs/](docs/)**: Comprehensive project documentation\n  - **[architecture/](docs/architecture/)**: System architecture documentation\n  - **[api/](docs/api/)**: API reference documentation\n  - **[development/](docs/development/)**: Development setup and standards\n  - **[testing/](docs/testing/)**: Multi-node testing and scenarios\n  - **[infrastructure/](docs/infrastructure/)**: Deployment and infrastructure\n  - **[adr/](docs/adr/)**: Architecture decision records\n\n### Key Commands\n```bash\n# Dioxus: development with hot reload\ncd communitas-dioxus\ndx serve --platform desktop --hotpatch\n\n# Dioxus: production bundle\ndx bundle --platform desktop\n# Experimental mobile bundles (Android/iOS)\ndx bundle --platform android\n\n# Swift (macOS): open in Xcode\nopen communitas-apple/Package.swift\n\n# Quality Checks\ndx check --platform desktop \u0026\u0026 cargo clippy --all-features\n```\n\n---\n\n## Deployment Options\n\nCommunitas supports multiple deployment scenarios for different use cases:\n\n### Dioxus Application (End Users — Cross-Platform)\nFull-featured cross-platform application (desktop GA, experimental Android/iOS runners).\n```bash\ncd communitas-dioxus\ndx bundle --platform desktop\n# optional mobile targets (stability varies)\ndx bundle --platform android\ndx bundle --platform ios\n```\nSee [communitas-dioxus/](communitas-dioxus/) for details.\n\n### Swift Application (Native macOS)\nNative macOS SwiftUI app targeting macOS 14+. Connects to x0xd for all networking.\n```bash\n# Open in Xcode\nopen communitas-apple/Package.swift\n\n# Build from command line\nswift build --package-path communitas-apple\n```\nBoth apps discover the running x0xd daemon from `~/Library/Application Support/x0x/api.port` and `api-token`.\n\n---\n\n## Network \u0026 Identity\n\nIdentity is the public key (pubkey_hex). Four-word networking is used only to encode\nconnection endpoints (IP:port) for sharing between peers.\n\n### x0x Daemon Integration\nBoth the Dioxus and Swift apps talk to a local x0xd daemon for all networking. The daemon writes two files at startup:\n\n- `~/Library/Application Support/x0x/api.port` — the `host:port` the API listens on (e.g. `127.0.0.1:12700`)\n- `~/Library/Application Support/x0x/api-token` — a 64-character hex Bearer token required for authenticated endpoints\n\nBoth apps discover these at runtime via `communitas-x0x-client` (Rust) or `X0xClient` (Swift). If x0xd is not installed or not running, the onboarding gate will prompt the user to install/start it.\n\n### Connection Words Example\n```rust\n// Share a connection address with a friend (IP:port encoded as words)\nlet connection_words = get_my_connection_words().await?;\n// → \"ocean-blue-eagle-star\"\n\n// Friend uses the connection words to dial directly\nconnect_to_peer(\u0026connection_words).await?;\n```\n\n### Network Participation\n- **Desktop Nodes**: Full participants with the Dioxus/Tauri UI (macOS/Linux/Windows)\n- **macOS Nodes**: Native SwiftUI app backed by x0xd\n- **Mobile Nodes**: Experimental Dioxus builds on Android/iOS (stability pending upstream Tauri updates)\n\n---\n\n## Security \u0026 Cryptographic Guarantees\n\n### Post-Quantum Cryptographic Primitives\n- **NIST FIPS 204 (ML-DSA-87/65)**: Module-Lattice-Based Digital Signature Algorithm with 192-bit (user) and 128-bit (site) quantum security levels\n- **NIST FIPS 203 (ML-KEM-768)**: Module-Lattice-Based Key Encapsulation Mechanism with 192-bit classical security\n- **ChaCha20-Poly1305**: Authenticated encryption with associated data (AEAD) for session encryption\n- **BLAKE3**: Cryptographic hash function for content addressing and integrity verification\n- **Keyring Integration**: Platform keychain storage (macOS Keychain, Windows Credential Manager, Linux Secret Service)\n\n### Threat Model \u0026 Mitigations\n- **Man-in-the-Middle**: Prevented by ML-DSA signature verification and ML-KEM authenticated key exchange\n- **Quantum Computing**: Post-quantum algorithms resist Shor's and Grover's algorithms\n- **Replay Attacks**: Nonce-based message authentication and temporal ordering\n- **Sybil Attacks**: Proof-of-work on identity creation with rate limiting\n- **Eclipse Attacks**: Multiple bootstrap sources with FOAF-based peer discovery\n- **Network Partitioning**: CRDT eventual consistency ensures state convergence without coordination\n\n### Decentralization Properties\n- **No DNS Dependency**: Four-word cryptographic identities replace hierarchical naming\n- **No PKI/Certificate Authorities**: Self-sovereign identity with cryptographic verification\n- **No Blockchain Consensus**: CRDT conflict-free convergence without global coordination\n- **No Central Servers**: Peer-to-peer gossip overlay with distributed state replication\n- **Partition Tolerance**: CAP theorem AP system (availability + partition tolerance over consistency)\n\n---\n\n## License\n\nDual-licensed under **MIT** or **Apache-2.0** at your option. Commercial licensing also available via [Saorsa Labs](mailto:saorsalabs@gmail.com).\n\n---\n\n## Contributing\n\n1. **Code Style**: Follow existing patterns and conventions\n2. **Commit Format**: Conventional commits (`feat:`, `fix:`, `docs:`)\n3. **Quality Gates**: All code must pass Dioxus (`dx check`) + Rust linting\n4. **Testing**: Include tests for new functionality\n\n### Development Standards\n- **No Panics**: Rust code forbids `unwrap`/`expect`/`panic!` in production (enforced by clippy)\n- **Type Safety**: Rust-first surfaces with strict clippy/fmt enforcement\n- **Test Coverage**: Comprehensive integration tests covering resilience, messaging, and membership features\n- **Security First**: Post-quantum cryptography and secure defaults\n- **Partition Tolerance**: All features must operate correctly during network partitions\n\n---\n\n## Research \u0026 Standards Compliance\n\n### Cryptographic Standards\n- **[NIST FIPS 204](https://csrc.nist.gov/pubs/fips/204/final)**: Module-Lattice-Based Digital Signature Standard (ML-DSA)\n- **[NIST FIPS 203](https://csrc.nist.gov/pubs/fips/203/final)**: Module-Lattice-Based Key-Encapsulation Mechanism Standard (ML-KEM)\n- **[RFC 8439](https://www.rfc-editor.org/rfc/rfc8439)**: ChaCha20 and Poly1305 for IETF Protocols\n\n### Distributed Systems Theory\n- **CAP Theorem**: Prioritizes availability and partition tolerance (AP system)\n- **CRDT Research**: Operation-based CRDTs with causal consistency (Shapiro et al.)\n- **Gossip Protocols**: HyParView (Leitao et al.), SWIM with indirect probes (Das et al.), Plumtree with peer scoring (Leitao et al.)\n\n### Network Resilience Testing\n- **Partition Tolerance**: Verified through integration tests with simulated network failures\n- **Exponential Backoff**: Jittered retry strategies prevent cascading failures\n- **Resource Limits**: Configured connection limits (50 peers), memory caps (2GB), timeouts (30s); enforcement is in progress\n\n---\n\nCommunitas represents a new class of partition-tolerant P2P systems combining post-quantum cryptography, CRDT-based eventual consistency, and catastrophic failure resistance. The architecture prioritizes operational continuity during network degradation while maintaining cryptographic security guarantees.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsaorsa-labs%2Fcommunitas","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsaorsa-labs%2Fcommunitas","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsaorsa-labs%2Fcommunitas/lists"}