How mistromy/nirupama works
1. High-level shape
- This repo is a multi-language Discord bot platform centered on a Python bot, with a smaller Go-based supervisor/launcher for operational control.
- It also includes a static marketing website and a set of prototype/archive code paths that show older or experimental bot implementations.
2. Primary runtime: pybot/
- The main production bot appears to live in pybot/, with main.py and launch.py as the likely entry points.
- The structure strongly suggests a discord.py-style cog architecture, where features are split into modular command/feature units under pybot/cogs/.
3. Feature modules inside the bot
- pybot/cogs/ separates the bot into domains such as:
- ai_core.py for AI chat behavior
- commands.py for general bot commands
- admin.py for server/operator controls
- tracking.py, uptime.py, uptimehealthchecks.py for activity and availability features
- vc.py for voice-channel-related behavior
- honeypot.py and privacypolicy.py for moderation/privacy concerns
- This is the main functional boundary: each cog owns a feature slice and is loaded into the Discord bot runtime.
4. Data and persistence layer
- pybot/data/ai_data.py indicates bot-specific persisted state or curated AI metadata.
- The README says user levels are tracked in Supabase Postgres, so the bot likely stores engagement/activity history externally rather than only in memory.
- The architecture therefore has two data paths: ephemeral runtime state inside the bot process and persistent user/activity data in Supabase.
5. Shared utility layer
- pybot/utils/ holds cross-cutting helpers used by multiple cogs:
- ai_interface.py abstracts AI provider interaction
- discord_helpers.py likely normalizes Discord embed/message handling
- levels.py and git_format.py support leveling and formatting logic
- logger.py centralizes logging
- ship.py, shipgenerator.html, and shiprenderer.py implement the project’s signature /ship-style relationship scoring/rendering feature
- This layer is the main internal boundary between business logic and reusable support code.
6. AI subsystem
- The repo treats AI as a distinct subsystem, not just a single command.
- ai_core.py, ai_interface.py, and the prototype files under TestsPrototypesAndIdeas/ show experimentation with multiple AI-related approaches and providers.
- The README makes clear the AI chatbot is evolving, so the architecture likely routes user messages through a moderation/feature layer before invoking an AI backend.
7. Operational/monitoring features
- Uptime monitoring is first-class: there are dedicated cogs for uptime and health checks, and the README references Cronitor.
- That means the bot is not only responding to Discord events, but also exposing health/heartbeat behavior for external monitoring.
- admin.py and tracking.py suggest separate operational and analytics concerns from normal user-facing commands.
8. Go supervisor and launch path
- The go/ tree is a separate subsystem with cmd/supervisor/main.go, bootstrap checks, bot prelaunch/launch code, and a TUI console.
- This looks like a process supervisor / launcher tool rather than the bot itself: it likely validates environment readiness, starts the bot, and gives the operator a terminal UI for status/control.
- internal/bootstrap/checks.go is especially important as a boundary for startup validation before the Python bot runs.
9. TUI and local control surface
- go/internal/tui/ and components/console/console.go indicate a text-based operational interface.
- Architecturally, this is the local human-control plane: a separate interface for launching, observing, or managing the bot process without going through Discord.
10. Public website
- The website/ directory is a standalone static site (index.html, script.js, styles.css) with its own README.
- It functions as the public entry point / landing page for adding the bot, which is consistent with the README’s “Add Nirupama Now!” call to action.
- The GitHub Actions workflow under .github/workflows/pages.yml suggests this site is deployed via GitHub Pages.
11. Project history and experimentation
- archive/ contains older bot and logging/reboot code, while TestsPrototypesAndIdeas/ contains assorted experiments and model/API test scripts.
- These directories are not core runtime paths, but they show how the bot’s architecture has evolved and where experimental AI or media features were tested before integration.
12. What matters for an architecture diagram
- The key diagram boundaries are:
- Discord API ↔ Python bot
- Python bot ↔ external services like Supabase, AI providers, and Cronitor
- Go supervisor/TUI ↔ Python bot process
- Static website ↔ GitHub Pages / user acquisition
- The repo is therefore best drawn as a Python feature-hosting bot with a separate Go control plane and a static web front-end, all surrounded by external Discord and cloud service dependencies.
Main entry points: main.py Bot entry · main.go Supervisor · ai_core.py AI core · index.html Landing site
Components 25
Python bot
Primary Discord bot runtime and feature modules
- Bot entry · Main Python bot startup path
pybot/main.py - Launch flow · Alternate Python launch/bootstrap path
pybot/launch.py - Commands · General bot commands and interaction surface
pybot/cogs/commands.py - Admin · Server and operator controls
pybot/cogs/admin.py - AI core · Chat and AI-driven bot behavior
pybot/cogs/ai_core.py - Tracking · Activity and usage tracking
pybot/cogs/tracking.py - Uptime · Availability and heartbeat features
pybot/cogs/uptime.py - Voice · Voice-channel behavior
pybot/cogs/vc.py - Privacy · Privacy policy and related handling
pybot/cogs/privacypolicy.py - AI interface · Abstraction over AI provider calls
pybot/utils/ai_interface.py - Ship feature · Relationship scoring and rendering helpers
pybot/utils/ship.py - Levels · Leveling and progression logic
pybot/utils/levels.py - AI data · Bot-specific AI metadata or persisted state
pybot/data/ai_data.py
Go control plane
Supervisor, bootstrap, and local TUI launcher
- Supervisor · Process supervisor and operator launcher
go/cmd/supervisor/main.go - Bootstrap checks · Environment and readiness validation before launch
go/internal/bootstrap/checks.go - Bot launch · Prelaunch and launch orchestration for the bot process
go/internal/bot/launch.go - TUI console · Local terminal control and status surface
go/internal/tui/tui.go
Archive & prototypes
Older implementations and experiment paths
- Legacy bot · Older bot implementation path
archive/bot.py - AI prototypes · Assorted AI and media experiment scripts
TestsPrototypesAndIdeas/chatgpt.py
External services
Third-party APIs and infrastructure used by the repo
- Discord · Chat platform event and command runtime
- Supabase · Persistent storage for user levels and activity
- AI providers · LLM and model endpoints used by the bot
- Cronitor · Uptime and health monitoring service
- GitHub Pages · Static hosting/deployment for the website
Connections 26
- Bot entry → Discord: connects to · Runs as a Discord bot
- Launch flow → Bot entry: starts · Launches the main bot runtime
- Bot entry → Commands: loads · Registers feature cogs
- Bot entry → Admin: loads · Registers feature cogs
- Bot entry → AI core: loads · Registers feature cogs
- Bot entry → Tracking: loads · Registers feature cogs
- Bot entry → Uptime: loads · Registers feature cogs
- Bot entry → Voice: loads · Registers feature cogs
- Bot entry → Privacy: loads · Registers feature cogs
- Commands → Levels: uses · Shares progression logic
- AI core → AI interface: uses · Routes prompts through AI abstraction
- AI core → AI data: reads · Uses curated AI data and state
- Tracking → Supabase: stores · Persists usage and level data
- Levels → Supabase: stores · Reads/writes persistent leveling data
- Uptime → Cronitor: reports · Publishes health and uptime signals
- AI interface → AI providers: calls · Invokes LLM or model backends
- Supervisor → Bootstrap checks: validates · Performs environment readiness checks
- Supervisor → Bot launch: orchestrates · Starts and manages bot launch flow
- Supervisor → TUI console: shows · Provides local operator console
- Bot launch → Bot entry: starts · Spawns the Python bot process
- TUI console → Supervisor: controls · Human interaction with supervisor runtime
- Landing site → GitHub Pages: deploys to · Static site hosting via Pages
- Landing site → Discord: acquires users · Invite and landing path for Discord users
- Legacy bot → Discord: old runtime · Legacy Discord bot implementation
- AI prototypes → AI providers: experiments with · Prototype scripts for model/provider testing
- AI prototypes → Discord: tests against · Discord interaction experiments