# mistval/kotoba architecture

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

- Interactive diagram: https://gitdiagram.com/mistval/kotoba
- Repository: https://github.com/mistval/kotoba

## Overview

##### Main Components
- Discord Bot – Housed under the “bot” directory. This component interacts with Discord (via Discord.js or similar) and includes its own set of commands, message processors, and helper utilities.
- API Server – Located in “api”. It is an Express-based backend providing endpoints for game operations, user data, and other functionalities. It also exposes routes (see “api/routes”) and utilities for game logic.
- Web Frontend – Found in the “kotobaweb” folder. This is a React application that displays the user interface, handles user interactions, and connects to the API.
- Worker Process – In the “worker” directory. Its role is to handle heavy-lifting tasks (like computing quiz statistics or rendering furigana) so that neither the API nor the bot’s event loop is blocked.
- Cloud Functions – Under “cloud_functions”. These comprise HTTP endpoints (for furigana and hispadic commands) that offload certain processing from the main bot/API.
- Nginx Proxy – The “nginx” directory holds configuration files for an Nginx server used to proxy web requests to both the frontend and API.
- Backup Tools – The “backup” directory provides scripts to backup user data, indicating an external process or scheduled task that interacts with the other systems.
- Resources – The “resources” directory contains non-code assets (dictionaries, fonts, images, quiz data) that are potentially used by multiple components (API, bot, web).

##### Relationships and Data Flows
- The Web Frontend (React) communicates with the API server via HTTP (or possibly WebSocket for real-time features).
- The API server might further interact with shared code (from “node-common” and “common”) and databases (MongoDB, as indicated in the README by configuration instructions).
- The Discord Bot interacts with both Discord (external integration) and internal services such as the Worker (sending HTTP requests to offload heavy tasks) and the Cloud Functions endpoints.
- The Nginx proxy sits in front of the web components and the API server, directing incoming HTTP requests appropriately.
- The Worker process receives HTTP requests from both the Bot and (potentially) the API for computational tasks, such as calculating quiz statistics.
- The Cloud Functions – deployed on platforms like Google Cloud – are triggered by the Bot (or possibly user actions) and provide results for specialized queries (like furigana and hispadic lookup).

##### Architectural Patterns and Design Principles
- Separation of Concerns – Components (bot, API, and frontend) are cleanly separated so that they can evolve independently.
- Microservices-like Communication – Even if not microservices in a strict sense, the use of HTTP for inter-process communication suggests loosely coupled pieces.
- Shared libraries – Common and node-common indicate adherence to the DRY principle by reusing code across components.
- Offloading intensive operations – The use of a Worker process and Cloud Functions shows that computation-heavy tasks are isolated, ensuring responsiveness in user-facing services.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User-Facing Components
    subgraph "User-Facing Components"
        webFrontend["Kotoba Web Frontend (React)"]
        discordBot["Kotoba Discord Bot"]
    end

    %% Backend Services
    subgraph "Backend Services"
        nginxProxy["Nginx Proxy"]
        apiServer["Kotoba API Server (Express)"]
        workerProcess["Kotoba Worker Process"]
        cloudFunctions["Kotoba Cloud Functions"]
    end

    %% Shared & Support
    subgraph "Shared & Support"
        commonLib["Common Library"]
        nodeCommonLib["Node Common Library"]
        backupTools["Backup Tools"]
        resources["Resources (Assets)"]
    end

    %% External Systems
    subgraph "External Systems"
        discord["Discord"]
        mongodb["MongoDB"]
    end

    %% Data Flows
    nginxProxy -->|"HTTPproxy"| webFrontend
    nginxProxy -->|"HTTPproxy"| apiServer
    webFrontend -->|"HTTPrequests"| apiServer
    apiServer -->|"uses"| commonLib
    apiServer -->|"uses"| nodeCommonLib
    apiServer -->|"accesses"| mongodb
    apiServer -->|"utilizes"| resources
    apiServer -->|"offloadsTasks"| workerProcess
    discordBot -->|"interacts"| discord
    discordBot -->|"offloads"| workerProcess
    discordBot -->|"calls"| cloudFunctions
    discordBot -->|"uses"| commonLib
    discordBot -->|"uses"| nodeCommonLib
    backupTools -->|"backsUp"| mongodb
    backupTools -->|"utilizes"| resources

    %% Click Events
    click discordBot "https://github.com/mistval/kotoba/tree/master/bot/"
    click apiServer "https://github.com/mistval/kotoba/tree/master/api/"
    click webFrontend "https://github.com/mistval/kotoba/tree/master/kotobaweb/"
    click workerProcess "https://github.com/mistval/kotoba/tree/master/worker/"
    click cloudFunctions "https://github.com/mistval/kotoba/tree/master/cloud_functions/"
    click commonLib "https://github.com/mistval/kotoba/tree/master/common/"
    click nodeCommonLib "https://github.com/mistval/kotoba/tree/master/node-common/"
    click nginxProxy "https://github.com/mistval/kotoba/tree/master/nginx/"
    click backupTools "https://github.com/mistval/kotoba/tree/master/backup/"
    click resources "https://github.com/mistval/kotoba/tree/master/resources/"

    %% Styles
    classDef frontend fill:#cfe2f3,stroke:#0b5394,stroke-width:2px;
    classDef backend fill:#d9ead3,stroke:#38761d,stroke-width:2px;
    classDef support fill:#fff2cc,stroke:#e69138,stroke-width:2px;
    classDef external fill:#f4cccc,stroke:#cc0000,stroke-width:2px;

    class webFrontend,discordBot frontend;
    class apiServer,workerProcess,cloudFunctions,nginxProxy backend;
    class commonLib,nodeCommonLib,backupTools,resources support;
    class discord,mongodb external;
```
