Commonplace

System Overview

This document provides a high-level overview of the Commonplace system architecture, explaining how the different components work together to provide a flexible, powerful knowledge management platform with multi-tenant capabilities and federated sharing.

Architectural Principles

Commonplace is built on several key architectural principles:

  • Federated Identity: Both users and servers are identified through federated addressing, enabling global identity verification
  • Complete User Segregation: Each user's data is completely isolated with no shared storage between users
  • Federation by Design: Cross-server communication and sharing built into the core architecture
  • Unified Protocol: Single message protocol handles all client-server and server-server communication
  • Security by Design: Cryptographic identity verification and sandboxed execution throughout
  • Progressive Complexity: System components reveal capabilities gradually
  • Extensibility: Architecture designed to support extensions and customization

Identity Architecture

Federated Identity System

Commonplace uses DNS as the foundation for identity verification:

User Identity Format: username@server.domain.com

  • Users are identified globally using email-like addresses
  • The server domain must have a valid DNS TXT record for verification
  • Each user has a cryptographic key pair bound to their identity

Server Identity Format: server.domain.com

  • Servers publish their public keys via DNS TXT records
  • DNS verification enables trusted server-to-server communication
  • Supports custom ports and paths for flexible deployment

Identity Binding Process

  1. Server Setup: Server generates cryptographic keys and publishes public key in DNS
  2. User Registration: User generates keys and requests registration with a server
  3. Identity Binding: Server creates a cryptographic binding between username and user's public key
  4. DNS Verification: Other servers can verify identities by checking DNS records

CLARIFY: Current implementation is single-user; multi-tenant registration flow is planned

Core Components

Commonplace Server

The server handles multi-tenant data storage, user management, and federation:

  • User Management: Complete segregation of user data and permissions
  • Storage Architecture: Per-user storage directories with no cross-contamination
  • Authentication: Cryptographic challenge-response for users and servers
  • Federation Manager: Handles server-to-server communication and verification
  • Sharing Service: Manages local and federated sharing of cards and collections

Implementation Status: Single-user server exists; multi-tenant features are planned

Commonplace Client

The client provides the user interface while adapting to the multi-tenant model:

  • Server Discovery: Automatically discovers server capabilities via DNS
  • User Registration: Handles key generation and registration with servers
  • Identity Management: Manages user credentials and server connections
  • Federated Sharing: Interface for sharing content across server boundaries
  • Offline Capabilities: Can work offline with cached content (to be discussed in terms of timing, as this complicates matters somewhat!)

Implementation Status: Single-user client exists; multi-tenant features are planned

Storage System

Complete user data segregation is a core principle. Note below diagram looks like a filesystem structure but should be seen as a conceptual structure as the actual implementation is likely to differ.

server_data/
├── users/
│   ├── alice/           # Alice's completely isolated storage
│   │   ├── cards/
│   │   ├── collections/
│   │   └── shared/      # Items shared with Alice
│   └── bob/             # Bob's completely isolated storage
│       ├── cards/
│       ├── collections/
│       └── shared/
└── server/              # Server-level data only
    ├── identity_bindings/
    └── federation_cache/

Key Features:

  • No shared storage between users
  • Shared content is copied/referenced in recipient's storage; optimisations possible in future but security is paramount.
  • Server maintains minimal global state for identity and federation

Protocol Architecture

Unified Message Protocol handles all communication:

  • Client ↔ Server: Authentication, CRUD operations, sharing requests
  • Server ↔ Server: Federation, cross-server sharing, identity verification
  • Extensible message types for future capabilities

Connection Management:

  • Persistent connections with capability negotiation
  • User session management across multiple clients
  • Server connection pooling for federation

Multi-Tenant Operations

User Onboarding Flow

  1. Server Discovery: Client queries DNS to find server capabilities
  2. Registration Request: User submits username, public key, and profile
  3. Identity Binding: Server creates cryptographic binding for the user
  4. Storage Creation: Server creates isolated storage directory for user
  5. Authentication: User can now authenticate and access their data

Authentication Flows

