# syuilo/ai architecture

> Architecture diagram of the GitHub repository syuilo/ai, 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/syuilo/ai
- Repository: https://github.com/syuilo/ai

## Overview

##### Project Type and Purpose
- This project is a bot tailored for the Misskey social network. It functions as an AI assistant that can post notes and interact with users. The bot is implemented in Node.js and is designed to integrate with Misskey’s API.
- The README and file structure confirm that it supports both local Node.js execution and containerized deployment via Docker. The configuration file (config.json, based on example.json) and memory persistence (memory.json) are key to its operation.

##### Key Directories and Architectural Components
- Core Source Code: The “src” directory is the heart of the application. It includes entry points (index.ts), AI logic (ai.ts), configuration (config.ts), and utility functions (contained in “src/utils”).
- Modules: The “src/modules” folder contains a variety of submodules each responsible for different bot features – commands such as aichat, birthday, chart rendering, dice game, reversi game, poll, reminder, and more. This suggests a plugin-like, extensible architecture.
- Misskey Interaction: Inside “src/misskey” you find files like note.ts and user.ts which handle interactions with Misskey’s note posting, user management, and related functionality.
- External Concerns: The project also includes Docker-related files (Dockerfile, docker-compose.yml), configuration helpers, and even a memory persistence mechanism (memory.json) that acts as an in-memory database for saving state.

##### Main Components
a. Configuration & Initialization
- Component: Configuration Manager (loads config.json and sets runtime parameters)
- Role: Initializes parameters such as API keys, enabled modules, MeCab paths and memory directory.

b. Core Engine
- Component: Bot Engine (src/index.ts, module loader in src/module.ts, core module in src/modules/core)
- Role: Acts as the entry point; loads and initializes each module; manages routing commands to modules.

c. Modular Command Handlers
- Component: Individual Modules (each subdirectory under src/modules)
- Role: Each module (e.g., aichat, birthday, chart, dice, reversi, poll) implements a specific feature of the bot. They are dynamically invoked based on user input or scheduled tasks.

d. Misskey API Interaction
- Component: Misskey Client (src/misskey folder)
- Role: Handles API requests/responses with Misskey. Manages note creation, user data retrieval, and possibly real-time stream data.

e. Utility Layer
- Component: Utility Functions (src/utils)
- Role: Provides helper functions for logging, date handling, string manipulation, URL conversions, etc.

f. Persistence Layer
- Component: Memory Storage (memory.json)
- Role: Acts as the statekeeper, storing session and historical data in a JSON file.

g. Docker & Deployment
- Component: Containerization & Build Scripts
- Role: Dockerfile, docker-compose.yml, and related configuration for deploying in containerized environments.

##### Relationships and Data Flow
- The “Core Engine” communicates with the “Misskey API Interaction” component both for receiving incoming notes and sending messages/responses.
- Each module in the “Modular Command Handlers” block may interact with the utilities and the persistence layer as needed (for example, the “noting” module storing data in memory.json).
- Docker wraps the entire application, emphasizing how the different components are packaged together with environment-specific configuration (e.g., MeCab enablement).

##### Architectural Patterns and Design Principles
- Modularity: The project clearly follows a modular design, where each feature is isolated in its own subdirectory under “src/modules”. Emphasize loose coupling between modules via a central module loader.
- Extensibility: Since adding a new module is as simple as placing a new directory under the modules folder, show how new functionalities extend the core engine.
- Separation of Concerns: Distinct areas for configuration, business logic (modules), Misskey interfacing, and utility functions.

