# neechko/mokachan architecture

> Architecture diagram of the GitHub repository neechko/mokachan, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/neechko/mokachan
- Repository: https://github.com/neechko/mokachan

## Overview

Mokachan is a Discord bot whose main workflows are AI companion chat with persistent memory and channel-based character spawns that users can claim into collections. Lyrics lookup is a separate command capability. The README documents the broader command set; sampled source confirms detailed wiring mainly for AI chat, lyrics, collection browsing, and admin grants, so other command links are omitted where call ownership is not evidenced.

Main entry points: [`index.js`](https://github.com/neechko/mokachan/blob/master/index.js) (Bot router), [`src/database.js`](https://github.com/neechko/mokachan/blob/master/src/database.js) (SQLite state), [`src/characterSource.js`](https://github.com/neechko/mokachan/blob/master/src/characterSource.js) (Character source pool), [`src/commands/ai.js`](https://github.com/neechko/mokachan/blob/master/src/commands/ai.js) (AI chat handler)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Discord runtime"]
  node_router["Bot router<br/>[index.js]"]
  node_matcher["Command matcher<br/>[commandMatcher.js]"]
  node_lyrics["Lyrics command<br/>[lyrics.js]"]
  node_historycmd["History commands<br/>[history.js]"]
  node_database[("SQLite state<br/>[database.js]")]
  node_maintenance["Database maintenance<br/>[maintenance.js]"]
end

subgraph group_companion["AI companion"]
  node_ai["AI chat handler<br/>[ai.js]"]
  node_memory["Companion memory<br/>[companion.js]"]
end

subgraph group_collectibles["Character collectibles"]
  node_collectioncmd["Collection browser<br/>[koleksi.js]"]
  node_claimcmd["Claim command<br/>[claim.js]"]
  node_admincard["Admin card grant<br/>[adminCard.js]"]
  node_spawn["Spawn scheduler<br/>[characterSpawn.js]"]
  node_sources["Character source pool<br/>[characterSource.js]"]
  node_rarity["Rarity mapping<br/>[rarity.js]"]
end

subgraph group_integrations["External integrations"]
  node_gemini["Gemini client<br/>[gemini.js]"]
  node_anilist["AniList provider<br/>[anilist.js]"]
  node_tenrai["Tenrai provider<br/>[tenrai.js]"]
  node_genshin["Genshin provider<br/>[genshin.js]"]
  node_genshindb["GenshinDB provider<br/>[genshindb.js]"]
end

node_user(("Discord user"))
node_discord(("Discord platform"))
node_lyricsapi["LRCLIB"]
node_geminiapi["Gemini API"]
node_anilistapi["AniList API"]
node_tenraiapi["Tenrai API"]
node_genshinapi["Genshin APIs"]

node_user -->|"sends commands"| node_discord
node_discord -->|"delivers messages"| node_router
node_router -->|"matches commands"| node_matcher
node_router -->|"dispatches chat"| node_ai
node_router -->|"dispatches lyrics"| node_lyrics
node_router -->|"dispatches claims"| node_claimcmd
node_router -->|"dispatches collection"| node_collectioncmd
node_router -->|"dispatches grants"| node_admincard
node_router -->|"dispatches history"| node_historycmd
node_router -->|"connects client"| node_discord
node_ai -->|"builds context"| node_memory
node_ai -->|"requests reply"| node_gemini
node_ai -->|"saves chat log"| node_database
node_memory -->|"reads and saves memory"| node_database
node_memory -->|"summarizes memory"| node_gemini
node_memory -->|"reads channel context"| node_discord
node_gemini -->|"sends requests"| node_geminiapi
node_ai -->|"sends response"| node_discord
node_lyrics -->|"searches lyrics"| node_lyricsapi
node_lyrics -->|"posts lyrics"| node_discord
node_spawn -->|"requests character"| node_sources
node_spawn -->|"tracks channel spawn"| node_database
node_spawn -->|"posts spawn"| node_discord
node_claimcmd -->|"claims active spawn"| node_database
node_claimcmd -->|"confirms claim"| node_discord
node_collectioncmd -->|"reads collection"| node_database
node_collectioncmd -->|"labels characters"| node_rarity
node_collectioncmd -->|"displays collection"| node_discord
node_admincard -->|"searches characters"| node_sources
node_admincard -->|"grants card"| node_database
node_admincard -->|"confirms grant"| node_discord
node_sources -->|"queries source"| node_anilist
node_sources -->|"queries source"| node_tenrai
node_sources -->|"queries source"| node_genshin
node_sources -->|"queries source"| node_genshindb
node_anilist -->|"fetches character data"| node_anilistapi
node_tenrai -->|"fetches character data"| node_tenraiapi
node_genshin -->|"fetches character data"| node_genshinapi
node_genshindb -->|"fetches character data"| node_genshinapi
node_maintenance -->|"checks database"| node_database
node_router -->|"runs maintenance"| node_maintenance

click node_router "https://github.com/neechko/mokachan/blob/master/index.js"
click node_matcher "https://github.com/neechko/mokachan/blob/master/src/commandMatcher.js"
click node_lyrics "https://github.com/neechko/mokachan/blob/master/lyrics.js"
click node_historycmd "https://github.com/neechko/mokachan/blob/master/src/commands/history.js"
click node_collectioncmd "https://github.com/neechko/mokachan/blob/master/src/commands/koleksi.js"
click node_claimcmd "https://github.com/neechko/mokachan/blob/master/src/commands/claim.js"
click node_admincard "https://github.com/neechko/mokachan/blob/master/src/commands/adminCard.js"
click node_ai "https://github.com/neechko/mokachan/blob/master/src/commands/ai.js"
click node_memory "https://github.com/neechko/mokachan/blob/master/src/companion.js"
click node_gemini "https://github.com/neechko/mokachan/blob/master/src/gemini.js"
click node_spawn "https://github.com/neechko/mokachan/blob/master/src/characterSpawn.js"
click node_sources "https://github.com/neechko/mokachan/blob/master/src/characterSource.js"
click node_anilist "https://github.com/neechko/mokachan/blob/master/src/anilist.js"
click node_tenrai "https://github.com/neechko/mokachan/blob/master/src/tenrai.js"
click node_genshin "https://github.com/neechko/mokachan/blob/master/src/genshin.js"
click node_genshindb "https://github.com/neechko/mokachan/blob/master/src/genshindb.js"
click node_rarity "https://github.com/neechko/mokachan/blob/master/src/rarity.js"
click node_database "https://github.com/neechko/mokachan/blob/master/src/database.js"
click node_maintenance "https://github.com/neechko/mokachan/blob/master/src/maintenance.js"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_router,node_matcher,node_lyrics,node_historycmd,node_database,node_maintenance,node_user toneBlue
class node_ai,node_memory toneAmber
class node_collectioncmd,node_claimcmd,node_admincard,node_spawn,node_sources,node_rarity,node_geminiapi,node_anilistapi,node_tenraiapi,node_genshinapi toneMint
class node_gemini,node_anilist,node_tenrai,node_genshin,node_genshindb toneRose
class node_discord,node_lyricsapi toneIndigo
```

## Components

### Discord runtime

- [Bot router](https://github.com/neechko/mokachan/blob/master/index.js): `index.js`
- [Command matcher](https://github.com/neechko/mokachan/blob/master/src/commandMatcher.js): `src/commandMatcher.js`
- [Lyrics command](https://github.com/neechko/mokachan/blob/master/lyrics.js): `lyrics.js`
- [History commands](https://github.com/neechko/mokachan/blob/master/src/commands/history.js): `src/commands/history.js`
- [SQLite state](https://github.com/neechko/mokachan/blob/master/src/database.js): `src/database.js`
- [Database maintenance](https://github.com/neechko/mokachan/blob/master/src/maintenance.js): `src/maintenance.js`

### AI companion

- [AI chat handler](https://github.com/neechko/mokachan/blob/master/src/commands/ai.js): `src/commands/ai.js`
- [Companion memory](https://github.com/neechko/mokachan/blob/master/src/companion.js): `src/companion.js`

### Character collectibles

- [Collection browser](https://github.com/neechko/mokachan/blob/master/src/commands/koleksi.js): `src/commands/koleksi.js`
- [Claim command](https://github.com/neechko/mokachan/blob/master/src/commands/claim.js): `src/commands/claim.js`
- [Admin card grant](https://github.com/neechko/mokachan/blob/master/src/commands/adminCard.js): `src/commands/adminCard.js`
- [Spawn scheduler](https://github.com/neechko/mokachan/blob/master/src/characterSpawn.js): `src/characterSpawn.js`
- [Character source pool](https://github.com/neechko/mokachan/blob/master/src/characterSource.js): `src/characterSource.js`
- [Rarity mapping](https://github.com/neechko/mokachan/blob/master/src/rarity.js): `src/rarity.js`

### External integrations

- [Gemini client](https://github.com/neechko/mokachan/blob/master/src/gemini.js): `src/gemini.js`
- [AniList provider](https://github.com/neechko/mokachan/blob/master/src/anilist.js): `src/anilist.js`
- [Tenrai provider](https://github.com/neechko/mokachan/blob/master/src/tenrai.js): `src/tenrai.js`
- [Genshin provider](https://github.com/neechko/mokachan/blob/master/src/genshin.js): `src/genshin.js`
- [GenshinDB provider](https://github.com/neechko/mokachan/blob/master/src/genshindb.js): `src/genshindb.js`

### Other components

- **Discord user**
- **Discord platform**
- **LRCLIB**
- **Gemini API**
- **AniList API**
- **Tenrai API**
- **Genshin APIs**

## Connections

- Discord user → Discord platform: sends commands
- Discord platform → Bot router: delivers messages
- Bot router → Command matcher: matches commands
- Bot router → AI chat handler: dispatches chat
- Bot router → Lyrics command: dispatches lyrics
- Bot router → Claim command: dispatches claims
- Bot router → Collection browser: dispatches collection
- Bot router → Admin card grant: dispatches grants
- Bot router → History commands: dispatches history
- Bot router → Discord platform: connects client
- AI chat handler → Companion memory: builds context
- AI chat handler → Gemini client: requests reply
- AI chat handler → SQLite state: saves chat log
- Companion memory → SQLite state: reads and saves memory
- Companion memory → Gemini client: summarizes memory
- Companion memory → Discord platform: reads channel context
- Gemini client → Gemini API: sends requests
- AI chat handler → Discord platform: sends response
- Lyrics command → LRCLIB: searches lyrics
- Lyrics command → Discord platform: posts lyrics
- Spawn scheduler → Character source pool: requests character
- Spawn scheduler → SQLite state: tracks channel spawn
- Spawn scheduler → Discord platform: posts spawn
- Claim command → SQLite state: claims active spawn
- Claim command → Discord platform: confirms claim
- Collection browser → SQLite state: reads collection
- Collection browser → Rarity mapping: labels characters
- Collection browser → Discord platform: displays collection
- Admin card grant → Character source pool: searches characters
- Admin card grant → SQLite state: grants card
- Admin card grant → Discord platform: confirms grant
- Character source pool → AniList provider: queries source
- Character source pool → Tenrai provider: queries source
- Character source pool → Genshin provider: queries source
- Character source pool → GenshinDB provider: queries source
- AniList provider → AniList API: fetches character data
- Tenrai provider → Tenrai API: fetches character data
- Genshin provider → Genshin APIs: fetches character data
- GenshinDB provider → Genshin APIs: fetches character data
- Database maintenance → SQLite state: checks database
- Bot router → Database maintenance: runs maintenance