docs: replace textual database documentation with Mermaid ER diagram

Author: BigMichi1

docs/DEVELOPMENT.md

@@ -0,0 +1,213 @@
+# Development Guide
+
+## Quick Start
+
+**⚠️ IMPORTANT: Always use Mise. Never use npm or bun run directly.**
+
+```bash
+# Install dependencies
+mise run install
+
+# Start development server with auto-rebuild
+mise run dev
+
+# View all available tasks
+mise tasks
+```
+
+### If You Don't Have Mise Installed
+
+```bash
+# Install Mise (macOS/Linux)
+curl https://mise.jdx.dev/install.sh | sh
+
+# Or with Homebrew
+brew install mise
+
+# Then follow "Quick Start" above
+```
+
+## Project Structure
+
+```
+src/bot/
+├── bot.ts                      # Main Discord client & events
+├── api/
+│   └── idleChampionsApi.ts     # Game API client (query-param based)
+├── commands/
+│   ├── setup.ts                # Save user credentials
+│   ├── redeem.ts               # Manual code redemption
+│   ├── inventory.ts            # Show account info
+│   ├── open.ts                 # Open chests
+│   ├── blacksmith.ts           # Upgrade heroes
+│   ├── codes.ts                # Show code history
+│   ├── makepublic.ts           # Share codes with other users
+│   ├── backfill.ts             # Recover missed codes from history
+│   └── help.ts                 # Command help
+├── database/
+│   ├── db.ts                   # SQLite connection & queries
+│   ├── userManager.ts          # User credentials storage
+│   ├── codeManager.ts          # Code tracking & history
+│   └── backfillManager.ts      # Backfill operations & locking
+├── handlers/
+│   ├── codeScanner.ts          # Message code detection
+│   └── backfillHandler.ts      # Message history scanning & redemption
+└── utils/
+    └── debugLogger.ts          # Response logging & cleanup
+
+lib/
+└── *.d.ts                      # Type definitions from game API
+```
+
+## Key Technologies
+
+- **Mise** - Task runner and tool version manager (MANDATORY)
+- **Bun 1.3.9** - JavaScript runtime (3-4x faster than Node.js)
+- **discord.js 14.26** - Discord bot framework
+- **sqlite3** - Local database
+- **node-fetch** - HTTP client (for game API)
+- **TypeScript** - Type-safe development
+
+## Important Notes
+
+### SSL Certificate Issue
+
+The Idle Champions API server has an expired SSL certificate. Always start the bot with:
+
+```bash
+NODE_TLS_REJECT_UNAUTHORIZED=0
+```
+
+### Instance ID Problem
+
+When calling game APIs (redeem, open chests, blacksmith), you must:
+
+1. Fetch fresh user details via `getUserDetails()`
+2. Extract `instance_id` from `details.instance_id`
+3. Pass it to the API call
+
+This prevents "Outdated instance id" errors from the server.
+
+### API Pattern
+
+All game API calls use URL query parameters, not JSON body:
+
+```
+POST /~idledragons/post.php?call=redeemcoupon&user_id=X&hash=Y&instance_id=Z&code=ABC
+```
+
+## Building
+
+Use Mise for all build tasks:
+
+```bash
+# Build the project
+mise run build
+
+# Watch for changes and rebuild
+mise run watch
+```
+
+## Common Tasks
+
+All tasks are run through Mise. Use `mise tasks` to see all available commands:
+
+```bash
+mise run install  # Install dependencies
+mise run dev      # Start development server
+mise run build    # Build TypeScript
+mise run watch    # Watch & rebuild on changes
+mise run lint     # Check code quality
+mise run lint:fix # Auto-fix linting issues
+mise run audit    # Check for vulnerabilities
+mise run clean    # Clean build artifacts
+```
+
+## Database
+
+SQLite database (`./data/idle.db`) with the following structure:
+
+```mermaid
+erDiagram
+    USERS ||--o{ REDEEMED_CODES : "has"
+    USERS ||--o{ PENDING_CODES : "has"
+    USERS ||--o{ AUDIT_LOG : "generates"
+    
+    USERS {
+        string discord_id PK
+        int user_id "Idle Champions user ID"
+        string user_hash "Idle Champions auth token"
+        string server "game server URL"
+        string instance_id "deprecated"
+        datetime created_at
+        datetime updated_at
+    }
+    
+    REDEEMED_CODES {
+        int id PK
+        string code
+        string discord_id FK
+        string status
+        json loot
+        datetime timestamp
+    }
+    
+    PENDING_CODES {
+        int id PK
+        string code
+        string discord_id FK
+        datetime added_at
+    }
+    
+    AUDIT_LOG {
+        int id PK
+        string discord_id FK
+        string action
+        json details
+        datetime timestamp
+    }
+    
+    BACKFILL_OPERATIONS {
+        int id PK
+        string initiated_by "user ID or 'system'"
+        datetime started_at
+        datetime completed_at
+        int codes_found
+        int codes_redeemed
+        string status "in_progress, completed, failed"
+    }
+```
+
+## Testing Commands
+
+```
+/setup user_id:123456 user_hash:abc123def456...
+
+/redeem code:TESTCODE
+
+/inventory
+
+/open chest_type:Gold count:5
+
+/blacksmith contract_type:Small hero_id:1 count:3
+
+/help
+```
+
+## Debugging
+
+The bot saves API responses to `debug/` folder automatically:
+
+- Files older than 1 hour are deleted
+- Useful for troubleshooting API issues
+- Format: `endpoint_YYYY-MM-DDTHH-mm-ss-SSSZ.json`
+
+## Environment Variables
+
+```bash
+DISCORD_TOKEN      # Bot token from Discord Developer Portal
+DISCORD_GUILD_ID   # Server ID (for guild-specific commands)
+DISCORD_CHANNEL_ID # Channel ID (for auto code scanning)
+DB_PATH            # Database file path (default: ./data/idle.db)
+NODE_ENV           # development or production
+```

