# mistromy/nirupama architecture

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

- Interactive diagram: https://gitdiagram.com/mistromy/nirupama
- Repository: https://github.com/mistromy/nirupama

## Overview

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: [`pybot/main.py`](https://github.com/mistromy/nirupama/blob/main/pybot/main.py) (Bot entry), [`go/cmd/supervisor/main.go`](https://github.com/mistromy/nirupama/blob/main/go/cmd/supervisor/main.go) (Supervisor), [`pybot/cogs/ai_core.py`](https://github.com/mistromy/nirupama/blob/main/pybot/cogs/ai_core.py) (AI core), [`website/index.html`](https://github.com/mistromy/nirupama/blob/main/website/index.html) (Landing site)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_g_python["Python bot"]
  node_py_entry["Bot entry<br/>python entrypoint<br/>[main.py]"]
  node_py_launch["Launch flow<br/>python launcher<br/>[launch.py]"]
  node_cogs_commands["Commands<br/>discord cog<br/>[commands.py]"]
  node_cogs_admin["Admin<br/>discord cog<br/>[admin.py]"]
  node_cogs_ai["AI core<br/>discord cog<br/>[ai_core.py]"]
  node_cogs_tracking["Tracking<br/>discord cog<br/>[tracking.py]"]
  node_cogs_uptime["Uptime<br/>discord cog<br/>[uptime.py]"]
  node_cogs_voice["Voice<br/>discord cog<br/>[vc.py]"]
  node_cogs_privacy["Privacy<br/>discord cog<br/>[privacypolicy.py]"]
  node_utils_ai["AI interface<br/>python util<br/>[ai_interface.py]"]
  node_utils_ship["Ship feature<br/>python util<br/>[ship.py]"]
  node_utils_levels["Levels<br/>python util<br/>[levels.py]"]
  node_data_ai["AI data<br/>python data<br/>[ai_data.py]"]
end

subgraph group_g_go["Go control plane"]
  node_go_supervisor["Supervisor<br/>go command<br/>[main.go]"]
  node_go_checks["Bootstrap checks<br/>go bootstrap<br/>[checks.go]"]
  node_go_launch["Bot launch<br/>go launcher<br/>[launch.go]"]
  node_go_tui["TUI console<br/>go tui<br/>[tui.go]"]
end

subgraph group_g_web["Website"]
  node_web_site["Landing site<br/>static site<br/>[index.html]"]
end

subgraph group_g_extras["Archive & prototypes"]
  node_archive_bot["Legacy bot<br/>archive runtime<br/>[bot.py]"]
  node_proto_tests["AI prototypes<br/>experiments<br/>[chatgpt.py]"]
end

subgraph group_g_ext["External services"]
  node_discord_api(("Discord<br/>external platform"))
  node_supabase[("Supabase<br/>external database")]
  node_ai_providers(("AI providers<br/>external api"))
  node_cronitor(("Cronitor<br/>external monitoring"))
  node_github_pages(("GitHub Pages<br/>external hosting"))
end

node_py_entry -->|"connects to"| node_discord_api
node_py_launch -->|"starts"| node_py_entry
node_py_entry -->|"loads"| node_cogs_commands
node_py_entry -->|"loads"| node_cogs_admin
node_py_entry -->|"loads"| node_cogs_ai
node_py_entry -->|"loads"| node_cogs_tracking
node_py_entry -->|"loads"| node_cogs_uptime
node_py_entry -->|"loads"| node_cogs_voice
node_py_entry -->|"loads"| node_cogs_privacy
node_cogs_commands -->|"uses"| node_utils_levels
node_cogs_ai -->|"uses"| node_utils_ai
node_cogs_ai -->|"reads"| node_data_ai
node_cogs_tracking -->|"stores"| node_supabase
node_utils_levels -->|"stores"| node_supabase
node_cogs_uptime -->|"reports"| node_cronitor
node_utils_ai -->|"calls"| node_ai_providers
node_go_supervisor -->|"validates"| node_go_checks
node_go_supervisor -->|"orchestrates"| node_go_launch
node_go_supervisor -->|"shows"| node_go_tui
node_go_launch -->|"starts"| node_py_entry
node_go_tui -->|"controls"| node_go_supervisor
node_web_site -->|"deploys to"| node_github_pages
node_web_site -.->|"acquires users"| node_discord_api
node_archive_bot -.->|"old runtime"| node_discord_api
node_proto_tests -.->|"experiments with"| node_ai_providers
node_proto_tests -.->|"tests against"| node_discord_api

click node_py_entry "https://github.com/mistromy/nirupama/blob/main/pybot/main.py"
click node_py_launch "https://github.com/mistromy/nirupama/blob/main/pybot/launch.py"
click node_cogs_commands "https://github.com/mistromy/nirupama/blob/main/pybot/cogs/commands.py"
click node_cogs_admin "https://github.com/mistromy/nirupama/blob/main/pybot/cogs/admin.py"
click node_cogs_ai "https://github.com/mistromy/nirupama/blob/main/pybot/cogs/ai_core.py"
click node_cogs_tracking "https://github.com/mistromy/nirupama/blob/main/pybot/cogs/tracking.py"
click node_cogs_uptime "https://github.com/mistromy/nirupama/blob/main/pybot/cogs/uptime.py"
click node_cogs_voice "https://github.com/mistromy/nirupama/blob/main/pybot/cogs/vc.py"
click node_cogs_privacy "https://github.com/mistromy/nirupama/blob/main/pybot/cogs/privacypolicy.py"
click node_utils_ai "https://github.com/mistromy/nirupama/blob/main/pybot/utils/ai_interface.py"
click node_utils_ship "https://github.com/mistromy/nirupama/blob/main/pybot/utils/ship.py"
click node_utils_levels "https://github.com/mistromy/nirupama/blob/main/pybot/utils/levels.py"
click node_data_ai "https://github.com/mistromy/nirupama/blob/main/pybot/data/ai_data.py"
click node_go_supervisor "https://github.com/mistromy/nirupama/blob/main/go/cmd/supervisor/main.go"
click node_go_checks "https://github.com/mistromy/nirupama/blob/main/go/internal/bootstrap/checks.go"
click node_go_launch "https://github.com/mistromy/nirupama/blob/main/go/internal/bot/launch.go"
click node_go_tui "https://github.com/mistromy/nirupama/blob/main/go/internal/tui/tui.go"
click node_web_site "https://github.com/mistromy/nirupama/blob/main/website/index.html"
click node_archive_bot "https://github.com/mistromy/nirupama/blob/main/archive/bot.py"
click node_proto_tests "https://github.com/mistromy/nirupama/blob/main/TestsPrototypesAndIdeas/chatgpt.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_py_entry,node_py_launch,node_cogs_commands,node_cogs_admin,node_cogs_ai,node_cogs_tracking,node_cogs_uptime,node_cogs_voice,node_cogs_privacy,node_utils_ai,node_utils_ship,node_utils_levels,node_data_ai toneBlue
class node_go_supervisor,node_go_checks,node_go_launch,node_go_tui toneAmber
class node_web_site toneMint
class node_archive_bot,node_proto_tests toneRose
class node_discord_api,node_supabase,node_ai_providers,node_cronitor,node_github_pages toneIndigo
```

## Components

### Python bot

Primary Discord bot runtime and feature modules

- [Bot entry](https://github.com/mistromy/nirupama/blob/main/pybot/main.py): python entrypoint · Main Python bot startup path · `pybot/main.py`
- [Launch flow](https://github.com/mistromy/nirupama/blob/main/pybot/launch.py): python launcher · Alternate Python launch/bootstrap path · `pybot/launch.py`
- [Commands](https://github.com/mistromy/nirupama/blob/main/pybot/cogs/commands.py): discord cog · General bot commands and interaction surface · `pybot/cogs/commands.py`
- [Admin](https://github.com/mistromy/nirupama/blob/main/pybot/cogs/admin.py): discord cog · Server and operator controls · `pybot/cogs/admin.py`
- [AI core](https://github.com/mistromy/nirupama/blob/main/pybot/cogs/ai_core.py): discord cog · Chat and AI-driven bot behavior · `pybot/cogs/ai_core.py`
- [Tracking](https://github.com/mistromy/nirupama/blob/main/pybot/cogs/tracking.py): discord cog · Activity and usage tracking · `pybot/cogs/tracking.py`
- [Uptime](https://github.com/mistromy/nirupama/blob/main/pybot/cogs/uptime.py): discord cog · Availability and heartbeat features · `pybot/cogs/uptime.py`
- [Voice](https://github.com/mistromy/nirupama/blob/main/pybot/cogs/vc.py): discord cog · Voice-channel behavior · `pybot/cogs/vc.py`
- [Privacy](https://github.com/mistromy/nirupama/blob/main/pybot/cogs/privacypolicy.py): discord cog · Privacy policy and related handling · `pybot/cogs/privacypolicy.py`
- [AI interface](https://github.com/mistromy/nirupama/blob/main/pybot/utils/ai_interface.py): python util · Abstraction over AI provider calls · `pybot/utils/ai_interface.py`
- [Ship feature](https://github.com/mistromy/nirupama/blob/main/pybot/utils/ship.py): python util · Relationship scoring and rendering helpers · `pybot/utils/ship.py`
- [Levels](https://github.com/mistromy/nirupama/blob/main/pybot/utils/levels.py): python util · Leveling and progression logic · `pybot/utils/levels.py`
- [AI data](https://github.com/mistromy/nirupama/blob/main/pybot/data/ai_data.py): python data · Bot-specific AI metadata or persisted state · `pybot/data/ai_data.py`

### Go control plane

Supervisor, bootstrap, and local TUI launcher

- [Supervisor](https://github.com/mistromy/nirupama/blob/main/go/cmd/supervisor/main.go): go command · Process supervisor and operator launcher · `go/cmd/supervisor/main.go`
- [Bootstrap checks](https://github.com/mistromy/nirupama/blob/main/go/internal/bootstrap/checks.go): go bootstrap · Environment and readiness validation before launch · `go/internal/bootstrap/checks.go`
- [Bot launch](https://github.com/mistromy/nirupama/blob/main/go/internal/bot/launch.go): go launcher · Prelaunch and launch orchestration for the bot process · `go/internal/bot/launch.go`
- [TUI console](https://github.com/mistromy/nirupama/blob/main/go/internal/tui/tui.go): go tui · Local terminal control and status surface · `go/internal/tui/tui.go`

### Website

Static public landing site

- [Landing site](https://github.com/mistromy/nirupama/blob/main/website/index.html): static site · Public marketing and invite site · `website/index.html`

### Archive & prototypes

Older implementations and experiment paths

- [Legacy bot](https://github.com/mistromy/nirupama/blob/main/archive/bot.py): archive runtime · Older bot implementation path · `archive/bot.py`
- [AI prototypes](https://github.com/mistromy/nirupama/blob/main/TestsPrototypesAndIdeas/chatgpt.py): experiments · Assorted AI and media experiment scripts · `TestsPrototypesAndIdeas/chatgpt.py`

### External services

Third-party APIs and infrastructure used by the repo

- **Discord**: external platform · Chat platform event and command runtime
- **Supabase**: external database · Persistent storage for user levels and activity
- **AI providers**: external api · LLM and model endpoints used by the bot
- **Cronitor**: external monitoring · Uptime and health monitoring service
- **GitHub Pages**: external hosting · Static hosting/deployment for the website

## Connections

- 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
