# otakustay/oniichan architecture

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

- Interactive diagram: https://gitdiagram.com/otakustay/oniichan
- Repository: https://github.com/otakustay/oniichan

## Overview

##### Main Components
- Kernel: Located in the packages/kernel directory, it embodies the decoupled core logic, including command processing, workflows, and inbox handling. It’s designed to run in an isolated environment (separate threads/processes) and is intended to be IDE-agnostic.
- Editor Host: Found in packages/editor-host, this component bridges the VS Code APIs to the kernel, effectively exposing the necessary IDE capabilities.
- VS Code Extension: In packages/vscode, which wraps the functionalities, user interfaces, and configuration for the extension within VS Code.
- Web & Web Host: The packages/web (a React-based client application) and packages/web-host provide a way to expose the kernel’s services via a web interface. The web-host adapts the kernel’s functions so that UI elements can be controlled remotely.
- Storage: Under packages/storage, this module provides local persistence functionality – ensuring that any file/database operations are centralized and consistent.
- Shared & Prompt: The shared library (packages/shared) contains common utilities, types, and shared models that multiple other modules rely on. The prompt module (packages/prompt) manages user prompting, formatting, and scaffold-related functions.

##### Relationships and Interactions
- The VS Code extension wraps around the Editor Host and Kernel, acting as the front-end for VS Code users. Illustrate that the VS Code module uses the Editor Host to communicate with the Kernel.
- The Web Host and Web client form another layer: the Web Host exposes standardized endpoints/services from the Kernel, while the Web client (React-based) communicates with the Web Host over WebSockets or API calls.
- The Prompt package, handling input parsing and user requests, interacts with the Kernel and possibly the shared messaging or command processing system.

##### Architectural Patterns and Design Principles
- Decoupling: Stress how the Kernel is designed to be IDE-agnostic, which allows it to be concurrently used by different “host” environments (Editor Host for VS Code, Web Host for web clients, and eventually other IDE integrations).
- Extensibility: The architecture makes it straightforward to plug in new interfaces or integrations (for example, adding a JetBrains host that mimics the Editor Host interface).

##### Relevant Technologies
- Node.js environment with TypeScript as indicated by the tsconfig files.
- React for the web client.
- VS Code API for the vscode extension component.
- Lerna and Nx to manage the monorepo structure.
- Communication methods such as WebSockets or IPC for inter-process communication, especially regarding the web-host and kernel interaction.

##### Capturing Essential Architectural Elements
- Explicitly indicate persistence through the Storage module and display the role of shared functions via the Shared package.
- Optionally, add a section/comments noting future possibilities (e.g., running Kernel in separate processes or exposing HTTP endpoints for CLI tools) to reflect the intended architectural flexibility.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Clients
    IDEClient["IDE Client\n(VS Code)"]:::external
    Browser["Browser Client\n(Web)"]:::external

    %% VS Code Subsystem
    vscode["VS Code Extension\n(UI & Config)"]:::host
    editor["Editor Host\n(VS Code API Bridge)"]:::host

    %% Kernel Core
    kernel["Kernel\n(Core Logic for workflows and commands)"]:::core

    %% Web Subsystem
    webclient["Web Client\n(React-based)"]:::host
    webhost["Web Host\n(Exposes Kernel services)"]:::host

    %% Supporting Modules
    storage["Storage\n(Local persistence)"]:::support
    prompt["Prompt Module\n(User input processing)"]:::support
    shared["Shared Library\n(Common utilities)"]:::support

    %% Connections - VS Code Side
    IDEClient -->|"launches"| vscode
    vscode -->|"uses"| editor
    editor -->|"calls"| kernel

    %% Connections - Web Side
    Browser -->|"loads"| webclient
    webclient -->|"requests"| webhost
    webhost -->|"forwardsTo"| kernel

    %% Kernel interactions with supporting modules
    kernel -->|"writesTo"| storage
    kernel -->|"triggers"| prompt

    %% Shared Library dependencies (dotted arrows)
    vscode -.->|"common"| shared
    editor -.->|"common"| shared
    kernel -.->|"common"| shared
    webhost -.->|"common"| shared
    prompt -.->|"common"| shared

    %% Click Events
    click kernel "https://github.com/otakustay/oniichan/tree/master/packages/kernel"
    click editor "https://github.com/otakustay/oniichan/tree/master/packages/editor-host"
    click vscode "https://github.com/otakustay/oniichan/tree/master/packages/vscode"
    click webhost "https://github.com/otakustay/oniichan/tree/master/packages/web-host"
    click webclient "https://github.com/otakustay/oniichan/tree/master/packages/web"
    click storage "https://github.com/otakustay/oniichan/tree/master/packages/storage"
    click shared "https://github.com/otakustay/oniichan/tree/master/packages/shared"
    click prompt "https://github.com/otakustay/oniichan/tree/master/packages/prompt"

    %% Styles
    classDef core fill:#FFD700,stroke:#D2691E,stroke-width:2px;
    classDef host fill:#90EE90,stroke:#228B22,stroke-width:2px;
    classDef support fill:#ADD8E6,stroke:#1E90FF,stroke-width:2px;
    classDef external fill:#FFEFD5,stroke:#CD853F,stroke-width:2px;
```
