# eightman999/ourin architecture

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

- Interactive diagram: https://gitdiagram.com/eightman999/ourin
- Repository: https://github.com/eightman999/ourin

## Overview

##### Project Type and Purpose
- This is a macOS‐native desktop application (“Ourin”) written primarily in Swift with mixed C/C++ components.
- It provides a “baseware” runtime for Ukagaka‐style virtual characters (“ghosts”), supporting modules such as balloon rendering, Shiori scripting, plugin hosting, NAR package installation, event dispatch, SSTP/HTTP servers, and an embedded script engine (YAYA Core).

##### High-Level Architectural Layers
A. UI Layer
- OurinApp, SwiftUI Views (ContentView, AboutView, DevToolsView, GhostView, BalloonView, NarInstallView, etc.)
- Asset catalogs (Assets.xcassets)
B. Application Services Layer
- AnimationEngine, GhostManager, Balloon subsystem (DescriptorLoader, ImageLoader, ICO), HeadlineHost, NarInstaller, LogStore
- Property system (PropertyManager + Provider plugins for System, Ghost, Plugin, Resource)
- ResourceBridge (bridging macOS resources into the app)
C. Protocol / Event Layer
- SHIORIEvents (EventBridge, various Observers)
- SSTP (TCP/HTTP/XPC servers and parsers: SstpTcpServer, SstpHttpServer, SstpRouter, SSTPDispatcher)
- PluginEventDispatcher / PluginHost (PluginRegistry, PluginProtocol)
- WebHandler & WebNarInstaller for the Web API
D. Native Bridge & Embedded Engine Layer
- FMO bridge (FmoBridge.c/h, shared memory, mutex) for inter-process memory exchange
- Ourin-Bridging-Header linking Swift to C/C++
- YayaAdapter + integrated YAYA Core (yaya_core subproject containing Lexer, Parser, VM)
E. Persistence / Utilities Layer
- LogModels, LogStore, ProcessKiller, SyncCenter, Utils/Log
- Unit tests (OurinTests) and UI tests (OurinUITests)

##### Component Relationships and Data Flow
- UI → Services: UI components invoke Application Services (e.g., GhostManager, Balloon, NarInstall) to render and manage ghosts.
- Services → Protocol/Event: Services publish/subscribe to system events via SHIORIEvents and dispatch user commands.
- Protocol/Event → PluginHost: Incoming SSTP, XPC, HTTP, or plugin events are routed to plugin modules via PluginEventDispatcher.
- Services → FMO & YAYA Core: Some components delegate script execution to YAYA Core or share data with other processes via FMO.
- Persistence: Logs and metrics are stored via LogStore and ServerMetrics.

