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

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

Adding a new Discord command

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

Adding a new database operation

Add method in
```
oxeye-db/src/lib.rs
```
Add types if needed in
```
models.rs
```
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.

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

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

Adding a new Discord command

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

Adding a new database operation

Add method in
```
oxeye-db/src/lib.rs
```
Add types if needed in
```
models.rs
```
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.

Claude Code Guide for Oxeye

Related Skills

Nano Banana Pro

Markdown Converter

1password