# aeternus-capital/theatrum architecture

> Architecture diagram of the GitHub repository aeternus-capital/theatrum, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/aeternus-capital/theatrum
- Repository: https://github.com/aeternus-capital/theatrum

## Overview

##### Project type and purpose
- This is an open-source, monorepo tool written in TypeScript (Deno-compatible) called “Theatrum.”
- It consists of two main packages:
- @theatrum/core – the runtime engine for defining entities, methods, executors, and dispatching calls (no vendor lock-in).
- @theatrum/console – a React/Mantine web UI for exploring & interacting with the core via network calls.
- There is also an “examples/basic” application showing how to wire core into a Deno server and optionally connect a database (e.g., MongoDB integration).

##### File structure
- Top-level directories:
- docs/ – static documentation and topics (architecture, examples, integrations).
- packages/core/ – core library source, errors, types, executor, entity, method abstractions.
- packages/console/ – web client with UI components (Actors, Entities, Methods, Playground, History), network.js, store layer, bundler & DNT tools.
- examples/basic/ – sample Deno app bootstrapping core, defining User entity & a math/sum method.
- Config files: deno.json, deno.lock in root and in each package; publish workflows in .github; dnt.json for npm builds.

##### Key insights from the README
- Core is lightweight, runtime-agnostic (works in Deno, service workers, Node via DNT output).
- Console is a standalone SPA that communicates with any Theatrum-powered endpoint.
- No opinions on router/auth – it exposes a minimal RPC layer.

##### Main components and interactions
a. Components
1. Client Layer
- Browser running @theatrum/console SPA (Actors, Entities, Methods, Playground, History UI).
2. Network/API Layer
- network.js in console → JSON-RPC/HTTP endpoints exposed by the core.
3. Application Server
- Example/basic (or any Theatrum server) using @theatrum/core.
- Sub-components inside core:
– Entity Registry (packages/core/src/entity.ts)
– Method Registry (packages/core/src/method.ts)
– Executor (packages/core/src/executor.ts)
– Error handling (packages/core/src/errors.ts)
– Theatrum orchestrator (packages/core/src/theatrum.ts)
4. Data Layer (optional)
- External services (e.g., MongoDB via integration-mongodb example, file storage, other HTTP APIs).
b. Relationships & Data Flow
- Browser → HTTP RPC → Theatrum server
- Theatrum server → Entities & Methods → Executor
- Executor → (optionally) Database or external service
- Theatrum server → JSON result → Browser
c. Architectural patterns & principles
- Plug-in style registries for Entities and Methods.
- Separation of concerns: core runtime vs. UI client.
- Runtime-agnostic code (no Deno- or Node-specific APIs in core).
- Single-page application for administrative console.
d. Key technologies & frameworks
- Deno + TypeScript (core & server example)
- React + Mantine (console UI)
- JSON-RPC / HTTP for remote calls
- DNT for Node.js packaging

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    subgraph "Client Layer"
        direction TB
        BrowserUI["Browser running @theatrum/console SPA"]:::ui
        subgraph "Console SPA"
            direction TB
            AppUI["App.jsx"]:::ui
            Header["Header"]:::ui
            Actors["Actors Panel"]:::ui
            Entities["Entities Panel"]:::ui
            Methods["Methods List"]:::ui
            Playground["Playground"]:::ui
            History["History"]:::ui
            Footer["Footer"]:::ui
        end
    end

    %% Network/API Layer
    Network["network.js"]:::api

    %% Application Server
    subgraph "Application Server"
        direction TB
        ServerEntry["Server Bootstrap"]:::server
        subgraph "Theatrum Core"
            direction TB
            Orchestrator["Theatrum Orchestrator"]:::core
            EntityReg["Entity Registry"]:::core
            MethodReg["Method Registry"]:::core
            ExecutorM["Executor"]:::core
            Errors["Error Handler"]:::core
        end
    end

    %% Data Layer
    DB["MongoDB / External Services"]:::external

    %% Connections
    BrowserUI -->|"HTTP JSON-RPC call"| Network
    Network -->|"forwards RPC"| ServerEntry
    ServerEntry -->|"initializes core"| Orchestrator
    Orchestrator -->|"register entities"| EntityReg
    Orchestrator -->|"register methods"| MethodReg
    EntityReg -->|"lookup entity"| ExecutorM
    MethodReg -->|"execute method"| ExecutorM
    ExecutorM -->|"DB query / external call"| DB
    ExecutorM -->|"return result"| Orchestrator
    Orchestrator -->|"HTTP JSON-RPC response"| Network
    Network -->|"returns result"| BrowserUI

    %% Click Events
    click AppUI "https://github.com/aeternus-capital/theatrum/blob/master/packages/console/web/src/App.jsx"
    click Header "https://github.com/aeternus-capital/theatrum/blob/master/packages/console/web/src/components/Header/index.jsx"
    click Actors "https://github.com/aeternus-capital/theatrum/blob/master/packages/console/web/src/components/Actors/index.jsx"
    click Entities "https://github.com/aeternus-capital/theatrum/blob/master/packages/console/web/src/components/Entities/index.jsx"
    click Methods "https://github.com/aeternus-capital/theatrum/blob/master/packages/console/web/src/components/Methods/index.jsx"
    click Playground "https://github.com/aeternus-capital/theatrum/blob/master/packages/console/web/src/components/Playground/index.jsx"
    click History "https://github.com/aeternus-capital/theatrum/blob/master/packages/console/web/src/components/History/index.jsx"
    click Footer "https://github.com/aeternus-capital/theatrum/blob/master/packages/console/web/src/components/Footer/index.jsx"
    click Network "https://github.com/aeternus-capital/theatrum/blob/master/packages/console/web/src/network.js"
    click ServerEntry "https://github.com/aeternus-capital/theatrum/blob/master/examples/basic/src/index.ts"
    click EntityReg "https://github.com/aeternus-capital/theatrum/blob/master/packages/core/src/entity.ts"
    click MethodReg "https://github.com/aeternus-capital/theatrum/blob/master/packages/core/src/method.ts"
    click ExecutorM "https://github.com/aeternus-capital/theatrum/blob/master/packages/core/src/executor.ts"
    click Errors "https://github.com/aeternus-capital/theatrum/blob/master/packages/core/src/errors.ts"
    click Orchestrator "https://github.com/aeternus-capital/theatrum/blob/master/packages/core/src/theatrum.ts"

    %% Styles
    classDef ui fill:#e0ffe0,stroke:#008000,color:#006400
    classDef api fill:#e0e0ff,stroke:#0000ff,color:#000066
    classDef server fill:#f0f0f0,stroke:#666666,color:#333333
    classDef core fill:#e0f7ff,stroke:#0088cc,color:#004466
    classDef external fill:#fff4e6,stroke:#ff8800,color:#cc5500
```
