System Architecture - ljcom/operadb GitHub Wiki

🧱 System Architecture – OperaDB

OperaDB is built on an event-driven, replayable, and modular architecture, designed to support scalable applications and workflows without the need to mutate the underlying database state directly.

🧠 Core Principles

Principle Description
Event Sourcing All data changes are stored as immutable events
Reducer Pattern Events are processed using reducers to build final state
Replayable State The state of any entity can be rebuilt from its event history
Schema Modularization Entities are defined via JSON-like schema, versioned and extendable
Actor-Centric Model All actions are performed in the context of an actor (user/system)

πŸ—‚ Architectural Layers

+--------------------------+
|        Frontend UI       |   ← React (Explorer)
+--------------------------+
            |
            v
+--------------------------+
|        API Layer         |   ← RESTful endpoints (Node.js/Express)
+--------------------------+
            |
            v
+--------------------------+
|  Event Dispatcher & Core |   ← Validates, routes, and stores events
+--------------------------+
            |
            v
+--------------------------+
|      Reducer Engine      |   ← Converts events to state snapshots
+--------------------------+
            |
            v
+--------------------------+
|     State Database       |   ← MongoDB / JSON store / vector DB
+--------------------------+

πŸ”— Key Components

1. Actor

Represents the user, bot, or system module initiating an action. Each event is tagged with its actor ID for traceability.

2. Schema

Defines the format of an entity’s data structure, validations, and field-level properties. Schemas are versioned and modular.

3. Reducer

Contains logic to process events (create, update, transfer, etc.) into a consistent state. Reducers are assigned per schema.

4. Event

Each action (like creating a user, issuing a coin, transferring an asset) is recorded as an event. Events are immutable and timestamped.

5. State

The current representation of an entity, computed by replaying its event history using the appropriate reducer.

πŸŒ€ Data Flow

User Action β†’ API β†’ Event Created β†’ Stored β†’ Reducer Runs β†’ State Saved/Updated β†’ UI Reflects State

🧩 Modularity & Plug-and-Play

OperaDB is schema-first. This means:

  • New modules (like coin, contract, asset) can be added by writing schema + reducer only.
  • No need to write new database tables or REST routes.
  • Everything is versioned and namespaced by account.

βš™οΈ Deployment Options

  • 🌐 Can run in single-instance or multi-tenant mode
  • πŸ§ͺ Local development using npm run dev
  • πŸ“¦ Docker-based deployment (coming soon)
  • πŸ”— Future: support for vector database integration (Weaviate / Milvus)

πŸ”’ Security Model

  • Events can be validated with signatures
  • Actor permissions are verified before processing reducers
  • Optional: token/session-based authorization layer

Next: Learn about Core Concepts such as actors, events, reducers, and schemas in detail.