🗺️ Roadmap(modernization): Master-Bot Unified Architecture, Lavalink v4 Audio Engine, Dual DB/Redis Fallbacks & Agent Ecosystem

[PhantomNimbi]

🗺️ Roadmap(modernization): Master-Bot Unified Architecture, Lavalink v4 Audio Engine, Dual DB/Redis Fallbacks & Agent Ecosystem

Note

• Primary Open Pull Request: All changes tracked in this issue are consolidated in Pull Request #829.
• Repository Fork: Developed and maintained at PhantomNimbi/Master-Bot.
• Lifecycle Policy: This master tracking issue details all architectural, infrastructural, and feature differences between upstream galnir/Master-Bot and the PhantomNimbi/Master-Bot modernization fork.

---

📖 Summary

This issue serves as the master architectural blueprint and tracking roadmap for modernizing Master-Bot. The project unifies the Discord bot gateway and the Next.js 15 web dashboard into a single, high-performance Node.js service, embeds the Lavalink v4 audio server via @helix-origin/lavalink-server, incorporates a universal testing suite via @helix-origin/vitest-suite, introduces dual external PostgreSQL/Redis support with zero-ops SQLite/ioredis-mock fallbacks, transitions hosting recommendations from unreliable PaaS cloud platforms to high-performance low-cost VPS providers (with Heroku as an optional cloud alternative), and deploys an extensive multi-agent ecosystem (.agents/).

---

🎯 Motivation & Context

Upstream galnir/Master-Bot faced critical operational hurdles:

1. Broken Audio Engine: Lavalink v3 experienced YouTube IP rate limits, broken scraping, and lacked plugin extensibility.
2. Operational Complexity: Required separate PostgreSQL and Redis server daemons to run even a single local development instance.
3. Multi-Process Friction: Separate Node.js processes for bot gateway (3000) and dashboard (3001) caused port collisions and deployment issues.
4. Cloud PaaS Limitations: Deploying to ephemeral PaaS containers (Render, Railway, Fly.io) resulted in lost SQLite data upon sleep/restart, high costs for 2GB+ RAM required by Java Lavalink, and blocked subdomains in OAuth flows.
5. Testing & Tooling Gaps: Incomplete test coverage and loose linting configurations led to hidden regressions.

This modernization fork resolves these challenges by making the stack zero-ops out of the box while establishing clear production paths on low-cost unmetered Linux VPS instances.

---

📐 Structural Guidance (Mermaid Diagrams)

1. Unified Service Architecture

flowchart TD
    subgraph ClientLayer [Clients & Endpoints]
        DiscordAPI[Discord Gateway API]
        WebUsers[Browser Users / Dashboard]
        VoiceGateway[Discord Voice WebSockets]
    end

    subgraph MasterBotService [Master-Bot Unified Service :3000]
        Router[Internal HTTP / SSR Web Server]
        BotClient[Sapphire Discord Client]
        DashboardApp[Next.js 15 App Router & tRPC v11]
        EmbeddedLavalink[Embedded Lavalink Server / Supervisor]
        SessionMgr[In-Memory SessionManager]
    end

    subgraph StorageLayer [Dual Storage & Fallback Architecture]
        subgraph DBEngine [Database Layer]
            direction TB
            PG[(External PostgreSQL)]
            SQLite[(Local SQLite: db.sqlite)]
            DBEngineSelect{DATABASE_URL starts with postgres?}
            DBEngineSelect -->|Yes| PG
            DBEngineSelect -->|No / Default| SQLite
        end

        subgraph CacheEngine [Cache Layer]
            direction TB
            ExtRedis[(External Redis Server)]
            MockRedis[In-Memory ioredis-mock]
            CacheSelect{REDIS_URL or REDIS_HOST set?}
            CacheSelect -->|Yes| ExtRedis
            CacheSelect -->|No / Fallback| MockRedis
        end
    end

    DiscordAPI <--> BotClient
    WebUsers <--> Router
    Router <--> DashboardApp
    DashboardApp <--> BotClient
    BotClient <--> SessionMgr
    SessionMgr <--> StorageLayer
    BotClient <--> EmbeddedLavalink
    VoiceGateway <--> EmbeddedLavalink