##### Architectural Patterns and Design Principles
- Layered architecture separating UI, business logic, protocol interfaces, and native bridges.
- Plugin architecture: dynamic discovery/registry of plugins and property providers.
- Event-driven design: central EventBridge dispatches macOS events (network, power, session) to SHIORI modules.
- Embedded script engine: decouples the core script evaluation (YAYA VM) from the Swift application.
- C/Swift bridging: uses a Bridging-Header to interoperate with C/C++ modules (FMO, YAYA).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% UI Layer
    subgraph "UI Layer"
        direction TB
        OurinApp["OurinApp"]:::ui
        Entry["main.swift"]:::ui
        Content["ContentView"]:::ui
        About["AboutView"]:::ui
        DevTools["DevToolsView"]:::ui
        GhostV["GhostView"]:::ui
        BalloonV["BalloonView"]:::ui
        NarInstallV["NarInstallView"]:::ui
        Assets["Assets.xcassets"]:::ui
    end

    %% Application Services Layer
    subgraph "Application Services Layer"
        direction TB
        AnimEngine["AnimationEngine"]:::services
        GhostMgr["GhostManager"]:::services
        BalloonSub["Balloon Subsystem"]:::services
        Headline["HeadlineHost"]:::services
        NarInstaller["NarInstaller"]:::services
        LogStore["LogStore"]:::services
        PropMgr["PropertyManager"]:::services
        ResBridge["ResourceBridge"]:::services
    end

    %% Protocol / Event Layer
    subgraph "Protocol / Event Layer"
        direction TB
        SHIORI["EventBridge & Observers"]:::protocol
        SSTP["SSTP Servers & Router"]:::protocol
        PluginDisp["PluginEventDispatcher"]:::protocol
        WebAPI["WebHandler & WebNarInstaller"]:::protocol
    end

    %% Native Bridge & Embedded Engine Layer
    subgraph "Native Bridge & Embedded Engine Layer"
        direction TB
        FMO["FMO Bridge"]:::native
        Bridging["Ourin-Bridging-Header"]:::native
        YAYA["YAYA Core Subsystem"]:::native
    end

    %% Persistence / Utilities Layer
    subgraph "Persistence / Utilities Layer"
        direction TB
        UtilsLog["Log.swift"]:::util
        ProcessKill["ProcessKiller"]:::util
        Sync["SyncCenter"]:::util
        Metrics["ServerMetrics"]:::util
    end

    %% Relationships
    OurinApp -->|"invoke services"| GhostMgr
    Content -->|"render request"| AnimEngine
    DevTools -->|"install flow"| NarInstaller
    GhostMgr -->|"subscribe events"| SHIORI
    AnimEngine -->|"publish events"| SHIORI
    SHIORI -->|"route messages"| PluginDisp
    SSTP -->|"incoming SSTP message"| PluginDisp
    GhostMgr -->|"script exec"| YAYA
    FMO -->|"shared memory"| GhostMgr
    NarInstaller -->|"write logs"| LogStore
    AnimEngine -->|"write logs"| LogStore
    LogStore -->|"persist"| UtilsLog
    SSTP -->|"metrics"| Metrics

    %% Click events UI
    click OurinApp "https://github.com/eightman999/ourin/blob/master/Ourin/OurinApp.swift"
    click Entry "https://github.com/eightman999/ourin/blob/master/Ourin/main.swift"
    click Content "https://github.com/eightman999/ourin/blob/master/Ourin/ContentView.swift"
    click About "https://github.com/eightman999/ourin/blob/master/Ourin/About/AboutView.swift"
    click DevTools "https://github.com/eightman999/ourin/blob/master/Ourin/DevTools/DevToolsView.swift"
    click GhostV "https://github.com/eightman999/ourin/blob/master/Ourin/Ghost/BalloonView.swift"
    click BalloonV "https://github.com/eightman999/ourin/blob/master/Ourin/Balloon/BalloonView.swift"
    click NarInstallV "https://github.com/eightman999/ourin/blob/master/Ourin/NarInstall/NarInstallView.swift"
    click Assets "https://github.com/eightman999/ourin/blob/master/Ourin/Assets.xcassets"

    %% Click events Services
    click AnimEngine "https://github.com/eightman999/ourin/blob/master/Ourin/Animation/AnimationEngine.swift"
    click GhostMgr "https://github.com/eightman999/ourin/blob/master/Ourin/Ghost/GhostManager.swift"
    click BalloonSub "https://github.com/eightman999/ourin/blob/master/Ourin/Balloon/DescriptorLoader.swift"
    click Headline "https://github.com/eightman999/ourin/blob/master/Ourin/HeadlineHost/HeadlineModule.swift"
    click NarInstaller "https://github.com/eightman999/ourin/blob/master/Ourin/NarInstall/LocalNarInstaller.swift"
    click LogStore "https://github.com/eightman999/ourin/blob/master/Ourin/LogStore.swift"
    click PropMgr "https://github.com/eightman999/ourin/blob/master/Ourin/Property/PropertyManager.swift"
    click ResBridge "https://github.com/eightman999/ourin/blob/master/Ourin/ResourceBridge.swift"

    %% Click events Protocol/Event
    click SHIORI "https://github.com/eightman999/ourin/blob/master/Ourin/SHIORIEvents/EventBridge.swift"
    click SSTP "https://github.com/eightman999/ourin/blob/master/Ourin/ExternalServer/SstpTcpServer.swift"
    click PluginDisp "https://github.com/eightman999/ourin/blob/master/Ourin/PluginEvent/PluginEventDispatcher.swift"
    click WebAPI "https://github.com/eightman999/ourin/blob/master/Ourin/Web/WebHandler.swift"

    %% Click events Native
    click FMO "https://github.com/eightman999/ourin/blob/master/Ourin/FMO/FmoBridge.c"
    click Bridging "https://github.com/eightman999/ourin/blob/master/Ourin/Ourin-Bridging-Header.h"
    click YAYA "https://github.com/eightman999/ourin/tree/master/yaya_core/"

    %% Click events Utils
    click UtilsLog "https://github.com/eightman999/ourin/blob/master/Ourin/Utils/Log.swift"
    click ProcessKill "https://github.com/eightman999/ourin/blob/master/Ourin/Utils/ProcessKiller.swift"
    click Sync "https://github.com/eightman999/ourin/blob/master/Ourin/Utils/SyncCenter.swift"
    click Metrics "https://github.com/eightman999/ourin/blob/master/Ourin/ExternalServer/ServerMetrics.swift"

    %% Styles
    classDef ui fill:#ccffcc,stroke:#333,stroke-width:1px
    classDef services fill:#ccf,stroke:#333,stroke-width:1px
    classDef protocol fill:#ffdd99,stroke:#333,stroke-width:1px
    classDef native fill:#e0ccff,stroke:#333,stroke-width:1px
    classDef util fill:#dddddd,stroke:#333,stroke-width:1px
```
