# cognition-brahmai/mvent architecture

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

- Interactive diagram: https://gitdiagram.com/cognition-brahmai/mvent
- Repository: https://github.com/cognition-brahmai/mvent

## Overview

##### Main Components

a) Core Components (Central):
- Shared Memory Manager (from shared_memory.py)
- Events Manager (from events_manager.py)
- Memory Event Decorator System (from memory_events.py)

b) Process Boundaries:
- Process 1 (Example Producer)
- Process 2 (Example Consumer)
- Additional Processes (Optional)

##### Process Integration Layer
- Inside each process, show:
- MemoryEventHandler instances
- Decorated event handlers
- Emit/Subscribe flows

##### Data Flow Layer
- Event emission paths
- Subscription notifications
- TTL cleanup processes

- Blue: Core components (Shared Memory, Events Manager)
- Green: Active processes
- Yellow: Event handlers and decorators
- Red: Critical paths (event emission, notifications)
- Gray: Memory-mapped file storage

Key Flows to Represent:

##### Event Registration Flow
**Decorator → Events Manager → Shared Memory Manager**

##### Event Emission Flow
**Process (emit) → Events Manager → Shared Memory Manager → Memory-Mapped File**

##### Event Notification Flow
**Memory-Mapped File → Shared Memory Manager → Events Manager → Registered Handlers**

##### TTL Cleanup Flow
**Timer → Events Manager → Shared Memory Manager → Memory-Mapped File**

Important Elements to Include:

##### Thread Safety Mechanisms
- Mutex/lock symbols where appropriate
- Atomic operations

##### TTL Management
- A cleanup scheduler component
- Expiration tracking

##### Inter-Process Communication
- Process boundaries
- Shared memory access points

Specific annotations:

##### Component Labels
- MemoryEventHandler: "Primary API Interface"
- Shared Memory Manager: "Memory-Mapped File Controller"
- Events Manager: "Event Distribution System"

##### Process Boundaries
- Isolation boundaries

##### Data Flow Markers
- Event emission paths
- Subscription notifications
- TTL cleanup operations

Level of Detail Guidelines:

##### High-Level View
- Main components and their interactions
- Process boundaries
- Primary data flows

##### Mid-Level Details
- Decorator mechanism
- Event handler registration
- TTL management

##### Implementation Details
- Memory-mapped file interaction
- Thread safety mechanisms
- Event distribution patterns

Remember to:
- Use clear, consistent symbols
- Notes for critical operations
- Error handling paths
- Thread-safe operations
- TTL-related processes

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Core Components
    subgraph Core
        SM[Shared Memory Manager]
        EM[Events Manager]
        MED[Memory Event Decorator System]
        MMF[(Memory-Mapped File)]:::storage
        
        SM <--> EM
        SM <--> MMF
        MED --> EM
    end
    
    %% Process 1 (Producer)
    subgraph Process1[Process 1 - Producer]
        direction TB
        P1H[MemoryEventHandler]:::handler
        P1D[Decorated Events]:::decorator
        
        P1H --> P1D
        P1D --> EM
    end
    
    %% Process 2 (Consumer)
    subgraph Process2[Process 2 - Consumer]
        direction TB
        P2H[MemoryEventHandler]:::handler
        P2D[Decorated Events]:::decorator
        
        P2H --> P2D
        EM --> P2D
    end
    
    %% TTL Management
    subgraph TTL[TTL Management]
        direction TB
        TS[TTL Scheduler]:::scheduler
        TC[Cleanup Process]:::process
        
        TS --> TC
        TC --> SM
    end
    
    %% Thread Safety
    subgraph ThreadSafety[Thread Safety]
        direction TB
        MT[Mutex/Locks]:::safety
        AO[Atomic Operations]:::safety
    end
    
    %% Relationships
    ThreadSafety --> SM
    ThreadSafety --> EM
    
    %% Styling
    classDef core fill:#a8d1f0,stroke:#333,stroke-width:2px
    classDef handler fill:#90EE90,stroke:#333,stroke-width:2px
    classDef decorator fill:#FFE5B4,stroke:#333,stroke-width:2px
    classDef storage fill:#D3D3D3,stroke:#333,stroke-width:2px
    classDef process fill:#98FB98,stroke:#333,stroke-width:2px
    classDef scheduler fill:#FFA07A,stroke:#333,stroke-width:2px
    classDef safety fill:#F0F8FF,stroke:#333,stroke-width:2px
    
    class SM,EM,MED core
    class P1H,P2H handler
    class P1D,P2D decorator
    class MMF storage
    class TC process
    class TS scheduler
    class MT,AO safety
    
    %% Click Events
    click SM "https://github.com/cognition-brahmai/mvent/blob/main/mvent/core/shared_memory.py"
    click EM "https://github.com/cognition-brahmai/mvent/blob/main/mvent/core/events_manager.py"
    click MED "https://github.com/cognition-brahmai/mvent/blob/main/mvent/decorators/memory_events.py"
    click P1H "https://github.com/cognition-brahmai/mvent/blob/main/mvent/examples/basic_usage.py"
    click P2H "https://github.com/cognition-brahmai/mvent/blob/main/mvent/__init__.py"

    %% Legend
    subgraph Legend
        direction TB
        L1[Core Components]:::core
        L2[Event Handlers]:::handler
        L3[Decorators]:::decorator
        L4[(Storage)]:::storage
        L5[Processes]:::process
        L6[Scheduler]:::scheduler
        L7[Thread Safety]:::safety
    end
```
