dev-sahad/minnal-bot

1. System shape

- This repo is a Discord bot monorepo with a Python runtime at the center, plus a small web control plane and a set of TypeScript packages/artifacts that support APIs, generated clients, and UI tooling.

- The main runtime is the Discord bot; the web and TS pieces are adjacent subsystems rather than the primary execution path.

2. Bot entrypoint and runtime boundary

- discord_bot.py is the primary startup file for the bot.

- config.py, config_manager.py, and logger.py provide configuration, persistence helpers, and logging around the bot process.

- start.py and webhook_server.py appear to be supporting launch/hosting entrypoints or auxiliary servers.

3. Feature decomposition via cogs

- The bot is organized into cogs/*.py, with each file owning a domain:

- administration and moderation: admin.py, bot_control.py, checks.py, sentinel.py, watchlist.py

- community automation: welcome.py, autorole.py, verify.py, tickets.py, giveaways.py, ghostping.py

- engagement systems: economy.py, levels.py, stats.py, fun.py, memes.py, rizz_engine.py, anime.py

- utility/info: utilities.py, info.py, help.py, dashboard.py

- media/voice: music.py, voice_features.py, voice_manager.py

- integrations: web_bridge.py, ai_chat.py, codepilot.py, omni_status.py

- This is the main functional boundary: each cog encapsulates a command or event-driven subsystem.

4. Data and state persistence

- Runtime state is file-backed in data/*.json, including economy.json, reaction_roles.json, birthdays.json, web_config.json, bot_stats.json, and settings.json.

- The design is lightweight and local-first: the bot persists operational state to JSON rather than a separate database service in the main Python path.

- This means architecture diagrams should show a bot process reading/writing local files, not a remote datastore, for core features.

5. Assets and media

- audio/ contains local media assets used by the bot, likely for music/voice or sound-trigger features.

- assets/ is a general static asset bucket.

- These are part of the bot’s runtime environment and should be shown as local dependencies, not external services.

6. Web bridge and remote control path

- The repo includes a dedicated bot-to-web control bridge: cogs/web_bridge.py, webhook_server.py, and documentation like WEB_BRIDGE_GUIDE.md.

- The README indicates a token/link flow between Discord and a web panel: a Discord command produces a server token, which is then used by the browser panel to connect to the bot.

- Architecturally, this is a separate control channel from Discord chat commands: browser UI -> bridge/auth token -> bot state/actions.

7. Static admin panels

- admin-panel.html, advanced-admin-panel.html, config-editor.html, and related HTML docs are standalone web UIs.

- These are meant to be deployed separately as static pages and used to manage bot settings, connection state, and administrative actions.

- They are not the bot itself; they are the operator-facing front end for the web bridge.

8. TypeScript API server artifact

- artifacts/api-server/ is a small TypeScript server with src/app.ts, src/index.ts, and routes like health.ts and railway.ts.

- It looks like a lightweight service boundary for deployment/health checks and platform integration, with built output under dist/.

- In a diagram, treat it as a companion HTTP service rather than the bot’s core logic.

9. Shared API contracts and generated clients

- lib/api-spec/openapi.yaml is the contract source for API generation.

- lib/api-client-react and lib/api-zod contain generated clients/schemas, suggesting a contract-first workflow for browser-side/API integration and runtime validation.

- These packages are the shared boundary between the TypeScript UI/server world and any API surface exposed by the bot ecosystem.

10. Database/schema package

- lib/db contains a shared schema package built with Drizzle tooling (drizzle.config.ts, src/schema).

- Even if the main bot uses JSON files, this package indicates a separate schema layer for structured data and likely supports the TS side of the repo.

- For architecture, treat it as a shared data model package used by the API/UI tooling.

11. Frontend tooling and sandboxes

- artifacts/bot-logs and artifacts/mockup-sandbox are Vite-based React apps with many shared UI components.

- mockup-sandbox includes a custom preview plugin and generated mockup component definitions, which suggests a design/prototyping environment.

- bot-logs likely provides a UI for viewing operational logs or bot telemetry.

- These are separate frontend artifacts, not required for bot execution, but important for operator experience.

12. Operational and deployment boundaries

- Dockerfile, Procfile, requirements.txt, package.json, pnpm-workspace.yaml, and tsconfig* show a repo that supports both Python and Node-based builds.

- The README also emphasizes Replit/PythonAnywhere/Railway-style deployment, so the architecture is designed for hosted bot execution plus optional web hosting.

- tests/ is minimal, so the main reliability boundary is operational rather than deeply unit-tested code.

13. External dependencies and integration points

- The bot’s main external system is Discord: slash commands, guild events, voice, moderation, and admin workflows all run through the Discord API.

- Secondary external surfaces are a static web host for admin panels and any webhook/HTTP endpoints used for bridging or health checks.

- The repo’s architecture is therefore a Discord-centric event system with a sidecar web admin channel and supporting generated API/tooling packages.