##### Technologies, Frameworks, and Libraries
- Node.js for the runtime execution.
- TypeScript (as indicated by the .ts files, and tsconfig.json) for the codebase.
- Docker for containerization (Dockerfile, docker-compose.yml).
- Optionally, MeCab is used for natural language processing if the keyword module is enabled.
- External APIs are consumed (Gemini Pro API and PLaMo API) for certain AI functionalities.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Internal Node.js Components
    subgraph "Internal Node.js Components"
        config["Configuration Manager"]
        core["Core Bot Engine"]
        loader["Module Loader"]
        subgraph "Modular Command Handlers"
            aichat["aichat Module"]
            birthday["birthday Module"]
            chart["chart Module"]
            dice["dice Module"]
            reversi["reversi Module"]
            poll["poll Module"]
            reminder["reminder Module"]
        end
        utils["Utility Functions"]
        memory["Memory Storage"]
    end

    %% Misskey Interaction
    subgraph "Misskey Interaction"
        subgraph "Misskey Client"
            note["Note Handler"]
            user["User Handler"]
        end
    end

    %% Deployment & Containerization
    subgraph "Deployment & Containerization"
        dockerfile["Dockerfile"]
        dockerCompose["docker-compose.yml"]
    end

    %% Data Flow Connections
    config -->|"initializes"| core
    core -->|"loads"| loader

    loader -->|"invokes"| aichat
    loader -->|"invokes"| birthday
    loader -->|"invokes"| chart
    loader -->|"invokes"| dice
    loader -->|"invokes"| reversi
    loader -->|"invokes"| poll
    loader -->|"invokes"| reminder

    core -->|"communicates_with"| note
    core -->|"communicates_with"| user

    aichat -->|"uses"| utils
    birthday -->|"uses"| utils
    chart -->|"uses"| utils
    dice -->|"uses"| utils
    reversi -->|"uses"| utils
    poll -->|"uses"| utils
    reminder -->|"uses"| utils

    aichat -->|"persists_to"| memory
    birthday -->|"persists_to"| memory
    chart -->|"persists_to"| memory
    dice -->|"persists_to"| memory
    reversi -->|"persists_to"| memory
    poll -->|"persists_to"| memory
    reminder -->|"persists_to"| memory

    dockerfile --- dockerCompose
    dockerfile --- config
    dockerfile --- core

    note --- user

    %% Click Events
    click config "https://github.com/syuilo/ai/blob/master/src/config.ts"
    click core "https://github.com/syuilo/ai/blob/master/src/index.ts"
    click loader "https://github.com/syuilo/ai/blob/master/src/module.ts"
    click aichat "https://github.com/syuilo/ai/tree/master/src/modules/aichat"
    click birthday "https://github.com/syuilo/ai/tree/master/src/modules/birthday"
    click chart "https://github.com/syuilo/ai/tree/master/src/modules/chart"
    click dice "https://github.com/syuilo/ai/tree/master/src/modules/dice"
    click reversi "https://github.com/syuilo/ai/tree/master/src/modules/reversi"
    click poll "https://github.com/syuilo/ai/tree/master/src/modules/poll"
    click reminder "https://github.com/syuilo/ai/tree/master/src/modules"
    click utils "https://github.com/syuilo/ai/tree/master/src/utils"
    click memory "https://github.com/syuilo/ai/blob/master/memory.json"
    click note "https://github.com/syuilo/ai/blob/master/src/misskey/note.ts"
    click user "https://github.com/syuilo/ai/blob/master/src/misskey/user.ts"
    click dockerfile "https://github.com/syuilo/ai/tree/master/Dockerfile"
    click dockerCompose "https://github.com/syuilo/ai/blob/master/docker-compose.yml"

    %% Styles
    classDef config fill:#FFEEAD,stroke:#333,stroke-width:2px;
    classDef core fill:#CFFFB3,stroke:#333,stroke-width:2px;
    classDef loader fill:#ADD8E6,stroke:#333,stroke-width:2px;
    classDef module fill:#FFB7CE,stroke:#333,stroke-width:2px;
    classDef misc fill:#D3D3D3,stroke:#333,stroke-width:2px;
    classDef external fill:#FFD700,stroke:#333,stroke-width:2px;
    classDef deploy fill:#B0E0E6,stroke:#333,stroke-width:2px;

    class config config;
    class core core;
    class loader loader;
    class aichat,birthday,chart,dice,reversi,poll,reminder module;
    class utils,memory misc;
    class note,user external;
    class dockerfile,dockerCompose deploy;
```
