# nullsora/kotodama architecture

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

- Interactive diagram: https://gitdiagram.com/nullsora/kotodama
- Repository: https://github.com/nullsora/kotodama

## Overview

##### Project Type and Purpose
- Kotodama is a third-party Onebot client. Its primary purpose is to connect to a Onebot-compliant backend (using a WebSocket “ws” connection) and provide an interface for managing chats, contacts, groups, and various message types.
- The README emphasizes that this desktop client supports chat functions, message rendering (with specialized components for messages, contacts, settings, etc.), and customization features (like Light/Dark mode and theme settings).

##### Analyzing the File Structure
- Top-Level Structure: Notice configuration files such as .eslintrc, package.json, and tsconfig files, which set up the build/linting environment.
- src Directory:
- The "src/main" directory contains the Electron main process code. Within it are subdirectories like “connection” (for connecting to the Onebot backend) and “registry” (which appears to bundle utility functionalities such as connector management, file handling, protocol definitions, and window control).
- The "src/preload" directory holds the preload scripts. This code exposes selected functionalities to the renderer while maintaining security boundaries.
- The "src/renderer" directory encompasses the entire Vue.js-based user interface. It includes HTML, Vue single file components (SFCs) for different UI parts (chat, contact, message, layout, settings, etc.), assets (images, fonts), state management (Pinia stores), and utility functions.

a. Main Components:
- Electron Main Process: Responsible for bootstrapping the application, handling system-level events, and bridging native capabilities (found in src/main).
- Preload Script: The middleware (in src/preload) that safely exposes APIs from the main process to the renderer.
- Renderer Process: The Vue.js app (in src/renderer) that manages the user interface, chat components, and state management.
- External Onebot Server: Since the client connects to a Onebot backend via a WebSocket connection, include this as an external system.
- Utility/Registry Modules: Components like connection handling, file management, protocol translation, and window control, which are defined in the registry subdirectory.

b. Relationships and Interactions:
- Data Flow: The renderer sends user interactions to the main process (through the preload API) which in turn communicates with the external Onebot server.
- IPC Communication: Clearly show the inter-process communication (IPC) channel from the renderer to the main process (mediated by preload scripts).
- Internal Dependencies: The main process modules (like the connection/connector.ts and registry components) encapsulate the logic for connecting to the server and managing data.

c. Architectural Patterns and Design Principles:
- Separation of Concerns: The architecture distinctly separates the UI (renderer) from backend logic (main process) and secure API exposure (preload).
- Modularization: The registry directory further modularizes functions like file management, window control, and protocol management.
- Client-Server Communication: The use of websockets and a Onebot API emphasizes a client-server paradigm where the client listens to incoming messages and sends outgoing commands.

d. Mention Key Technologies:
- Electron to bundle and run a desktop application.
- Vue.js (and PrimeVue) for building the reactive user interface.
- TypeScript for improved maintainability and safety.
- Electron-Vite which streamlines development and build processes.
- UnoCSS for utility-first CSS styling.

## Diagram (Mermaid)

```mermaid
flowchart TD
    D1["Renderer Process (Vue App)"]:::renderer
    C1["Preload Scripts"]:::preload
    M1["Electron Main Process"]:::electron
    B1["Connection Handling Module"]:::electron
    B2["Registry Modules"]:::electron
    A1["External Onebot Server"]:::external

    D1 -->|"IPC"| C1
    C1 -->|"IPC"| M1
    M1 -->|"calls"| B1
    M1 -->|"calls"| B2
    B1 -->|"WebSocket"| A1
    A1 -->|"pushMessage"| B1
    B1 -->|"uses"| B2

    click M1 "https://github.com/nullsora/kotodama/tree/main/src/main"
    click B1 "https://github.com/nullsora/kotodama/blob/main/src/main/connection/connector.ts"
    click B2 "https://github.com/nullsora/kotodama/tree/main/src/main/registry"
    click C1 "https://github.com/nullsora/kotodama/tree/main/src/preload"
    click D1 "https://github.com/nullsora/kotodama/tree/main/src/renderer"

    classDef electron fill:#ffcc00,stroke:#333,stroke-width:2px;
    classDef preload fill:#8cd3ff,stroke:#333,stroke-width:2px;
    classDef renderer fill:#b3f7b3,stroke:#333,stroke-width:2px;
    classDef external fill:#f8a398,stroke:#333,stroke-width:2px;
```
