mindoodb
Architecture

Scalable, secure, distributed

MindooDB's architecture is designed for offline-first operation, end-to-end encryption, and efficient synchronization across multiple deployment models.

MindooDB architecture: tenants, databases, documents, sync patterns, and security model
Core architecture

System components

Tenant structure
  • Tenant — Organization or team sharing documents
  • Directory database — Admin-only user registry
  • Databases — Multiple databases per tenant
  • Documents — Automerge CRDTs with history
  • Attachments — Encrypted file storage
Key hierarchy
  • Admin signing key — Ed25519 for directory operations
  • Admin encryption key — RSA-OAEP for sensitive data
  • User signing keys — Ed25519 per user
  • User encryption keys — RSA-OAEP per user
  • Named keys — AES-256 for document-level access
Architecture overview
MindooDB architecture: tenants contain databases, databases contain documents, sync happens through content-addressed stores
Tenants are created client-side. Each tenant contains multiple databases. Documents are stored in append-only stores with cryptographic chaining.
Scalability

Performance characteristics

Data growth

Append-only architecture means data accumulates over time. Plan for growth management:

  • Time-based sharding (yearly/monthly databases)
  • Category-based splitting
  • Archival strategies
  • Snapshot optimization
Sync efficiency

Incremental sync only transfers missing entries:

  • Content-addressed deduplication
  • Cursor-based change tracking
  • Minimal network usage
  • Works over slow connections
Query performance

Optimize queries with indexing:

  • Virtual Views for categorization
  • Incremental indexing
  • Custom indexers (FlexSearch, etc.)
  • Time-based queries
Data modeling

Organizing your data

Sharding strategies
  • Time-based — Yearly/monthly databases
  • Category-based — By document type or project
  • Access-based — By security level
  • Geographic — By region or data residency

See data modeling patterns →

When to split
  • Database size exceeds threshold (e.g., 10GB)
  • Document count exceeds limit (e.g., 1M documents)
  • Query performance degrades
  • Different access patterns emerge
  • Different retention policies needed

See performance optimization →

Multi-tenant architecture

Tenant isolation and collaboration

Tenant isolation
  • Each tenant has independent keys
  • Separate user directories
  • Isolated data by default
  • Complete control over access
Cross-tenant collaboration
  • Share specific databases between tenants
  • Use named keys for fine-grained access
  • Incremental sync for efficiency
  • Maintain independent tenant management

See cross-tenant patterns →

Sync patterns

Deployment models

Client-server

Multiple clients sync with a central server. Server can mirror encrypted data without decryption keys.

Network sync protocol →

Peer-to-peer

Direct client-to-client sync without routing through a server. Ideal for local networks and offline scenarios.

P2P sync docs →

Hybrid

Combine client-server and P2P sync. Use server for reliability, P2P for speed and redundancy.

Sync patterns →

Performance considerations

Optimization strategies

Incremental processing
  • Use iterateChangesSince() for incremental updates
  • Only process changed documents
  • Cursor-based tracking for resumable processing
  • Efficient for large datasets
Indexing
  • Virtual Views for categorized queries
  • Custom indexers (FlexSearch, etc.)
  • Incremental index updates
  • Multi-database and multi-tenant views

See indexing docs →