# teglonlabs/vibespace architecture

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

- Interactive diagram: https://gitdiagram.com/teglonlabs/vibespace
- Repository: https://github.com/teglonlabs/vibespace

## Overview

##### Main Components
- Models: These include the data schemas for Vibe, World, and WorldMoment (with sensor data as a bonus) found in the models directory. They form the backbone that defines the properties of both vibes and worlds.
- Repository: An in-memory, thread-safe storage system that enables CRUD operations for both vibes and worlds. This is crucial for persisting the entities and providing rapid access in a real-time scenario.
- Server: This is the core MCP protocol implementation using JSON-RPC. It exposes resources using custom URI schemes (like “vibe://” and “world://”) and contains endpoints for combined interactions (e.g., “world://{id}/vibe”).
- Streaming: A dedicated component implementing NATS integration for real-time streaming of “world moments.” It facilitates multi-tenant stream ID namespacing and efficient, real-time updates.
- RPC Tools: The rpcmethods package and associated utilities that format and provide JSON-RPC requests, standardize method names, and improve error handling. This package is central to securely connecting vibes and worlds in the application’s logic.

##### Highlighting the Combination of Vibes and Worlds
- JSON-RPC API layer as a central hub where requests are received. Clearly show that calls with URIs such as “vibe://{id}” and “world://{id}” are parsed then processed to modify or bind related data.
- A component representing “RPC Method Discovery and Tools” (from the rpcmethods package) next to the Server, emphasizing that these are used to ensure proper resource access and to combine operations across vibes and worlds.

##### Architectural Patterns and Relationships
- Graph components representing “Vibes” and “Worlds” so that they converge when specific operations are performed (e.g., when a world is created, followed by setting its current vibe, the “world” component is linked to the “vibe” component). This convergence is a key area to highlight as it shows how the two are combinable.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "API Layer"
        A["Client Interfaces"]:::api
        B["JSON-RPC Server"]:::api
    end

    subgraph "Business Logic Layer"
        D["RPC Methods & Tools"]:::logic
        C["Repository"]:::logic
        E["Combined Operation: set_world_vibe"]:::combined
        F["Models (Vibes & Worlds)"]:::logic
    end

    subgraph "Integration Layer"
        G["Streaming (NATS Integration)"]:::integration
    end

    A -->|"jsonrpc_calls"| B
    D -->|"rpc_invocation"| B
    B -->|"CRUD(create_vibe,update_vibe,create_world,update_world,set_world_vibe)"| C
    C -->|"trigger_set_world_vibe"| E
    E -->|"apply_vibe_world_bind"| F
    B -->|"publish_world_moments"| G

    click B "https://github.com/teglonlabs/vibespace/blob/main/cmd/server/main.go"
    click C "https://github.com/teglonlabs/vibespace/blob/main/repository/repository.go"
    click F "https://github.com/teglonlabs/vibespace/tree/main/models/"
    click G "https://github.com/teglonlabs/vibespace/tree/main/streaming/"
    click D "https://github.com/teglonlabs/vibespace/tree/main/rpcmethods/"

    classDef api fill:#aedff7,stroke:#0a3d62,stroke-width:2px;
    classDef logic fill:#f7e1ae,stroke:#a65c00,stroke-width:2px;
    classDef integration fill:#d0f7d7,stroke:#0b6e4f,stroke-width:2px;
    classDef combined fill:#ffd1dc,stroke:#ff6392,stroke-width:2px;
```
