# ittzspsv/lilyv2 architecture

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

- Interactive diagram: https://gitdiagram.com/ittzspsv/lilyv2
- Repository: https://github.com/ittzspsv/lilyv2

## Overview

1. **Overall shape**
   - This is a **Discord.py multi-module bot** organized as a set of optional **cogs/modules** under `src/`.
   - The architecture is intentionally plugin-like: each major feature area has its own package, commands, components, and sometimes persistence layer.

2. **Bot entry and integration boundary**
   - `src/sDiscordIntegration.py` appears to be the main integration layer that ties the bot together with Discord.
   - From there, the bot loads feature cogs and routes Discord events/commands into the appropriate module.

3. **Module-level decomposition**
   - Core bot capabilities are split into independent domains:
     - **Moderation**
     - **Management / staff tools**
     - **Logging**
     - **Utility**
     - **Leveling / economy**
     - **Ticketing**
     - **Rulesets / permissions**
     - **Vouching**
     - **Security**
     - **Music**
     - **GTO** and **Substring** utilities
     - **Blox Fruits** game support
     - **Grow a Garden / algorithms** support
   - The README explicitly says modules are removable/replaceable, which is important for diagramming the system boundary.

4. **Shared configuration and constants**
   - `src/Config/` holds global configuration objects such as bot details and value/config data.
   - Root data files like `src/ValueData.json`, `src/nsfw.json`, and `configs.txt` suggest centralized lookup tables and runtime settings used across modules.
   - This config layer is a shared dependency for many feature packages.

5. **Persistence and storage layer**
   - The bot uses a mix of **SQLite databases** and **JSON files** under `storage/`.
   - Databases are separated by domain:
     - `storage/configs/Configs.db`, `ValueData.db`, `ComboData.db`
     - `storage/levels/Levels.db`
     - `storage/logs/Logs.db`
     - `storage/management/staff_management.db`
     - `storage/music/Music.db`
   - JSON files are used for smaller or more static view/config state, such as ticket views and automod config.
   - `aiosqlite` in the README indicates async DB access is part of the architecture.

6. **Moderation, logging, and security flow**
   - `LilyModeration`, `LilyLogging`, `LilySecurity`, and `LilyRulesets` form a policy-and-enforcement layer.
   - Moderation has command handlers, UI components, database access, and utilities, so the flow is: Discord action → moderation command/event → DB/logging side effects → response/embeds.
   - Logging is a distinct subsystem for error/debug/audit output, likely consuming moderation and management events.

7. **Staff management subsystem**
   - `LilyManagement` contains a dedicated staff management domain with:
     - command layer
     - UI components
     - database access
     - type definitions
   - This suggests staff records and profiles are persisted separately from moderation data, with a clear domain boundary.

8. **Leveling / economy subsystem**
   - `LilyLeveling` includes a core engine, commands, and components, backed by `Levels.db`.
   - The README shows profile cards and leaderboards, so the flow is: activity tracking → level/xp updates → card/image rendering → Discord message output.
   - This module is visually oriented but still data-driven through persistent progression state.

9. **Ticketing and dashboard-like interaction surfaces**
   - `LilyTicketTool` is a self-contained workflow with core logic, thread support, command layer, components, and persisted view/config files.
   - `LilyDashboard` and `LilyUtilityComponents` indicate reusable UI/interaction components for Discord messages, selects, buttons, and embeds rather than a separate web dashboard.
   - The architecture favors Discord-native interaction UIs over external frontends.

10. **Blox Fruits game-support subsystem**
   - This is one of the largest domain-specific areas in the repo.
   - It is split into:
     - `commands` for Discord interactions
     - `components` for UI surfaces
     - `core` for calculations, fruit detection, trade formatting, and suggestion logic
     - `modules/combo` for combo management
     - a cache layer in `sLilyBloxFruitsCache.py`
   - This module likely processes user-provided trade/inventory data, calculates outcomes, and renders game-specific images and embeds.

11. **Blox Fruits data-processing and image pipeline**
   - `src/ui/` contains generators for stock images, fruit values, combos, profile cards, win/loss cards, greeting cards, and background manipulation.
   - `src/Misc/` contains downloader/fetcher helpers and shared embed/component helpers.
   - The key flow here is: domain data → algorithm/calculation layer → image generation layer → Discord embed or attachment.
   - Pillow is a major dependency because visuals are part of the module output, not just decoration.

