# oexza/orisun architecture

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

- Interactive diagram: https://gitdiagram.com/oexza/orisun
- Repository: https://github.com/oexza/orisun

## Overview

- Core Server Application (Orisun Server): This is implemented predominantly in Go (located in the “src/orisun” folder) and is responsible for handling incoming gRPC requests, event storage logic, and managing the modular components (admin, event store, and various storage backends).
- Database (PostgreSQL): Used for durable event storage, automatic schema setup, and managing boundaries (each PostgreSQL schema representing a bounded context).
- Embedded Messaging System (NATS JetStream): Provides real‐time event streaming and pub/sub. It is embedded, meaning that no external NATS service is required—but it still represents a separate logical component.
- Client Libraries: For example, the Java client (present under “clients/java”) which communicates with the Orisun server via gRPC. This highlights the external interfaces and connectivity.
- Administration & UI Components: These are parts of the “admin” module (files under “src/orisun/admin”) containing handlers, templates, and dashboards. They deliver the administrative interface for schema and event management.

##### Relationships and Interactions
- Administrative & Configuration Interaction: The admin sub-module in the Go code manages boundaries, authentication, and provides templates for dashboards. Indicate this as a separate module within the Orisun server that interfaces with the database and monitoring/logging functions.

##### Architectural Patterns and Design Principles
- Modular and Extensible Architecture: The project separates different functionalities into distinct directories (admin, eventstore, multiple storage backends like PostgreSQL, SQLite, and FoundationDB). Annotate these modules and emphasize the “Batteries Included” philosophy.
- Real-time Streaming: Demonstrate a pipeline from the server’s event processing to NATS JetStream for pub/sub and back to any subscribing clients.
- API-Driven Communication: Use the gRPC interface as the primary communication mechanism between external clients and the backend components.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Clients
    subgraph "External Clients"
        A["Client Library (Java)"]
    end

    %% Core Server Components
    subgraph "Core Server Components"
        S1["Orisun Server (gRPC & Admin)"]
        S2["gRPC API and Event Store Logic"]
        S3["Administration & UI Components"]
    end

    %% Databases
    subgraph "Databases"
        DB["PostgreSQL (Event Storage & Boundaries)"]
    end

    %% Message Bus
    subgraph "Message Bus"
        NATS["Embedded NATS JetStream (Real-time Pub/Sub)"]
    end

    %% External Client to Server
    A -->|"gRPC_call"| S1

    %% Internal Components within Orisun Server
    S1 ---|"includes"| S2
    S1 ---|"includes"| S3

    %% Server interactions with Database and Messaging
    S1 -->|"writes_events"| DB
    S1 -->|"publishes_events"| NATS

    %% Real-time notifications from NATS to External Clients
    NATS -->|"stream_updates"| A

    %% Click Events
    click S1 "https://github.com/oexza/orisun/blob/main/src/orisun/main/main.go"
    click S2 "https://github.com/oexza/orisun/tree/main/src/orisun/eventstore"
    click S3 "https://github.com/oexza/orisun/tree/main/src/orisun/admin"
    click DB "https://github.com/oexza/orisun/tree/main/src/orisun/postgres"
    click A "https://github.com/oexza/orisun/tree/main/clients/java"

    %% Styles
    classDef servers fill:#CCE5FF,stroke:#004085,stroke-width:2px;
    classDef db fill:#D4EDDA,stroke:#155724,stroke-width:2px;
    classDef external fill:#FFF3CD,stroke:#856404,stroke-width:2px;
    classDef messaging fill:#F8D7DA,stroke:#721C24,stroke-width:2px;

    class S1,S2,S3 servers;
    class DB db;
    class NATS messaging;
    class A external;
```