Loading

2. Embedded Lavalink Audio Pipeline

sequenceDiagram
    autonumber
    actor User as Discord User
    participant Bot as Master-Bot (Sapphire Client)
    participant Lava as Embedded Lavalink Server (@helix-origin/lavalink-server)
    participant YT as YouTube API / Remote Cipher
    participant DiscVoice as Discord Voice Channel

    User->>Bot: /play query: "lo-fi beats"
    Bot->>Lava: REST search / loadtracks
    Lava->>YT: Resolve track metadata & stream signatures
    YT-->>Lava: Audio track streams
    Lava-->>Bot: Track load response
    Bot->>DiscVoice: Join voice channel
    Bot->>Lava: WebSocket voice update (session ID & token)
    Lava->>DiscVoice: Stream real-time Opus audio packets
    Bot-->>User: Now Playing rich embed with interactive buttons

Loading

3. Database & Cache Seamless Fallback State Machine

stateDiagram-v2
    [*] --> InspectEnv: Service Startup
    InspectEnv --> PostgreSQL: DATABASE_URL = postgresql://...
    InspectEnv --> SQLiteFallback: Default / file:./db.sqlite
    PostgreSQL --> ConnectPostgres
    ConnectPostgres --> PostgresActive: Success
    ConnectPostgres --> SQLiteFallback: Connection Refused / Fallback
    
    InspectEnv --> ExternalRedis: REDIS_URL or REDIS_HOST configured
    InspectEnv --> MockRedisFallback: Default / In-Memory
    ExternalRedis --> ConnectRedis
    ConnectRedis --> RedisActive: Success
    ConnectRedis --> MockRedisFallback: Timeout / Error

Loading

---

📊 High-Level Comparison Matrix

