Canonical Architecture

This document defines the authoritative architecture of RitualOS. It describes the flow of authority, data, and communication between services. All development must comply with this architecture.

Architecture Overview

RitualOS is organized into six layers, each with distinct responsibilities and non-negotiable properties:

┌─────────────────────────────────────────────────────────────────────┐
│                          IDENTITY LAYER                              │
│                                                                       │
│   ┌───────────────────────────────┐                                  │
│   │        id.ritualos.com         │                                  │
│   │  Identity, Passport, OAuth    │                                  │
│   │  Houses, Archetypes, Creds    │                                  │
│   └───────────────┬───────────────┘                                  │
│                   │  (signed identity context)                        │
└───────────────────┼─────────────────────────────────────────────────┘
                    │
                    ▼
┌─────────────────────────────────────────────────────────────────────┐
│                          ACTION LAYER                                │
│                                                                       │
│  ┌────────────┐  ┌────────────┐  ┌────────────┐  ┌──────────────┐  │
│  │ path.*     │  │ learn.*    │  │ guild.*    │  │ way.*        │  │
│  │ Quests     │  │ Education  │  │ Work/Labor │  │ Physical     │  │
│  │ XP/Gold    │  │ Skills     │  │ Reputation │  │ Activity     │  │
│  └─────┬──────┘  └─────┬──────┘  └─────┬──────┘  └─────┬────────┘  │
│        │               │               │               │           │
│        └───────────────┴───────────────┴───────────────┘           │
│                        (reward requests)                             │
└───────────────────────────────┬─────────────────────────────────────┘
                                ▼
┌─────────────────────────────────────────────────────────────────────┐
│                       API GATEWAY                                    │
│                                                                       │
│            api.ritualos.com                                          │
│   SINGLE AUTHORIZED WRITE GATEWAY                                    │
│   - validates identity                                               │
│   - enforces rules                                                   │
│   - authorizes XP / Gold / Credentials                               │
└───────────────────────────────┬─────────────────────────────────────┘
                                ▼
┌─────────────────────────────────────────────────────────────────────┐
│                       SETTLEMENT LAYER                               │
│                                                                       │
│   ┌──────────────────────────┐     ┌─────────────────────────────┐  │
│   │   ledger.ritualos.com    │     │     market.ritualos.com      │  │
│   │  Immutable Archive       │     │  Assets, Listings, Exchange  │  │
│   │  Receipts, Proofs        │     │  (consumes credentials)     │  │
│   └──────────────────────────┘     └─────────────────────────────┘  │
└─────────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────────┐
│                       NARRATIVE / SOCIAL                              │
│                                                                       │
│   ┌──────────────────────────┐     ┌─────────────────────────────┐  │
│   │  scroll.ritualos.com     │     │   realm.ritualos.com         │  │
│   │  Culture, Memory         │     │  Spatial / Events / Avatars  │  │
│   └──────────────────────────┘     └─────────────────────────────┘  │
└─────────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────────┐
│                       GOVERNANCE LAYER                                │
│                                                                       │
│            governance.ritualos.com                                    │
│   Proposals, Voting, Legitimacy (credential-gated)                    │
└─────────────────────────────────────────────────────────────────────┘

Layer Definitions

Identity Layer

Service: id.ritualos.com

The foundation of the RitualOS ecosystem. All identity originates here and flows downward to all other layers.

Responsibilities:

• Issuance and management of canonical identities
• OAuth 2.0 authentication and authorization
• House and Archetype assignment (based on behavior, not choice)
• Credential storage and verification
• Identity context signing for downstream services

Non-Negotiable Properties:

• No other service may create identities
• No other service may infer or assign Houses or Archetypes
• All identity queries must resolve through this layer

Action Layer

Services: path.ritualos.com, learn.ritualos.com, guild.ritualos.com, way.ritualos.com

The domain of user action and contribution. These services orchestrate user activities but do not mint rewards directly.

Responsibilities:

• Path: Quest engine, daily rites, XP/Gold minting (the only authorized mint)
• Learn: Educational content, course delivery, skill tracking
• Guild: Work coordination, bounties, reputation
• Way: Physical activity tracking, move-to-earn challenges

Non-Negotiable Properties:

• Only Path may mint XP and Gold
• Other action services request rewards through the API gateway
• All actions must be validated against identity before execution

API Gateway

Service: api.ritualos.com

The single authorized write gateway for all state-changing operations.

Responsibilities:

• Validates identity context from Identity Layer
• Enforces business rules and rate limits
• Authorizes XP, Gold, and Credential issuance
• Routes authorized writes to Settlement Layer
• Provides audit trail for all mutations

Non-Negotiable Properties:

• All writes must flow through this gateway
• No direct database mutations from action services
• All authorization decisions are centralized here

Settlement Layer

Services: ledger.ritualos.com, market.ritualos.com