12. **Algorithmic sanitization and content analysis**
   - `src/LilyAlgorthims/` contains specialized detection/processing routines such as:
     - link scam detection
     - NSFW detection
     - stock processing
   - These appear to be reusable safety/validation helpers consumed by moderation, security, or content-related commands.
   - They form a lightweight analytics layer rather than a user-facing module.

13. **Utility and identity helpers**
   - `LilyUtility` provides general-purpose bot behaviors such as greetings, tags, utility commands, and shared utility components.
   - `LilyEngagement` and `LilyVouching` cover interaction and reputation-style features.
   - These are cross-cutting modules that support presentation and community features rather than core enforcement or domain logic.

14. **Important architectural boundary**
   - The repo is not organized around one monolith service; it is organized around **Discord cogs plus shared helper layers**.
   - The stable boundaries are:
     - Discord event/command entry points
     - domain modules
     - shared algorithms/utilities
     - storage/persistence
     - image/UI rendering
   - That separation is the main thing to preserve in an architecture diagram.

Main entry points: [`src/sDiscordIntegration.py`](https://github.com/ittzspsv/lilyv2/blob/main/src/sDiscordIntegration.py) (Discord bot), [`src/LilyBloxFruits/sLilyBloxFruitsCore.py`](https://github.com/ittzspsv/lilyv2/blob/main/src/LilyBloxFruits/sLilyBloxFruitsCore.py) (Blox Fruits), [`src/LilyModeration/sLilyModeration.py`](https://github.com/ittzspsv/lilyv2/blob/main/src/LilyModeration/sLilyModeration.py) (Moderation), [`src/LilyUtility/sLilyUtility.py`](https://github.com/ittzspsv/lilyv2/blob/main/src/LilyUtility/sLilyUtility.py) (Utility)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Integration"]
  node_integration["Discord bot<br/>integration layer"]
end

subgraph group_features["Feature Cogs"]
  node_moderation["Moderation<br/>discord cog<br/>[sLilyModeration.py]"]
  node_management["Staff mgmt<br/>discord cog"]
  node_logging["Logging<br/>discord cog<br/>[sLilyLogging.py]"]
  node_utility["Utility<br/>discord cog<br/>[sLilyUtility.py]"]
  node_leveling["Leveling<br/>progression cog"]
  node_ticketing["Tickets<br/>workflow cog"]
  node_rulesets["Rulesets<br/>policy cog<br/>[sLilyRulesets.py]"]
  node_security["Security<br/>safety cog<br/>[sLilySecurity.py]"]
  node_vouching["Vouching<br/>reputation cog<br/>[sLilyVouchCore.py]"]
  node_music["Music"]
  node_blox["Blox Fruits<br/>domain module"]
  node_gto["GTO<br/>utility cog<br/>[LilyGTOCommands.py]"]
  node_substring["Substring<br/>utility cog<br/>[sLilySubstring.py]"]
  node_engagement["Engagement<br/>community cog<br/>[LilyEngagement.py]"]
end

subgraph group_shared["Shared Layers"]
  node_config["Config<br/>[sBotDetails.py]"]
  node_valuecfg["Value data<br/>shared config<br/>[sValueConfig.py]"]
  node_algos{{"Algorithms<br/>analysis helpers"}}
  node_misc["Embeds & media<br/>helper layer<br/>[sLilyEmbed.py]"]
end

subgraph group_storage["Persistence"]
  node_storagecfg[("Config store<br/>sqlite/json store<br/>[Configs.db]")]
  node_storagelevels[("Levels DB<br/>sqlite store<br/>[Levels.db]")]
  node_storagelogs[("Logs DB<br/>sqlite store<br/>[Logs.db]")]
  node_storagemanagement[("Staff DB<br/>sqlite/json store")]
  node_storagemusic[("Music DB<br/>sqlite store<br/>[Music.db]")]
  node_storageviews["Views JSON<br/>json store<br/>[TicketViews.json]"]
end

subgraph group_present["UI Rendering"]
  node_ui["Image UI<br/>rendering pipeline"]
end

node_integration -->|"loads"| node_config
node_integration -->|"loads"| node_moderation
node_integration -->|"loads"| node_management
node_integration -->|"loads"| node_logging
node_integration -->|"loads"| node_utility
node_integration -->|"loads"| node_leveling
node_integration -->|"loads"| node_ticketing
node_integration -->|"loads"| node_blox
node_integration -->|"loads"| node_music
node_integration -->|"loads"| node_rulesets
node_integration -->|"loads"| node_security
node_integration -->|"loads"| node_vouching
node_integration -->|"loads"| node_gto
node_integration -->|"loads"| node_substring
node_integration -->|"loads"| node_engagement
node_moderation -->|"uses"| node_algos
node_moderation -->|"writes"| node_storagelogs
node_moderation -->|"reads/writes"| node_storagecfg
node_management -->|"persists"| node_storagemanagement
node_logging -->|"persists"| node_storagelogs
node_utility -->|"uses"| node_misc
node_utility -->|"renders"| node_ui
node_leveling -->|"persists"| node_storagelevels
node_leveling -->|"renders"| node_ui
node_ticketing -->|"persists"| node_storageviews
node_ticketing -->|"uses"| node_misc
node_blox -->|"uses"| node_algos
node_blox -->|"renders"| node_ui
node_blox -->|"reads"| node_config
node_blox -->|"persists"| node_storagecfg
node_music -->|"persists"| node_storagemusic
node_security -->|"uses"| node_algos
node_rulesets -->|"reads"| node_config

click node_integration "https://github.com/ittzspsv/lilyv2/blob/main/src/sDiscordIntegration.py"
click node_config "https://github.com/ittzspsv/lilyv2/blob/main/src/Config/sBotDetails.py"
click node_valuecfg "https://github.com/ittzspsv/lilyv2/blob/main/src/Config/sValueConfig.py"
click node_algos "https://github.com/ittzspsv/lilyv2/blob/main/src/LilyAlgorthims/sNSFWDetectionAlgorthim.py"
click node_misc "https://github.com/ittzspsv/lilyv2/blob/main/src/Misc/sLilyEmbed.py"
click node_moderation "https://github.com/ittzspsv/lilyv2/blob/main/src/LilyModeration/sLilyModeration.py"
click node_management "https://github.com/ittzspsv/lilyv2/blob/main/src/LilyManagement/sLilyStaffManagement.py"
click node_logging "https://github.com/ittzspsv/lilyv2/blob/main/src/LilyLogging/sLilyLogging.py"
click node_utility "https://github.com/ittzspsv/lilyv2/blob/main/src/LilyUtility/sLilyUtility.py"
click node_leveling "https://github.com/ittzspsv/lilyv2/blob/main/src/LilyLeveling/core/sLilyLevelingCore.py"
click node_ticketing "https://github.com/ittzspsv/lilyv2/blob/main/src/LilyTicketTool/LilyTicketToolCore.py"
click node_rulesets "https://github.com/ittzspsv/lilyv2/blob/main/src/LilyRulesets/sLilyRulesets.py"
click node_security "https://github.com/ittzspsv/lilyv2/blob/main/src/LilySecurity/sLilySecurity.py"
click node_vouching "https://github.com/ittzspsv/lilyv2/blob/main/src/LilyVouching/sLilyVouchCore.py"
click node_music "https://github.com/ittzspsv/lilyv2/blob/main/src/LilyMusic/sLilyMusicCommands.py"
click node_blox "https://github.com/ittzspsv/lilyv2/blob/main/src/LilyBloxFruits/sLilyBloxFruitsCore.py"
click node_gto "https://github.com/ittzspsv/lilyv2/blob/main/src/LilyGTO/LilyGTOCommands.py"
click node_substring "https://github.com/ittzspsv/lilyv2/blob/main/src/LilySubstring/sLilySubstring.py"
click node_engagement "https://github.com/ittzspsv/lilyv2/blob/main/src/LilyEngagement/LilyEngagement.py"
click node_ui "https://github.com/ittzspsv/lilyv2/blob/main/src/ui/sProfileCardGenerator.py"
click node_storagecfg "https://github.com/ittzspsv/lilyv2/blob/main/storage/configs/Configs.db"
click node_storagelevels "https://github.com/ittzspsv/lilyv2/blob/main/storage/levels/Levels.db"
click node_storagelogs "https://github.com/ittzspsv/lilyv2/blob/main/storage/logs/Logs.db"
click node_storagemanagement "https://github.com/ittzspsv/lilyv2/blob/main/storage/management/staff_management.db"
click node_storagemusic "https://github.com/ittzspsv/lilyv2/blob/main/storage/music/Music.db"
click node_storageviews "https://github.com/ittzspsv/lilyv2/blob/main/storage/view/TicketViews.json"

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_integration toneBlue
class node_moderation,node_management,node_logging,node_utility,node_leveling,node_ticketing,node_rulesets,node_security,node_vouching,node_music,node_blox,node_gto,node_substring,node_engagement toneAmber
class node_config,node_valuecfg,node_algos,node_misc toneMint
class node_storagecfg,node_storagelevels,node_storagelogs,node_storagemanagement,node_storagemusic,node_storageviews toneRose
class node_ui toneIndigo
```

## Components

### Integration

Bot startup and Discord event boundary

- [Discord bot](https://github.com/ittzspsv/lilyv2/blob/main/src/sDiscordIntegration.py): integration layer · Main Discord.py integration and module loader · `src/sDiscordIntegration.py`

### Feature Cogs

Optional Discord modules grouped by domain

- [Moderation](https://github.com/ittzspsv/lilyv2/blob/main/src/LilyModeration/sLilyModeration.py): discord cog · Command and policy enforcement module · `src/LilyModeration/sLilyModeration.py`
- [Staff mgmt](https://github.com/ittzspsv/lilyv2/blob/main/src/LilyManagement/sLilyStaffManagement.py): discord cog · Staff management domain and commands · `src/LilyManagement/sLilyStaffManagement.py`
- [Logging](https://github.com/ittzspsv/lilyv2/blob/main/src/LilyLogging/sLilyLogging.py): discord cog · Audit and error logging module · `src/LilyLogging/sLilyLogging.py`
- [Utility](https://github.com/ittzspsv/lilyv2/blob/main/src/LilyUtility/sLilyUtility.py): discord cog · General bot utilities and community helpers · `src/LilyUtility/sLilyUtility.py`
- [Leveling](https://github.com/ittzspsv/lilyv2/blob/main/src/LilyLeveling/core/sLilyLevelingCore.py): progression cog · XP, profiles, and leaderboard flow · `src/LilyLeveling/core/sLilyLevelingCore.py`
- [Tickets](https://github.com/ittzspsv/lilyv2/blob/main/src/LilyTicketTool/LilyTicketToolCore.py): workflow cog · Ticket creation and view workflows · `src/LilyTicketTool/LilyTicketToolCore.py`
- [Rulesets](https://github.com/ittzspsv/lilyv2/blob/main/src/LilyRulesets/sLilyRulesets.py): policy cog · Rules and permissions enforcement · `src/LilyRulesets/sLilyRulesets.py`
- [Security](https://github.com/ittzspsv/lilyv2/blob/main/src/LilySecurity/sLilySecurity.py): safety cog · Security and protective checks · `src/LilySecurity/sLilySecurity.py`
- [Vouching](https://github.com/ittzspsv/lilyv2/blob/main/src/LilyVouching/sLilyVouchCore.py): reputation cog · Trust and vouching workflows · `src/LilyVouching/sLilyVouchCore.py`
- [Music](https://github.com/ittzspsv/lilyv2/blob/main/src/LilyMusic/sLilyMusicCommands.py): music cog · Music command surface and external runtime config · `src/LilyMusic/sLilyMusicCommands.py`
- [Blox Fruits](https://github.com/ittzspsv/lilyv2/blob/main/src/LilyBloxFruits/sLilyBloxFruitsCore.py): domain module · Large game-support subsystem for calculations, trades, and combos · `src/LilyBloxFruits/sLilyBloxFruitsCore.py`
- [GTO](https://github.com/ittzspsv/lilyv2/blob/main/src/LilyGTO/LilyGTOCommands.py): utility cog · Specialized command module · `src/LilyGTO/LilyGTOCommands.py`
- [Substring](https://github.com/ittzspsv/lilyv2/blob/main/src/LilySubstring/sLilySubstring.py): utility cog · Specialized text utility module · `src/LilySubstring/sLilySubstring.py`
- [Engagement](https://github.com/ittzspsv/lilyv2/blob/main/src/LilyEngagement/LilyEngagement.py): community cog · Interaction-oriented feature module · `src/LilyEngagement/LilyEngagement.py`

### Shared Layers

Reusable config, algorithms, helpers, and presentation primitives

- [Config](https://github.com/ittzspsv/lilyv2/blob/main/src/Config/sBotDetails.py): shared config · Global bot and value configuration · `src/Config/sBotDetails.py`
- [Value data](https://github.com/ittzspsv/lilyv2/blob/main/src/Config/sValueConfig.py): shared config · Shared value/config data for modules · `src/Config/sValueConfig.py`
- [Algorithms](https://github.com/ittzspsv/lilyv2/blob/main/src/LilyAlgorthims/sNSFWDetectionAlgorthim.py): analysis helpers · Reusable detection and processing routines · `src/LilyAlgorthims/sNSFWDetectionAlgorthim.py`
- [Embeds & media](https://github.com/ittzspsv/lilyv2/blob/main/src/Misc/sLilyEmbed.py): helper layer · Shared embed, component, and downloader helpers · `src/Misc/sLilyEmbed.py`

### Persistence

Databases and JSON state used across modules

- [Config store](https://github.com/ittzspsv/lilyv2/blob/main/storage/configs/Configs.db): sqlite/json store · Shared config and value databases plus automod JSON · `storage/configs/Configs.db`
- [Levels DB](https://github.com/ittzspsv/lilyv2/blob/main/storage/levels/Levels.db): sqlite store · Progression persistence · `storage/levels/Levels.db`
- [Logs DB](https://github.com/ittzspsv/lilyv2/blob/main/storage/logs/Logs.db): sqlite store · Audit and logging persistence · `storage/logs/Logs.db`
- [Staff DB](https://github.com/ittzspsv/lilyv2/blob/main/storage/management/staff_management.db): sqlite/json store · Staff management persistence · `storage/management/staff_management.db`
- [Music DB](https://github.com/ittzspsv/lilyv2/blob/main/storage/music/Music.db): sqlite store · Music subsystem persistence · `storage/music/Music.db`
- [Views JSON](https://github.com/ittzspsv/lilyv2/blob/main/storage/view/TicketViews.json): json store · Persisted ticket view state · `storage/view/TicketViews.json`

### UI Rendering

Image and visual output pipeline

- [Image UI](https://github.com/ittzspsv/lilyv2/blob/main/src/ui/sProfileCardGenerator.py): rendering pipeline · Generators for cards, stock images, greetings, and effects · `src/ui/sProfileCardGenerator.py`

## Connections

- Discord bot → Config: loads · Bootstraps shared bot configuration
- Discord bot → Moderation: loads · Registers feature cogs into Discord
- Discord bot → Staff mgmt: loads · Registers staff management module
- Discord bot → Logging: loads · Registers logging module
- Discord bot → Utility: loads · Registers utility commands
- Discord bot → Leveling: loads · Registers progression subsystem
- Discord bot → Tickets: loads · Registers ticket workflows
- Discord bot → Blox Fruits: loads · Registers game-support domain
- Discord bot → Music: loads · Registers music module
- Discord bot → Rulesets: loads · Registers policy enforcement layer
- Discord bot → Security: loads · Registers security checks
- Discord bot → Vouching: loads · Registers reputation features
- Discord bot → GTO: loads · Registers specialized utility module
- Discord bot → Substring: loads · Registers specialized text module
- Discord bot → Engagement: loads · Registers community engagement module
- Moderation → Algorithms: uses · Relies on detection and content analysis helpers
- Moderation → Logs DB: writes · Records moderation activity and audit trail
- Moderation → Config store: reads/writes · Uses automod and shared config state
- Staff mgmt → Staff DB: persists · Stores staff records and profiles
- Logging → Logs DB: persists · Stores log events and diagnostics
- Utility → Embeds & media: uses · Shares embed and interaction helpers
- Utility → Image UI: renders · Produces visual utility outputs
- Leveling → Levels DB: persists · Stores XP and profile progression
- Leveling → Image UI: renders · Builds profile and leaderboard cards
- Tickets → Views JSON: persists · Stores ticket views and selectors
- Tickets → Embeds & media: uses · Uses shared component and embed helpers
- Blox Fruits → Algorithms: uses · Uses fruit detection, trade, and stock processing
- Blox Fruits → Image UI: renders · Generates combo, stock, and trade visuals
- Blox Fruits → Config: reads · Uses shared config and value data
- Blox Fruits → Config store: persists · Uses combo/value/config databases
- Music → Music DB: persists · Stores music state and settings
- Security → Algorithms: uses · Consumes scanning and detection helpers
- Rulesets → Config: reads · Uses shared policy/config values