User-to-Server Authentication:

  • Server sends cryptographic challenge
  • User signs challenge with private key
  • Server verifies signature against registered public key

Server-to-Server Authentication:

  • Requesting server signs challenge with its private key
  • Target server verifies signature against DNS-published public key
  • Establishes trusted communication channel

Sharing Architecture

Unified Sharing Model

Commonplace supports three sharing modes:

One-Off Sharing:

  • Share specific content with expiration
  • Recipient gets a copy in their storage
  • No ongoing synchronization

Feed Sharing:

  • Ongoing sharing with automatic updates
  • Configurable sync frequency
  • Changes propagate to shared copies

Editable Sharing:

  • Multiple users can edit shared content
  • Conflict resolution strategies (last-write-wins, merge, manual)
  • Real-time collaboration support (planned)

Local vs Federated Sharing

Local Sharing (same server):

  • Direct storage operations
  • Immediate consistency
  • Full permission control

Federated Sharing (cross-server):

  • Server-to-server protocol handles transfer
  • Caching and eventual consistency
  • Trust verification via DNS

Implementation Status: Basic sharing exists; federated sharing is planned

Federation Architecture

Cross-Server Communication

Server Discovery:

  • DNS-based server capability discovery
  • Public key verification through DNS
  • Connection establishment and caching

Federated Operations:

  • Cross-server user verification
  • Federated sharing requests
  • Content synchronization
  • Trust chain verification

Security Model

DNS Server Identity:

  • Server identities verified through DNS TXT records
  • DNSSEC support for enhanced security (possible, to discuss)
  • Regular re-verification of server identities

Cryptographic Security:

  • Ed25519 signatures for all identity operations
  • Per-user key pairs for content security
  • Server key pairs for federation trust
  • Message signing for messages containing user information (eg card updates).

Network Security:

  • TLS for all network communication
  • Certificate pinning for known servers
  • Rate limiting and abuse prevention

Deployment Models

Single-User Local (Current)

  • Server and client on same device
  • All data stored locally
  • No federation capabilities
  • Suitable for personal use

Multi-Tenant Server (Planned)

  • Central server with multiple users
  • Complete user data segregation
  • Local sharing between users
  • Federation with other servers

Federated Network (Planned)

  • Multiple servers in federation
  • Cross-server user verification
  • Distributed sharing and collaboration
  • Decentralized trust model

Configuration Requirements

Server Configuration

  • DNS Setup: TXT record with server public key
  • Domain Configuration: Valid domain name and SSL certificate
  • Storage: Sufficient disk space for user data segregation
  • Network: Stable internet connection for federation

Client Configuration

  • Server Discovery: Primary and fallback server domains
  • Identity: Key generation and backup procedures
  • Sharing: Default permissions and auto-accept rules

CLARIFY: Detailed configuration documentation needed

Performance Considerations

The multi-tenant architecture addresses performance through:

  • User Data Isolation: No cross-user queries or operations
  • Federated Caching: Smart caching of remote content
  • Connection Pooling: Efficient server-to-server connections
  • Lazy Loading: Only load user data when needed
  • Background Sync: Async federation operations

Implementation Roadmap

Phase 1: Federated Identity Foundation (Current Focus)

  • Federated server identity with DNS verification
  • Basic user registration
  • Cryptographic identity binding

Phase 2: Multi-User Storage

  • Complete user data segregation
  • User management interfaces
  • Basic authentication flows

Phase 3: Local Sharing

  • User-to-user sharing on same server
  • Permission management
  • Sharing mode implementation

Phase 4: Federation

  • Server-to-server protocol
  • Cross-server sharing
  • Trust verification

Phase 5: Production Features

  • Advanced security features
  • Performance optimizations
  • Administrative tools

Migration from Single-User

The current single-user implementation will migrate to multi-tenant:

  1. Data Migration: Not necessary since system exists only in development
  2. Identity Creation: Generate server identity and DNS records
  3. Client Updates: Update client for server discovery and registration
  4. Gradual Rollout: Multi-tenant features deployed incrementally

Next Steps

For more detailed information about specific aspects of the architecture, see: