How kissinglucifer/tachi works
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).