docs/github-dependabot.md

@@ -7,36 +7,43 @@ Dependabot automatically keeps your dependencies up-to-date by creating pull req
 The configuration in `.github/dependabot.yml` covers three ecosystems:
 
 ### 1. **npm Dependencies** (Weekly)
+
 - Checks for updates every Monday at 3:00 AM UTC
 - Limits to 5 open PRs at a time
 - Groups development and runtime dependencies separately
 - Auto-rebases branches
 - Targets: TypeScript, ESLint, Bun, Discord.js, and other npm packages
 
 ### 2. **GitHub Actions** (Weekly)
+
 - Checks for updates every Monday at 4:00 AM UTC
 - Auto-rebases branches
 - Keeps CI/CD workflows up-to-date
 
 ### 3. **Docker** (Weekly)
+
 - Checks for base image updates every Monday at 5:00 AM UTC
 - Watches the `debian:13-slim` base image
 - Auto-rebases branches
 
 ## Managing Dependabot PRs
 
 ### Enable Dependabot
+
 Dependabot is enabled by default for all public repositories. For private repos:
+
 1. Go to **Settings → Code security & analysis**
 2. Enable **Dependabot version updates** and **Dependabot alerts**
 
 ### Review & Merge
+
 1. **Actions tab** → View Dependabot PRs
 2. Review the changelog and dependencies
 3. Run tests (GitHub Actions will run automatically)
 4. Approve and merge when confident
 
 ### Commands
+
 Add these comments to Dependabot PRs:
 
 ```
@@ -49,12 +56,15 @@ Add these comments to Dependabot PRs:
 ```
 
 ### Configure Intervals
+
 Change update frequency by modifying the `schedule.interval` in `.github/dependabot.yml`:
+
 - `daily` - Check every day
 - `weekly` - Check every week (default)
 - `monthly` - Check every month
 
 ### Disable for Specific Packages
+
 Add to your `package.json`:
 
 ```json
@@ -66,10 +76,11 @@ Add to your `package.json`:
 ```
 
 Or in `.github/dependabot.yml`:
+
 ```yaml
 ignore:
-  - dependency-name: "package-name"
-  - dependency-name: "another-package"
+  - dependency-name: 'package-name'
+  - dependency-name: 'another-package'
 ```
 
 ## Security Updates
@@ -92,15 +103,18 @@ Dependabot will **always** create PRs for security vulnerabilities regardless of
 ## Troubleshooting
 
 **Dependabot not creating PRs:**
+
 - Check it's enabled in Settings
 - Verify `.github/dependabot.yml` syntax
 - Wait up to 24 hours for first run
 
 **Too many PRs:**
+
 - Reduce `open-pull-requests-limit` in `.github/dependabot.yml`
 - Change `interval` to `monthly` instead of `weekly`
 
 **Want to skip an update:**
+
 - Comment `@dependabot ignore this dependency` on the PR
 - Or add to `ignore` list in `.github/dependabot.yml`
 

docs/github-deployment.md

@@ -23,6 +23,7 @@ This workflow automatically builds and publishes Docker images to GitHub Contain
 Images are published to: `ghcr.io/YOUR_USERNAME/idle-code-redeemer-bot`
 
 Example tags:
+
 - `main-sha123456` - Commit SHA
 - `v2.0.0` - Semantic version
 - `2.0` - Major.minor version
@@ -61,7 +62,7 @@ deploy:
   runs-on: ubuntu-latest
   needs: build
   if: github.event_name == 'push' && github.ref == 'refs/heads/main'
-  
+
   steps:
     - name: Deploy via SSH
       uses: appleboy/ssh-action@master
@@ -76,6 +77,7 @@ deploy:
 ```
 
 **Setup Required:**
+
 1. Generate SSH key: `ssh-keygen -t ed25519 -f deploy_key`
 2. Add public key to server's `~/.ssh/authorized_keys`
 3. Add secrets to GitHub:
@@ -90,7 +92,7 @@ deploy:
   name: Deploy to Kubernetes
   runs-on: ubuntu-latest
   needs: build
-  
+
   steps:
     - name: Deploy to K8s
       uses: azure/k8s-deploy@v4
@@ -104,6 +106,7 @@ deploy:
 ### Option 3: Deploy to Container Orchestration Service
 
 Use services like:
+
 - **AWS ECS**: Use `aws-actions/amazon-ecs-deploy-task-definition`
 - **Azure Container Instances**: Use `azure/aci-deploy@v1`
 - **DigitalOcean App Platform**: Use `digitalocean/app_action@v1.1.0`
@@ -128,6 +131,7 @@ git push origin v2.0.0
 ```
 
 The workflow will automatically build and tag the image as:
+
 - `ghcr.io/username/idle-code-redeemer-bot:v2.0.0`
 - `ghcr.io/username/idle-code-redeemer-bot:2.0.0`
 - `ghcr.io/username/idle-code-redeemer-bot:2.0`
@@ -141,14 +145,17 @@ The workflow will automatically build and tag the image as:
 ## Troubleshooting
 
 **Build fails with "permission denied"**
+
 - Check Dockerfile permissions
 - Ensure all required files are committed to git
 
 **Image not published to registry**
+
 - Confirm you're on `main` branch or have a version tag
 - Check that GITHUB_TOKEN secret is available (automatic)
 
 **Deployment not triggering**
+
 - Verify the branch/tag matches the workflow triggers
 - Check the workflow file is in `.github/workflows/` directory