Project Overview

Aura aims to demonstrate a practical web-of-trust architecture that adheres to the following constraints:

Network as platform: All coordination and information flow happens peer-to-peer through the social graph.

Privacy by design: Information disclosure must be selective and consent-based.

Cross-platform: The system must run on web (Chrome, Firefox, Safari via WebAssembly), mobile (iOS, Android), and desktop (macOS, Linux).

Mobile-first and Resilient: The system targets mobile devices as the primary substrate for all interaction and service provision. As such it must be highly tolerant of network partitions and device failure.

Social Recovery: Users must be able to store secrets in the network and survive catastrophic device failure.

Version Compatibility: Older clients must interact with newer ones within semantic version compatibility bounds.

In order to achieve these goals, Aura combines threshold cryptography, choreographic programs that project to session typed protocols, fact-based semilattices, session types, and authorized effects.

Implementation

These three pillars combine into an 8-layer architecture. The layers progress from interface definitions through user-facing applications. See System Architecture for the complete layer breakdown.

The layers are as follows:

1. Foundation (aura-core): Effect traits, domain types, cryptographic utilities, and error types.

2. Specification (aura-journal, aura-wot, aura-verify, aura-store, aura-transport, aura-mpst, aura-macros): CRDT domains, capability systems, transport semantics, session type runtime, and choreography DSL.

3. Implementation (aura-effects, aura-composition): Stateless production handlers and handler composition infrastructure.

4. Orchestration (aura-protocol): Multi-party coordination, guard chain, and Aura Consensus runtime.

5. Feature implementation (aura-authenticate, aura-chat, aura-invitation, aura-recovery, aura-relational, aura-rendezvous, aura-social, aura-sync): End-to-end protocol crates for authentication, secure messaging, recovery, relational contexts, rendezvous, social topology, and synchronization.

6. Runtime composition (aura-agent, aura-simulator, aura-app): Complete system assembly, deterministic simulation, and portable application core.

7. User interface (aura-terminal): Terminal-based CLI and TUI entry points.

8. Testing and tools (aura-testkit, aura-quint): Test fixtures, mock effect handlers, and simulation harnesses.

Documentation Index

Additional documentation covers specific aspects of the system. The Foundation category covers mathematical and architectural foundations. The Core Systems category covers each major component. The Developer Guides category provides practical guides for implementation. The Project Meta category covers project structure.

Foundation

Theoretical Model provides mathematical foundations including formal calculus, algebraic types, and semilattice semantics.

System Architecture describes implementation architecture including effect system patterns, CRDT implementations, and choreographic protocols.

Privacy and Information Flow documents the consent-based privacy framework with trust boundaries, flow budgets, and leakage tracking.

Distributed Systems Contract specifies safety and liveness guarantees, the synchrony model, latency bounds, and adversarial assumptions.

System Invariants documents safety invariants and verification properties across the system.

Core Systems

Authority and Identity describes the authority-centric identity model with opaque authorities and relational contexts.

Identifiers and Boundaries documents the identifier system and context isolation.

Accounts and Commitment Tree covers the commitment tree structure for threshold identity management.

Key Rotation Ceremonies describes the shared Category C contract for key rotations and membership changes (devices, guardians, groups, blocks).

Journal System documents the fact-based journal, validation rules, and deterministic reduction flows.

Relational Contexts covers guardian bindings, recovery grants, and context-scoped journals.

Consensus describes the Aura Consensus protocol for strong agreement.

Operation Categories defines the A/B/C operation classification used throughout the system and how ceremonies relate to optimistic CRDT operations.

Effect System and Runtime covers effect system architecture and runtime composition.

MPST and Choreography documents multi-party session types and choreographic programming.

Transport and Information Flow covers guard chain enforcement, secure channel lifecycle, and FlowBudget receipts.

Authorization describes the authorization flow from capabilities to Biscuit tokens.

Rendezvous Architecture covers context-scoped rendezvous envelopes and channel establishment.

State Reduction describes deterministic state reduction from fact journals to canonical state.

Maintenance covers the distributed maintenance stack including snapshots and garbage collection.

Asynchronous Message Patterns documents patterns for reliable asynchronous message coordination.

Database Architecture specifies the distributed database layer using journals, Biscuit queries, and CRDTs.

Social Architecture defines the social organization model using messages, blocks, and neighborhoods.

CLI and Terminal User Interface specifies the CLI and iocraft-based TUI for Aura.

Developer Guides

Hello World Guide provides a starting point for developers new to Aura.

Core Systems Guide explains the core systems and how they work together.

Coordination Guide covers choreographic protocol design and implementation patterns.

Advanced Coordination Guide documents advanced techniques for distributed coordination.

Development Patterns and Workflows covers practical patterns for developing Aura systems, including code location guidance and typical implementation workflows.

Testing Guide describes property testing, simulation harnesses, and validation frameworks.

Simulation Guide covers deterministic simulation for verification and debugging.

Verification Guide covers formal verification techniques and property validation.

Maintenance Guide explains distributed maintenance, snapshots, garbage collection, and system evolution.

Project Meta

Project Structure provides a comprehensive crate structure overview with the dependency graph.