Component / Dimension	Upstream (galnir/Master-Bot)	Modernization Fork (PhantomNimbi/Master-Bot)
Runtime Architecture	Multi-process: Bot (3000) & Dashboard (3001) run separately	Single Node.js Process: Bot gateway & Dashboard unified on single PORT (3000)
Database Layer	External PostgreSQL server only (postgresql://...)	Dual Support with Fallback: External PostgreSQL + embedded packages/db/prisma/db.sqlite
Cache / State Store	Standalone Redis server process only (redis://...)	Dual Support with Fallback: External Redis + internal in-memory ioredis-mock
Audio Engine	Lavalink v3 (deprecated, broken YouTube scraping)	Lavalink v4: Embedded server via @helix-origin/lavalink-server
Testing Suite	Minimal test setup	Universal Testing Suite: @helix-origin/vitest-suite with Discord & storage mocks
Web Dashboard	Next.js 13/14 Pages Router	Next.js 15 (App Router): React 18, tRPC v11, NextAuth v5 beta, 9 Studios
Hosting & Deployment	No clear low-cost deployment guide	Low-Cost VPS First: Hetzner (€3.79/mo), OVH ($4.20/mo), DigitalOcean, Linode, Vultr, Contabo (optional Heroku)
Keep-Alive & Uptime	None (sleeps on free tiers after 15 mins)	Built-in Keep-Alive pinger (/health auto-pinged every 10 mins)
Command Suite	Legacy slash commands	74 Slash Commands: Music, Moderation, Tickets, Reminders, Games, GIFs
Agent Ecosystem	None	Extensive .agents/ ecosystem: 8 agents, 8 skills (gh CLI, issue, wiki), 5 rules, 5 templates
Documentation	Minimal README and docs	16-Page Comprehensive Wiki + GitHub-formatted Mermaid diagrams

---

🚀 Complete Modernization Breakdown

1. 🏗️ Consolidated Single-Process Architecture

• Unified Port & Process: Discord Bot Gateway (Sapphire framework) and Next.js 15 Web Dashboard (/dashboard) co-exist in a single Node.js process listening on PORT (default 3000).
• Internal Web Server (apps/bot/src/lib/server/webServer.ts):
  • Serves landing root (/) and handles dashboard SSR routing.
  • Exposes /health endpoint for container health probes and uptime monitors.
  • Background keepAlive service auto-pings /health every 10 minutes to prevent ephemeral cloud spin-downs.
• Unified Scripts: pnpm dev and pnpm start operate out of the box across all operating systems.

2. 🗄️ Dual Database Architecture (PostgreSQL with SQLite Fallback)

• Zero-Ops Default: Runs SQLite (packages/db/prisma/db.sqlite) automatically without database installation.
• Dynamic Schema Preparation (packages/db/scripts/prepare-schema.mjs): Inspects DATABASE_URL at build/push time. When pointed at PostgreSQL, dynamically generates PostgreSQL schema with @db.Text annotations; otherwise configures SQLite.
• Shared ORM Instance: Bot and Dashboard share @master-bot/db client for zero-latency cross-talk.

3. ⚡ Dual Cache Architecture (External Redis with ioredis-mock Fallback)

• Configurable External Redis: Reads REDIS_URL or REDIS_HOST & REDIS_PORT.
• Automatic In-Memory Fallback: When Redis is omitted or unreachable, seamlessly activates in-memory ioredis-mock with graceful warning logs instead of crashing the process.

4. 🎵 Embedded Lavalink v4 Audio Engine (@helix-origin/lavalink-server)

• Embedded Audio Server: Imports @helix-origin/lavalink-server directly into apps/bot.
• Turnkey Supervisor: Manages Lavalink v4 Java process in-memory or acts as high-throughput proxy gateway.
• Remote Audio Node Toggle: LAVA_EXTERNAL=true toggle allows instant connection to external remote audio nodes when deploying on constrained container memory limits.

5. 🌐 Low-Cost VPS Hosting Strategy (Replacing Ephemeral PaaS)

• Why VPS is Preferred: Eliminates ephemeral filesystem resets that destroy SQLite databases, avoids high RAM pricing on PaaS for Lavalink audio, and prevents OAuth domain blocking.
• Recommended Providers: Hetzner Cloud (CX22 €3.79/mo), OVHcloud Starter ($4.20/mo), DigitalOcean ($4-$6/mo), Linode ($5/mo), Vultr ($3.50-$5/mo), and Contabo (VPS S ~€5.50/mo for 8GB RAM).
• Heroku Cloud Alternative: Documented as an optional choice for users requiring managed PaaS, configured with Heroku Postgres and external Lavalink.

6. 🧪 Universal Modular Vitest Testing Suite (@helix-origin/vitest-suite)

• Monorepo-aware Vitest configuration via defineMonorepoConfig.
• Discord.js v14 mocks (createMockClient, createMockInteraction, createMockGuild), HTTP server harnesses, and Redis test doubles.

7. 🤖 Autonomous Agent Ecosystem (.agents/ & AGENTS.md)

• 8 Specialized Agents: architect, database-engineer, audio-engineer, test-engineer, github-specialist, dashboard-specialist, bot-specialist, release-engineer.
• 8 Dedicated Skills:
  • gh-cli-expert: Comprehensive GitHub CLI automation (issues, PRs, runs, releases, tarballs).
  • issue-orchestrator: Human-readable issue creation with emojis, Mermaid diagrams, and sub-issues.
  • wiki-management: Proper GitHub wiki links, sidebar, and footer pages.
  • database-fallback: PostgreSQL/SQLite and Redis/ioredis-mock management.
  • embedded-lavalink: Audio node supervision and proxy routing.
  • vitest-suite-expert: Test authoring and quality gating.
  • monorepo-orchestrator: Turbo and pnpm pipeline execution.
  • release-orchestrator: Release tagging and packaging.
• Standardized Rules & Templates: Commit message standards with emojis, issue templates, and test specifications.

---

🧩 Sub-Issues & Tasks (Discrete Milestone Tracking)

• 🧩 Sub-Task 1: Resolve monorepo-wide typos (INTERNAL_URL) and clean environment schemas
• 🧩 Sub-Task 2: Modernize TypeScript configs (apps/bot, @master-bot/db) and establish pre-compiled declarations
• 🧩 Sub-Task 3: Implement dual external PostgreSQL support with zero-ops SQLite fallback in @master-bot/db
• 🧩 Sub-Task 4: Implement dual external Redis support with internal ioredis-mock fallback in @master-bot/db
• 🧩 Sub-Task 5: Import and embed Lavalink v4 server via @helix-origin/lavalink-server with external node toggle
• 🧩 Sub-Task 6: Import @helix-origin/vitest-suite testing toolkit and configure workspace test runners
• 🧩 Sub-Task 7: Replace cloud hosting instructions with recommended low-cost VPS providers and optional Heroku guide
• 🧩 Sub-Task 8: Construct .agents/ ecosystem (Agents, Skills, Rules, Templates) with GitHub CLI & Issue Standards
• 🧩 Sub-Task 9: Author complete 16-page documentation wiki with Mermaid diagrams, sidebar, and footer
• 🧩 Sub-Task 10: Validate monorepo with pnpm lint, pnpm type-check, and pnpm test (0 errors)

---

🔍 Acceptance Criteria & Quality Gates

• Type Safety: pnpm type-check succeeds with 0 TypeScript compilation errors across all workspace packages.
• Linting & Code Quality: pnpm lint passes with 0 errors via ESLint and manypkg.
• Unit Testing: pnpm test executes with 100% pass rate using @helix-origin/vitest-suite.
• Zero-Ops Default: Repository boots from scratch with pnpm install && pnpm start with zero external dependencies.
• Production Scaling: Connecting PostgreSQL and Redis via environment variables works without code modifications.
• VPS Ready: Clear guides provided for Docker Compose and Node.js + PM2 on low-cost VPS hosts (Hetzner, OVH, DigitalOcean, Linode, Vultr, Contabo), with Heroku as an optional cloud alternative.

---

🛠️ Verification Matrix

✓ pnpm lint           — 0 errors across 6 workspaces (FULL TURBO)
✓ pnpm type-check     — 0 errors across all packages (@master-bot/auth, @master-bot/bot, @master-bot/dashboard, @master-bot/db)
✓ pnpm test           — 100% test pass rate using @helix-origin/vitest-suite presets
✓ Database Pre-check  — Prepared Prisma schema for SQLite / PostgreSQL dynamically
✓ Deployment Docs     — VPS guides (Docker/PM2) + low-cost host comparisons + optional Heroku guide

---

This master tracking issue remains OPEN until Pull Request #829 is accepted and merged into main.

[PhantomNimbi]

📢 Progress Update: Today's Changes & Enhancements

Here is a comprehensive overview of the updates, bug fixes, and ecosystem enhancements completed today:

---

1. 🧹 Environment Variable Normalization & Typo Resolution

• Resolved Typo Monorepo-Wide: Fixed INTERNA_URL to INTERNAL_URL across all runtime schemas, .env.example, .env, turbo.json, and wiki documentation.
• Dead Variable Pruning: Fully removed legacy PostgreSQL and Redis variables (POSTGRES_*, REDIS_*, duplicate auth vars) to keep configuration strictly focused on the active stack.

---

2. 🛠️ TypeScript, Tooling & Compilation Hardening

• Tsconfig Modernization:
  • Pruned invalid "ignoreDeprecations": "5.0" and "6.0" flags from root and package tsconfigs.
  • Made apps/bot/tsconfig.json self-contained (CommonJS + Node resolution), eliminating '@sapphire/ts-config' not found errors.
  • Resolved HMR type casting in apps/bot/src/lib/structures/ExtendedClient.ts.
• Pre-Compiled Declarations for @master-bot/db:
  • Configured packages/db/tsconfig.json to emit compiled index.js and index.d.ts declaration files via tsc.
  • Updated packages/db/package.json to point "main": "./index.js" and "types": "./index.d.ts", allowing workspace packages to cleanly consume type definitions without compiling raw .ts files on the fly.

---

3. ☁️ Deployment Defaults & Memory Protection

• LAVA_EXTERNAL=true on Cloud Blueprints:
  • Set LAVA_EXTERNAL=true and LAVA_ENABLED=false as the default in all cloud deployment manifests to protect bot containers from JVM Out-Of-Memory (OOM) crashes.

---

4. 🎵 Dedicated Standalone Lavalink v4 Server (HELIX-Origin/Lavalink-Server)

• Published Standalone Repo: Created and published HELIX-Origin/Lavalink-Server under the HELIX Origin GitHub organization.
• Dynamic Official Release Ingestion: The Dockerfile (eclipse-temurin:21-jre-alpine) automatically downloads the latest official Lavalink v4 release JAR from GitHub releases at build time.
• Dynamic Port & Pass Mapping: Dynamically binds server.port to ${PORT:${LAVA_PORT:2333}} and server.password to ${LAVA_PASS:youshallnotpass}, fully supporting Render, Railway, and Heroku port injection.
• 1-Click Deployment: Provided blueprints for Render (render.yaml), Railway (railway.json), Heroku (app.json, heroku.yml), and Fly.io (fly.toml).
• Comprehensive 7-Page Wiki: Complete documentation in wiki/ covering installation, configuration, cloud deployment, and client integration.

---

5. 🔗 Master-Bot Integration & Ecosystem Linking

• Added 1-click deployment buttons for the standalone Lavalink server directly into Master-Bot's README.md, wiki/Deployment.md, wiki/Music.md, wiki/Configuration.md, wiki/Getting-Started.md, and wiki/FAQ.md.
• Explicitly documented that LAVA_EXTERNAL is a client-side Discord bot flag, and clearly attributed repository ownership to HELIX Origin.

---

6. 🧪 Universal Modular Vitest Testing Suite (HELIX-Origin/vitest-suite)

• Created and published HELIX-Origin/vitest-suite under HELIX Origin as a shared testing toolkit for Node.js projects.
• Modular Presets: Preconfigured Vitest environments for base Node, Discord.js bots, HTTP servers, databases (SQLite/Prisma), and monorepos.
• Mocks & Test Doubles: Comprehensive mocks for Discord.js v14 (Client, Interaction, Guild, Channel, User), ephemeral port 0 servers, and in-memory mock Redis / models.
• Custom Matchers & Examples: Domain matchers (toBeDiscordSnowflake, toBeValidEmbed, toHaveHttpHeader) and a 6-page wiki guide.

---

7. 📊 Verification & Readiness

• Unit Tests: 15/15 unit tests passing cleanly.
• Type Checking: 3/3 packages clean with zero TypeScript errors.
• Git State: All repositories are committed, pushed, and up-to-date.
• Pull Request Status: PR #829 is fully prepared for review.

[PhantomNimbi]

📢 Modernization Milestone Update: Dual Database/Redis Fallbacks, Embedded Lavalink & Agent Ecosystem

Hello everyone! 👋 Here is an in-depth progress update on the architectural enhancements, test suite upgrades, and agent ecosystem integration completed across the repository:

---

1. 🗄️ Dual Database Architecture (PostgreSQL with SQLite Fallback)

• Implemented packages/db/scripts/prepare-schema.mjs:
  • Dynamically inspects DATABASE_URL upon pnpm db:generate or pnpm db:push.
  • When pointed to an external PostgreSQL connection (postgresql://...), dynamically generates PostgreSQL provider schema with @db.Text annotations.
  • When omitted or using file:./db.sqlite, configures local zero-ops SQLite fallback.
• Exported getDatabaseProvider() in @master-bot/db for runtime reflection.

---

2. ⚡ Dual Redis Architecture (External Redis with ioredis-mock Fallback)

• Enhanced packages/db/index.ts:
  • Dynamically attempts connection to REDIS_URL or REDIS_HOST if specified.
  • Features configurable connection timeouts and automatic error listeners.
  • If Redis is unavailable or unconfigured, it seamlessly activates in-memory ioredis-mock without crashing the application.
• Exported isUsingMockRedis() to expose live cache status on console and telemetry dashboards.

---

3. 🎵 Embedded Audio Server Integration (@helix-origin/lavalink-server)

• Added @helix-origin/lavalink-server v1.1.0 dependency to apps/bot.
• Implemented apps/bot/src/lib/lavalink/embeddedLavalink.ts:
  • Boots in-process Lavalink v4 audio gateway and supervisor alongside the bot unless LAVA_EXTERNAL=true.
  • Connected to graceful shutdown handlers (SIGINT, SIGTERM).
  • Allows zero external container overhead on local setups while preserving remote node compatibility for cloud containers.

---

4. 🧪 Universal Modular Testing Suite (@helix-origin/vitest-suite)

• Installed @helix-origin/vitest-suite v0.2.3 into root devDependencies.
• Configured vitest.config.ts using defineMonorepoConfig.
• Provided specialized mocks (createMockRedis, createMockClient, createMockPrisma) and matchers for testing across workspaces.

---

5. 🤖 Autonomous Agent Ecosystem (.agents/ & AGENTS.md)

• Established complete agent operating architecture:
  • 8 Specialized Agents (architect, database-engineer, audio-engineer, test-engineer, github-specialist, dashboard-specialist, bot-specialist, release-engineer).
  • 8 Production Skills (gh-cli-expert, issue-orchestrator, wiki-management, database-fallback, embedded-lavalink, vitest-suite-expert, monorepo-orchestrator, release-orchestrator).
  • Standardized Rules & Templates: Commit conventions with emojis, issue templates with Mermaid diagrams, sub-issue management, and test specifications.

---

📐 Architectural Lifecycle Flowchart

flowchart TD
    Start[pnpm start] --> PrepSchema[node prepare-schema.mjs]
    PrepSchema --> CheckDB{DATABASE_URL starts with postgres?}
    CheckDB -->|Yes| SetPG[Prisma: postgresql + @db.Text]
    CheckDB -->|No| SetSQLite[Prisma: sqlite + db.sqlite]
    
    SetPG --> StartService[Start Unified Master-Bot Service :3000]
    SetSQLite --> StartService

    StartService --> CheckRedis{REDIS_URL or REDIS_HOST set?}
    CheckRedis -->|Yes| TryRedis[Connect External Redis]
    TryRedis -->|Failure / Timeout| FallbackMock[Fallback to ioredis-mock]
    TryRedis -->|Success| ActiveRedis[External Redis Active]
    CheckRedis -->|No| FallbackMock

    StartService --> CheckLava{LAVA_EXTERNAL = true?}
    CheckLava -->|No / Unset| StartEmbedded[Embed @helix-origin/lavalink-server]
    CheckLava -->|Yes| ConnectRemote[Connect to Remote Lavalink Node]
    
    StartEmbedded --> Ready[System Online & Healthy]
    ConnectRemote --> Ready

Loading

---

🛠️ Quality Gates Verification

✓ pnpm lint           — 0 errors across all 6 workspaces (FULL TURBO)
✓ pnpm type-check     — 0 errors across @master-bot/auth, @master-bot/bot, @master-bot/dashboard, @master-bot/db
✓ pnpm test           — 100% test pass rate with @helix-origin/vitest-suite presets

[PhantomNimbi]

🌐 Infrastructure Update: Transitioning to Low-Cost VPS Hosting (with Optional Heroku Support)

Hello everyone! 👋 Based on practical reliability, persistence, and performance requirements, we have updated the official deployment documentation and roadmap:

---

1. 🛑 Why Cloud PaaS (Render, Railway, Fly.io) is Not Ideal

• Ephemeral Storage: Cloud PaaS containers destroy their local filesystem upon restarts, deploys, or dyno sleep cycles, which breaks SQLite persistence (packages/db/prisma/db.sqlite).
• Resource Limits & Cost: Java Lavalink v4 + Next.js App Router + Discord gateway bot require 1.5–2 GB RAM. Cloud platforms charge high monthly fees for this footprint, whereas a low-cost unmetered Linux VPS provides 4–8 GB RAM for ~$4–$5/month.
• Domain & OAuth Reputation: Default cloud subdomains (*.onrender.com, *.herokuapp.com) frequently encounter automated browser safe-browsing blocks, breaking Discord OAuth logins.

---

2. 🚀 Recommended Low-Cost VPS Providers & Hosts

We have curated a production-grade comparison of budget-friendly, unmetered VPS providers:

Provider	Starting Price	Specs / Recommended Plan	Key Advantages
Hetzner Cloud	~€3.79 / mo	CX22 (2 vCPU, 4 GB RAM, 40 GB NVMe)	Top value: High NVMe speeds, 20 TB traffic, EU/US
OVHcloud	~$4.20 / mo	Starter VPS (1 vCPU, 2 GB RAM, 20 GB SSD)	Unmetered bandwidth, enterprise anti-DDoS protection
DigitalOcean	~$4.00 - $6.00 / mo	Basic Droplet (1 vCPU, 1-2 GB RAM, 25 GB NVMe)	1-Click Docker droplets, low network latency
Linode (Akamai)	~$5.00 / mo	Nanode 1GB / Shared 2GB (1-2 vCPU, 1-2 GB RAM)	High network reliability, 24/7 technical support
Vultr	~$3.50 - $5.00 / mo	Cloud Compute (1 vCPU, 1-2 GB RAM, 25-32 GB NVMe)	32+ worldwide datacenters, fast provisioning
Contabo	~$5.50 / mo	Cloud VPS S (4 vCPU, 8 GB RAM, 50 GB NVMe)	Maximum RAM per dollar; hosts bot + dashboard + audio all-in-one

---

3. ☁️ Optional Cloud Alternative: Heroku

For developers who specifically prefer managed cloud hosting:

• Documented full Heroku configuration using the Node.js buildpack.
• Added explicit requirements for Heroku Postgres (DATABASE_URL=postgresql://...) to prevent data loss on dyno restart.
• Added instructions for connecting to an external Lavalink audio host (LAVA_EXTERNAL=true) to keep dyno memory within limits.
• Configured built-in keep-alive pinger (KEEP_ALIVE_ENABLED=true) to keep the /health endpoint warm.

---

📐 Updated Deployment Architecture

flowchart TD
    subgraph SelfHostedVPS ["Recommended: Low-Cost Linux VPS (Hetzner / OVH / DigitalOcean)"]
        DockerCompose["docker compose up -d --build"]
        DockerCompose --> BotService["Master-Bot Single Process (:3000)"]
        DockerCompose --> LavaContainer["Lavalink v4 Container (:2333)"]
        BotService --> SQLiteVol[("Persistent Volume: sqlite-data (db.sqlite)")]
    end

    subgraph OptionalHeroku ["Optional: Managed Cloud (Heroku)"]
        HerokuDyno["Heroku Web Dyno (PORT)"]
        HerokuDyno --> ExtPG[("Heroku Postgres Add-on (DATABASE_URL)")]
        HerokuDyno --> RemoteLava["External Remote Lavalink Node (LAVA_HOST)"]
    end

Loading

[PhantomNimbi]

Ok. after going through all this work and having it working almost perfectly on my machine I decided to test it on my VPS only to discover I had wasted my time and money on AI credits attempting to fix the problems in this repo. At this point I think I'm going to give up. The turbo rebuild is causing too many problems that need to be patched around instead of properly fixed and that just doesn't sit right with me. I'm closing this issue since none of my fixes are going to work with the turbo rewrite. At this point, it's safe to say I don't like turbo very much.