The immutable record and value exchange layer.

Responsibilities:

• Ledger: Append-only archive of all actions, receipts, and proofs
• Market: Asset listings, exchanges, and transactions (consumes credentials, never produces authority)

Non-Negotiable Properties:

• Ledger is write-only and append-only (no deletions, no updates)
• Ledger never computes or arbitrates
• Market never writes upstream (no authority production)
• Market consumes credentials but cannot grant them

Narrative Layer

Services: scroll.ritualos.com, realm.ritualos.com

The cultural and social expression layer.

Responsibilities:

• Scroll: Lore creation, memory artifacts, cultural expression
• Realm: 3D social spaces, events, avatars, community gatherings

Non-Negotiable Properties:

• May interpret events but cannot rewrite ledger records
• Cultural expression is protected from optimization
• Meaning precedes metrics

Governance Layer

Service: governance.ritualos.com

The legitimacy and decision-making layer.

Responsibilities:

• Proposal creation and voting
• Legitimacy calculation (credential-gated)
• Ecosystem rule changes
• Quorum enforcement

Non-Negotiable Properties:

• Voting power derives from credentials (read from Identity Layer)
• Cannot retroactively alter identity or ledger records
• Governance decisions preserve coherence, not chase consensus

Flow Directions

These flow directions define the trust boundaries of the system:

1. Identity flows downward only - From Identity Layer to all other layers
2. Authority flows inward only - All writes converge at API Gateway
3. Ledger is write-only, append-only - No reads for decision-making, no updates, no deletions
4. Market never writes upstream - Consumes credentials and assets, produces no authority
5. Governance reads credentials, never assigns them - Voting power is derived, not granted

Critical Architectural Rules

Rule 1: ID Is the Only Source of Truth for Identity

• No app may create identities
• No app may infer Houses or Archetypes
• All roles, permissions, and credentials resolve from ID

Rule 2: Ledger Is Append-Only and Non-Interactive

• Ledger never "decides" anything
• It records outcomes, proofs, and attestations
• No UI-driven mutations

Rule 3: Path Is the Only XP/Gold Mint

• Learn, Way, Guild, Governance request rewards
• Path authorizes, calculates, and emits
• Ledger records the result

Rule 4: Market Is a Sink, Not a Brain

• No core logic in Market
• It consumes credentials, assets, and permissions
• Never the reverse

Service Communication

All service-to-service communication follows these patterns:

OAuth Authentication

┌─────────┐         ┌─────────┐
│ Client  │         │ Service │
│ App     │         │         │
└────┬────┘         └────┬────┘
     │    OAuth          │
     │  Authorization    │
     ▼                   ▼
┌─────────────────────────────┐
│     id.ritualos.com         │
│  (OAuth Provider)           │
└──────────┬──────────────────┘
           │  Identity Context + Access Token
           ▼
┌─────────────────────────────┐
│     Client App              │
│  (Authenticated)            │
└─────────────────────────────┘

Credential Issuance

┌─────────┐  Issue    ┌─────────┐  Validate &   ┌─────────┐
│ Service │──────────▶│  API    │─────────────▶│   ID    │
│         │ Credential│ Gateway │   Issue      │ Service │
└─────────┘           └─────────┘              └─────────┘
                           │
                           ▼
                    ┌─────────┐
                    │ Ledger  │
                    │  Record │
                    └─────────┘

Reward Flow

┌─────────┐  Request  ┌─────────┐  Authorize  ┌─────────┐
│ Learn   │──────────▶│  Path   │────────────▶│   API   │
│ Guild   │  Reward   │         │   Mint      │ Gateway │
│ Way     │           │         │             └─────────┘
└─────────┘           └─────────┘                  │
                                                     ▼
                                              ┌─────────┐
                                              │ Ledger  │
                                              │  Write  │
                                              └─────────┘

Non-Negotiable Properties

These properties DEFINE the system and cannot be violated:

1. Single Service Endpoint

• All traffic flows through appropriate service URLs
• No unauthorized cross-service database access
• No bypassing the API Gateway

2. Ledger Module Is Append-Only

• No DELETE or UPDATE on receipt records
• Enforced at code level through immutable data structures
• Future audit trail guaranteed

3. OAuth Is The Only Auth Mechanism

• All ecosystem services use OAuth 2.0
• No direct database access from consuming services
• Session tokens managed by ID Service

4. Clear Separation of Concerns

• Each layer has distinct responsibilities
• Authority flows inward, never outward
• Data flows are unidirectional

Implementation Reference

All services must operate within these constraints. For implementation details, see:

• Technical Architecture - Service communication, protocols, and technical patterns
• Data Models - Database schemas and relationships
• API Reference - Complete API endpoint catalog

Evolution

This canonical architecture may evolve only through explicit governance processes that preserve backward compatibility with identity and ledger records.

No emergency overrides exist.

Continuity is sacred.