# mimokit/todaywaifu architecture

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

- Interactive diagram: https://gitdiagram.com/mimokit/todaywaifu
- Repository: https://github.com/mimokit/todaywaifu

## Overview

TodayWaifu is a GsCore chat plugin for daily character and member draws, image delivery, and related social commands. The main user flow is a chat command selecting a feature, resolving candidates from local resources or the optional remote gallery, recording daily results where applicable, and sending text or images. The README documents feature-specific image-source settings and local fallback for gallery mode. The graph retains documented feature branches; several implementation links are dashed because the available excerpts do not show their runtime call sites.

Main entry points: [`TodayWaifu/daily.py`](https://github.com/mimokit/todaywaifu/blob/main/TodayWaifu/daily.py) (Daily draws), [`TodayWaifu/gallery.py`](https://github.com/mimokit/todaywaifu/blob/main/TodayWaifu/gallery.py) (Remote gallery), [`TodayWaifu/roles.py`](https://github.com/mimokit/todaywaifu/blob/main/TodayWaifu/roles.py) (Role candidates), [`TodayWaifu/senders.py`](https://github.com/mimokit/todaywaifu/blob/main/TodayWaifu/senders.py) (Image senders)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_commands["Chat features"]
  node_daily["Daily draws<br/>[daily.py]"]
  node_normal["Normal draws<br/>[normal_wife.py]"]
  node_loli["Loli and shota<br/>[loli.py]"]
  node_pgr["PGR draws<br/>[pgr.py]"]
  node_social["Role actions<br/>[gift.py]"]
  node_custom["Custom roles<br/>[custom_role.py]"]
  node_help["Help command<br/>[help.py]"]
end

subgraph group_candidates["Candidate sources"]
  node_roles["Role candidates<br/>[roles.py]"]
  node_members["Member candidates<br/>[members.py]"]
  node_gallery["Remote gallery<br/>[gallery.py]"]
  node_localgallery["Folder gallery<br/>[folder_gallery.py]"]
end

subgraph group_records["Records and state"]
  node_domain["Domain records<br/>[domain.py]"]
  node_daily_store[("Daily persistence<br/>[daily_store.py]")]
  node_repository["Context registry"]
end

subgraph group_delivery["Image delivery"]
  node_senders["Image senders<br/>[senders.py]"]
  node_filecache[("File cache<br/>[file_cache.py]")]
end

subgraph group_support["Shared runtime"]
  node_shared["Shared services<br/>[shared.py]"]
  node_state["Runtime state<br/>[state.py]"]
  node_executor["IO executor<br/>[executor.py]"]
  node_config["Feature config"]
end

node_user(("Chat user"))
node_gscore(("GsCore bot"))
node_gallery_service{{"Gallery service"}}

node_user -->|"sends command"| node_gscore
node_gscore -.->|"routes commands"| node_daily
node_daily -.->|"offers feature"| node_normal
node_daily -.->|"resolves roles"| node_roles
node_daily -.->|"draws members"| node_members
node_normal -.->|"resolves roles"| node_roles
node_loli -.->|"resolves candidates"| node_roles
node_pgr -.->|"uses folders"| node_localgallery
node_roles -.->|"loads candidates"| node_gallery
node_gallery -->|"requests images"| node_gallery_service
node_gallery -->|"falls back locally"| node_localgallery
node_daily -.->|"records results"| node_daily_store
node_daily_store -->|"coordinates contexts"| node_repository
node_repository -->|"uses registry"| node_state
node_daily -.->|"delivers results"| node_senders
node_senders -->|"downloads images"| node_gallery
node_senders -.->|"uses image cache"| node_filecache
node_senders -.->|"sends messages"| node_gscore
node_social -.->|"updates records"| node_daily_store
node_custom -.->|"adds candidates"| node_roles
node_help -.->|"returns help"| node_gscore
node_shared -->|"exposes state"| node_state
node_gallery -->|"caches downloads"| node_filecache
node_gallery -.->|"offloads IO"| node_executor
node_daily -.->|"reads settings"| node_config

click node_daily "https://github.com/mimokit/todaywaifu/blob/main/TodayWaifu/daily.py"
click node_normal "https://github.com/mimokit/todaywaifu/blob/main/TodayWaifu/normal_wife.py"
click node_loli "https://github.com/mimokit/todaywaifu/blob/main/TodayWaifu/loli.py"
click node_pgr "https://github.com/mimokit/todaywaifu/blob/main/TodayWaifu/pgr.py"
click node_social "https://github.com/mimokit/todaywaifu/blob/main/TodayWaifu/gift.py"
click node_custom "https://github.com/mimokit/todaywaifu/blob/main/TodayWaifu/custom_role.py"
click node_help "https://github.com/mimokit/todaywaifu/blob/main/TodayWaifu/help.py"
click node_roles "https://github.com/mimokit/todaywaifu/blob/main/TodayWaifu/roles.py"
click node_members "https://github.com/mimokit/todaywaifu/blob/main/TodayWaifu/members.py"
click node_gallery "https://github.com/mimokit/todaywaifu/blob/main/TodayWaifu/gallery.py"
click node_localgallery "https://github.com/mimokit/todaywaifu/blob/main/TodayWaifu/folder_gallery.py"
click node_domain "https://github.com/mimokit/todaywaifu/blob/main/TodayWaifu/domain.py"
click node_daily_store "https://github.com/mimokit/todaywaifu/blob/main/TodayWaifu/daily_store.py"
click node_repository "https://github.com/mimokit/todaywaifu/blob/main/TodayWaifu/daily_repository.py"
click node_senders "https://github.com/mimokit/todaywaifu/blob/main/TodayWaifu/senders.py"
click node_filecache "https://github.com/mimokit/todaywaifu/blob/main/TodayWaifu/file_cache.py"
click node_shared "https://github.com/mimokit/todaywaifu/blob/main/TodayWaifu/shared.py"
click node_state "https://github.com/mimokit/todaywaifu/blob/main/TodayWaifu/state.py"
click node_executor "https://github.com/mimokit/todaywaifu/blob/main/TodayWaifu/executor.py"
click node_config "https://github.com/mimokit/todaywaifu/blob/main/daily_wife_config.py"

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_daily,node_normal,node_loli,node_pgr,node_social,node_custom,node_help,node_user toneBlue
class node_roles,node_members,node_gallery,node_localgallery toneAmber
class node_domain,node_daily_store,node_repository toneMint
class node_senders,node_filecache toneRose
class node_shared,node_state,node_executor,node_config,node_gscore,node_gallery_service toneIndigo
```

## Components

### Chat features

- [Daily draws](https://github.com/mimokit/todaywaifu/blob/main/TodayWaifu/daily.py): `TodayWaifu/daily.py`
- [Normal draws](https://github.com/mimokit/todaywaifu/blob/main/TodayWaifu/normal_wife.py): `TodayWaifu/normal_wife.py`
- [Loli and shota](https://github.com/mimokit/todaywaifu/blob/main/TodayWaifu/loli.py): `TodayWaifu/loli.py`
- [PGR draws](https://github.com/mimokit/todaywaifu/blob/main/TodayWaifu/pgr.py): `TodayWaifu/pgr.py`
- [Role actions](https://github.com/mimokit/todaywaifu/blob/main/TodayWaifu/gift.py): `TodayWaifu/gift.py`
- [Custom roles](https://github.com/mimokit/todaywaifu/blob/main/TodayWaifu/custom_role.py): `TodayWaifu/custom_role.py`
- [Help command](https://github.com/mimokit/todaywaifu/blob/main/TodayWaifu/help.py): `TodayWaifu/help.py`

### Candidate sources

- [Role candidates](https://github.com/mimokit/todaywaifu/blob/main/TodayWaifu/roles.py): `TodayWaifu/roles.py`
- [Member candidates](https://github.com/mimokit/todaywaifu/blob/main/TodayWaifu/members.py): `TodayWaifu/members.py`
- [Remote gallery](https://github.com/mimokit/todaywaifu/blob/main/TodayWaifu/gallery.py): `TodayWaifu/gallery.py`
- [Folder gallery](https://github.com/mimokit/todaywaifu/blob/main/TodayWaifu/folder_gallery.py): `TodayWaifu/folder_gallery.py`

### Records and state

- [Domain records](https://github.com/mimokit/todaywaifu/blob/main/TodayWaifu/domain.py): `TodayWaifu/domain.py`
- [Daily persistence](https://github.com/mimokit/todaywaifu/blob/main/TodayWaifu/daily_store.py): `TodayWaifu/daily_store.py`
- [Context registry](https://github.com/mimokit/todaywaifu/blob/main/TodayWaifu/daily_repository.py): `TodayWaifu/daily_repository.py`

### Image delivery

- [Image senders](https://github.com/mimokit/todaywaifu/blob/main/TodayWaifu/senders.py): `TodayWaifu/senders.py`
- [File cache](https://github.com/mimokit/todaywaifu/blob/main/TodayWaifu/file_cache.py): `TodayWaifu/file_cache.py`

### Shared runtime

- [Shared services](https://github.com/mimokit/todaywaifu/blob/main/TodayWaifu/shared.py): `TodayWaifu/shared.py`
- [Runtime state](https://github.com/mimokit/todaywaifu/blob/main/TodayWaifu/state.py): `TodayWaifu/state.py`
- [IO executor](https://github.com/mimokit/todaywaifu/blob/main/TodayWaifu/executor.py): `TodayWaifu/executor.py`
- [Feature config](https://github.com/mimokit/todaywaifu/blob/main/daily_wife_config.py): `daily_wife_config.py`

### Other components

- **Chat user**
- **GsCore bot**
- **Gallery service**

## Connections

- Chat user → GsCore bot: sends command (evidence: `README.md`)
- GsCore bot → Daily draws: routes commands
- Daily draws → Normal draws: offers feature
- Daily draws → Role candidates: resolves roles
- Daily draws → Member candidates: draws members
- Normal draws → Role candidates: resolves roles
- Loli and shota → Role candidates: resolves candidates
- PGR draws → Folder gallery: uses folders (evidence: `TodayWaifu/pgr.py`)
- Role candidates → Remote gallery: loads candidates (evidence: `TodayWaifu/gallery.py`)
- Remote gallery → Gallery service: requests images (evidence: `README.md`)
- Remote gallery → Folder gallery: falls back locally (evidence: `README.md`)
- Daily draws → Daily persistence: records results
- Daily persistence → Context registry: coordinates contexts (evidence: `TodayWaifu/daily_store.py`)
- Context registry → Runtime state: uses registry (evidence: `TodayWaifu/state.py`)
- Daily draws → Image senders: delivers results
- Image senders → Remote gallery: downloads images (evidence: `TodayWaifu/senders.py`)
- Image senders → File cache: uses image cache (evidence: `TodayWaifu/senders.py`)
- Image senders → GsCore bot: sends messages
- Role actions → Daily persistence: updates records
- Custom roles → Role candidates: adds candidates
- Help command → GsCore bot: returns help
- Shared services → Runtime state: exposes state (evidence: `TodayWaifu/shared.py`)
- Remote gallery → File cache: caches downloads (evidence: `TodayWaifu/gallery.py`)
- Remote gallery → IO executor: offloads IO (evidence: `TodayWaifu/gallery.py`)
- Daily draws → Feature config: reads settings
