Claude Code Guide for Oxeye

Project Overview

Oxeye is a Discord bot + Minecraft Mod + backend service that tracks who's online on Minecraft servers and displays that information in Discord. It consists of:

• Rust Backend: HTTP API server + Discord bot (single binary)
• Minecraft Fabric Mod: Java mod that reports player join/leave events
• SQLite Database: Persistent storage for server links and player status

Enabled Tools

• ast-grep: Available for structural code search and refactoring using AST patterns. Use for finding/modifying Rust and Java code structures.

Quick Reference

Build Commands

# Build the project
cargo build --release

# Run tests
cargo test

# Run with Discord token
DISCORD_TOKEN=<token> cargo run

# Check without building
cargo check

Project Structure

oxeye/
├── oxeye-backend/        # Main Rust HTTP server + Discord bot
│   ├── src/
│   │   ├── main.rs       # Entry point, runtime setup
│   │   ├── lib.rs        # Router creation, middleware setup
│   │   ├── config.rs     # Environment configuration
│   │   ├── routes.rs     # HTTP endpoint handlers
│   │   ├── error.rs      # Error types and HTTP mapping
│   │   ├── helpers.rs    # Utility functions
│   │   ├── validation.rs # Input validation
│   │   └── discord_commands.rs  # Discord slash commands
│   └── tests/            # Integration tests
├── oxeye-db/             # Database abstraction crate
│   └── src/
│       ├── lib.rs        # Database operations (~60 methods)
│       ├── models.rs     # Data types
│       └── error.rs      # Database errors
├── oxeye-mod/            # Minecraft Fabric Mod (Java/Gradle)
├── docs/                 # Architecture documentation
├── Cargo.toml            # Workspace root
└── DESIGN.md             # API specification

Technology Stack

| Component | Technology | Notes | |-----------|------------|-------| | Web Framework | Axum 0.8 | HTTP server with middleware | | Async Runtime | Tokio | Full features enabled | | Discord Bot | Poise 0.6 | Command framework on Serenity | | Database | tokio-rusqlite | Async SQLite with WAL mode | | Serialization | Serde + serde_json | JSON encoding/decoding | | Error Handling | thiserror | Ergonomic error types | | Logging | tracing | Structured logging | | Rate Limiting | tower-governor | IP-based rate limiting |

Rust Edition: 2024

Architecture Patterns

Layered Design

HTTP Request → Validation (validation.rs) → Routes (routes.rs) → Database (oxeye-db)
Discord Command → discord_commands.rs → Database (oxeye-db)

Error Handling

• All errors flow through AppError enum in error.rs
• Database errors wrapped and mapped to HTTP status codes
• Internal errors logged server-side, user-friendly messages returned
• Never expose SQL, stack traces, or library names to clients

Authentication

• API keys generated as oxeye-sk-{32 alphanumeric}
• Keys stored as SHA-256 hashes (never plaintext)
• Bearer token authentication on protected endpoints
• Connection codes format: oxeye-{6 alphanumeric} (10-minute TTL)

Concurrency

• SQLite with WAL mode for concurrent reads
• Tokio async/await throughout
• Rate limiting prevents abuse

API Endpoints

| Method | Path | Auth | Purpose | |--------|------|------|---------| | POST | /connect | None | Redeem connection code | | POST | /join | Bearer | Report player joining | | POST | /leave | Bearer | Report player leaving | | POST | /sync | Bearer | Replace entire player list | | GET | /status | Bearer | Check server connection | | POST | /disconnect | Bearer | Unlink server |

Discord Commands

• /oxeye connect <name> - Admin-only, generates linking code
• /oxeye list - Shows all servers in guild
• /oxeye status <name> - Shows online players with join times

Database Schema

Three main tables:

• pending_links - Connection codes with TTL
• servers - Linked Minecraft servers (api_key_hash, name, guild_id)
• online_players - Players currently online with join timestamps

Testing

# Run all tests
cargo test

# Run specific test
cargo test test_name

# Run with output
cargo test -- --nocapture

Tests use in-memory SQLite for speed. Coverage includes:

• All HTTP endpoints (success and error cases)
• Database operations
• Input validation
• Rate limiting behavior
• Error response formats

Environment Variables

| Variable | Default | Required | Description | |----------|---------|----------|-------------| | DISCORD_TOKEN | - | Yes | Discord bot token | | PORT | 3000 | No | HTTP server port | | DATABASE_PATH | oxeye.db | No | SQLite database file | | REQUEST_BODY_LIMIT | 1048576 | No | Max request size (bytes) | | REQUEST_TIMEOUT_SECS | 30 | No | Request timeout |

Rate limit variables also available (see config.rs).

Code Style

• Use #[debug_handler] on Axum handlers for better error messages
• Validation happens before any database operations
• Helper functions in helpers.rs for common operations
• Comprehensive error messages that help users fix issues
• Tests alongside implementation in oxeye-db, separate test files in oxeye-backend

Common Tasks

Adding a new HTTP endpoint

1. Add route in lib.rs under appropriate rate-limit tier
2. Add handler in routes.rs
3. Add validation if needed in validation.rs
4. Add database methods if needed in oxeye-db/src/lib.rs
5. Add integration tests in tests/integration_tests.rs

Adding a new Discord command

1. Add command function in discord_commands.rs
2. Register in the commands vector in main.rs
3. Database access via ctx.data().db

Adding a new database operation

1. Add method in oxeye-db/src/lib.rs
2. Add types if needed in models.rs
3. Add tests in the #[cfg(test)] module

Key Files to Understand

• oxeye-backend/src/lib.rs:1-119 - Router setup, middleware, rate limiting tiers
• oxeye-backend/src/routes.rs:1-143 - All HTTP handlers
• oxeye-db/src/lib.rs:1-400 - Database schema and core operations
• DESIGN.md - Complete API specification
• docs/architecture-decisions.md - Performance decisions and caching strategy

Docker

Multi-architecture builds available:

• Dockerfile.amd64 - x86-64
• Dockerfile.arm64 - ARM64 (Raspberry Pi, Apple Silicon)

Final images are minimal scratch-based containers.