🧠 Core Concepts – OperaDB

OperaDB is structured around modular and replayable logic. This page explains the essential concepts that make up the foundation of how OperaDB operates internally.

---

🧍‍♂️ Actor

• An actor is the originator of an event — either a user, a system, a bot, or an external service.
• All events are created in the context of an actor.
• Actors are registered in the system with a unique ID and assigned roles (e.g., admin, system, guest).

{
  "actorId": "user:abc123",
  "roles": ["admin"]
}

---

🧾 Event

• An event is an immutable log of an action.
• It records what happened, when, by whom, and on which entity.
• Events can be stored permanently, and used to replay or audit state.

{
  "type": "asset.create",
  "actor": "user:abc123",
  "data": {
    "assetId": "asset:x001",
    "name": "Gold",
    "qty": 100
  },
  "timestamp": "2025-06-04T07:30:00Z"
}

---

🧮 Reducer

• A reducer is a function that receives events and produces the current state.
• Reducers are schema-specific and versioned.
• They define logic like incrementing quantities, merging fields, or validating constraints.

// Example (simplified)
function reducer(state, event) {
  if (event.type === "asset.create") {
    return { ...event.data };
  }
  if (event.type === "asset.update") {
    return { ...state, ...event.data };
  }
  return state;
}

---

📜 Schema

• A schema defines the structure of an entity — similar to a database schema but modular and versioned.
• Schemas include:
  • Field names and types
  • Required fields
  • Validation rules
  • Associated reducer

{
  "schemaId": "mod:asset",
  "fields": [
    { "name": "assetId", "type": "string", "required": true },
    { "name": "name", "type": "string", "required": true },
    { "name": "qty", "type": "number", "required": false }
  ],
  "reducerCode": "// reducer logic"
}

---

📦 State

• The state is the result of applying all related events to an entity.
• State is not stored permanently by default — it is derived by replaying events through a reducer.
• Optionally, state can be cached or snapshotted for performance.

{
  "assetId": "asset:x001",
  "name": "Gold",
  "qty": 120
}

---

🔗 Chain & Slot

• Each entity (e.g. asset, coin, actor) is stored under an account namespace and a slot.
• Slots allow multiple versions or variants of the same entity to exist simultaneously.
• Chains are used to group events for replay and traceability.

---

🧭 Guiding Flow

Actor → Event → Reducer → State
Schema guides both the event format and the reducer behavior

---

🛠 Example Lifecycle

1. Actor creates an asset.create event.
2. Event is saved and validated.
3. Reducer processes the event.
4. State is generated or updated.
5. State can be queried or used in the frontend.

---

Continue to Modularity & Schemas to learn how to define and organize schema modules in OperaDB.