# kissinglucifer/tachi architecture

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

- Interactive diagram: https://gitdiagram.com/kissinglucifer/tachi
- Repository: https://github.com/kissinglucifer/tachi

## Overview

##### Project Type and Purpose
- Tachi is a **monorepo** containing multiple loosely coupled services:
– **client/**: React SPA (AGPL3)
– **server/**: Express/TypeScript REST & gRPC API, import pipelines (AGPL3)
– **bot/**: Discord bot (MIT)
– **github-bot/**: GitHub automation (MIT)
– **common/**: Shared types & utilities (MIT)
– **seeds/**: Static JSON data for songs/charts (UNLICENSE)
– **docs/** & **homepage/**: Documentation sites (MIT)
– **sieglinde/**: BMS/PMS analysis library (MIT)
- Purpose: track, analyze, and display rhythm-game scores; provide both web UI and chat/automation frontends.

##### File Structure
- Top-level folders map to individual deployable services or libraries.
- Each service has its own Dockerfile and Justfile—implying containerized, independently deployable units.
- **server/** is layered:
– API routes → handler libraries → data-access (MongoDB/Redis) → import worker queues → external gRPC & file-based integrators.
- **client/** follows a typical React + Vite structure with contexts, components, routes, utilities.
- **common/** is published as an NPM package for cross-service sharing.
- **seeds/** holds source-of-truth data, loaded by server import scripts.
- CI/CD workflows under `.github/workflows` orchestrate builds, tests, and deploys per-service.

##### Extract Key Architectural Insights from the README
- Services are “fairly decoupled” – you could replace the client or bot without touching the server.
- Emphasis on “modular” and “powerful” score-import engine in the backend.
- Recommended development within a Dev Container or Docker Compose, indicating a container-based microservices approach.

##### Diagramming the Main Components & Their Interactions
a. **Main Runtime Components**
– **React Client** (browser)
– **Express/TypeScript API Server**
- REST endpoints (HTTP/JSON)
- gRPC services (proto-generated)
- Worker queue for score imports
– **MongoDB** (primary data store)
– **Redis** (caching, rate-limiting, job locks)
– **Discord Bot** (node service calling Server HTTP API & Webhooks)
– **GitHub Bot** (node service using GitHub APIs & Server Webhooks)
– **CDN/S3** (static assets: game banners, user banners)
– **Static Docs/Website** (MkDocs & Vite-built homepage)
– **Seeds Import Scripts** (read from `seeds/` JSON into Mongo)
– **External Game APIs** (various IR and API-based score sources)
b. **Relationships & Data Flows**
1. User ⇄ Browser React Client ⇄ HTTP(S) ⇄ API Server
2. API Server ⇄ MongoDB & Redis
3. API Server ⇄ Worker Queue (internal hourly/daily jobs)
4. API Server → S3 for uploads & CDN URL generation
5. Discord Bot & GitHub Bot → HTTP/Webhook calls → API Server
6. Import Workers → external game-specific APIs (via common library) → data ingestion → MongoDB
7. Seeds Loader Scripts → read `seeds/` JSON → write to MongoDB (initial setup or migrations)
8. Docs & Homepage are served statically (no DB) after CI/CD build.
c. **Architectural Patterns & Principles**
– **Microservices/Polyrepo-in-Monorepo**: each service owns its domain and runtime.
– **Layered Backend**: Router → Service/Import Framework → Data Access.
– **Shared Kernel**: `common/` package holds domain primitives.
– **Eventual Consistency**: Import jobs queue updates; workers process asynchronously.
– **Container-First**: Dockerfiles per service; orchestrated via Docker Compose or Kubernetes.
– **Infrastructure as Code**: Dev Container, Justfiles, GitHub Actions.

##### Critical Details
- Service as its own deployable unit with its Dockerfile.
- Distinguish between synchronous (REST/gRPC) and asynchronous (worker queue) interactions.
- Shared dependencies (`common/`) and seed data flows.
- CI/CD triggers (Git push → GitHub Actions → build & deploy per service).

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Frontend Layer
    subgraph "Frontend Layer"
        RC["React Client"]:::service
    end

    %% Backend/API Layer
    subgraph "Backend/API Layer"
        API["Express API Server"]:::service
        REST["REST API Routes"]:::service
        GRPC["gRPC Services"]:::service
        WorkerQueue["Import Worker Queue & Worker"]:::service
    end

    %% Data Layer
    subgraph "Data Layer"
        Mongo["MongoDB"]:::data
        Redis["Redis"]:::data
        S3["S3/CDN"]:::data
    end

    %% Integration Layer
    subgraph "Integration Layer"
        Discord["Discord Bot"]:::service
        GHBot["GitHub Bot"]:::service
        GameAPI["External Game APIs"]:::external
        Seeds["Seeds Loader"]:::service
    end

    %% Static Layer
    subgraph "Static Layer"
        Docs["Documentation Site"]:::service
        Home["Static Homepage"]:::service
    end

    %% Dev/Ops
    subgraph "Dev/Ops"
        CI["CI/CD Workflows"]:::service
        Common["Shared Common Package"]:::external
    end

    %% Relationships
    RC -->|HTTP/JSON| API
    API -->|routes| REST
    API -->|gRPC calls| GRPC
    API -->|queus jobs| WorkerQueue
    API -->|reads/writes| Mongo
    API -->|caches| Redis
    API -->|uploads assets| S3

    WorkerQueue -->|async ingest| GameAPI
    Seeds -->|initial load| Mongo

    Discord -->|HTTP/Webhooks| API
    GHBot -->|HTTP/Webhooks| API

    Docs -->|static serve| S3
    Home -->|static serve| S3

    CI -->|build & deploy| RC
    CI -->|build & deploy| API
    CI -->|build & deploy| Discord
    CI -->|build & deploy| GHBot
    CI -->|build & deploy| Docs
    CI -->|build & deploy| Home

    %% Shared Package Dependencies
    API -->|imports| Common
    WorkerQueue -->|imports| Common
    RC -->|imports| Common
    Discord -->|imports| Common
    GHBot -->|imports| Common
    Seeds -->|imports| Common

    %% Click Events
    click RC "https://github.com/kissinglucifer/tachi/tree/main/client/"
    click API "https://github.com/kissinglucifer/tachi/tree/main/server/"
    click REST "https://github.com/kissinglucifer/tachi/tree/main/server/src/server/router/api/"
    click GRPC "https://github.com/kissinglucifer/tachi/tree/main/server/src/proto/"
    click WorkerQueue "https://github.com/kissinglucifer/tachi/tree/main/server/src/lib/score-import/worker/"
    click Mongo "https://github.com/kissinglucifer/tachi/tree/main/server/src/external/mongo/"
    click Redis "https://github.com/kissinglucifer/tachi/tree/main/server/src/external/redis/"
    click Discord "https://github.com/kissinglucifer/tachi/tree/main/bot/"
    click GHBot "https://github.com/kissinglucifer/tachi/tree/main/github-bot/"
    click Common "https://github.com/kissinglucifer/tachi/tree/main/common/"
    click Seeds "https://github.com/kissinglucifer/tachi/tree/main/seeds/"
    click Docs "https://github.com/kissinglucifer/tachi/tree/main/docs/"
    click Home "https://github.com/kissinglucifer/tachi/tree/main/homepage/"
    click CI "https://github.com/kissinglucifer/tachi/tree/main/.github/workflows/"

    %% Styles
    classDef service fill:#add8e6,stroke:#036,stroke-width:1px;
    classDef data fill:#ffe4b5,stroke:#963,stroke-width:1px;
    classDef external fill:#98fb98,stroke:#262,stroke-width:1px;
    class WorkerQueue,GameAPI asyncStroke;
    classDef asyncStroke stroke-dasharray: 5 5;
```
