wynn/ts/CLAUDE.md

Wynncraft Tools TypeScript Codebase Documentation

Overview

This is a TypeScript application that provides tools and services for the Wynncraft Minecraft server. It synchronizes game data, manages a Discord bot, and provides API services for in-game authentication.

Architecture

Technology Stack

• Runtime: Node.js with TypeScript (ESNext target)
• Workflow Engine: Temporal.io for orchestration and scheduling
• Database: PostgreSQL with postgres client
• Cache: Redis via BentoCache
• Discord: Discordeno library for bot functionality
• DI Container: @needle-di/core for dependency injection
• Validation: Arktype and Zod for runtime type validation
• CLI: Clipanion for command-line interface
• Logging: Pino with logfmt formatting

Project Structure

ts/
├── src/
│   ├── activities/      # Temporal activities (atomic operations)
│   ├── apiserver/       # REST API contract definitions
│   ├── bot/            # Discord bot implementation
│   ├── cmd/            # CLI commands (worker, bot)
│   ├── config/         # Environment configuration
│   ├── constants/      # Application constants
│   ├── di/             # Dependency injection setup
│   ├── lib/            # Shared libraries and utilities
│   ├── logger/         # Logging configuration
│   ├── services/       # Service layer (database, cache, etc.)
│   └── workflows/      # Temporal workflows (orchestration)
├── package.json        # Dependencies and scripts
└── tsconfig.json      # TypeScript configuration

Core Components

1. CLI Commands

WorkerCommand (src/cmd/worker.ts)

• Runs the Temporal worker that processes workflows and activities
• Schedules 4 recurring workflows:
  • update-guild-players: Every 15 minutes - Updates guild member data
  • update_guild_leaderboards: Every 5 minutes - Updates guild leaderboard stats
  • update-all-guilds: Every hour - Full guild data sync
  • update-online-players: Every 31 seconds - Tracks online players

BotCommand (src/cmd/bot.ts)

• Initializes and runs the Discord bot
• Registers slash commands
• Connects to Discord gateway
• Handles user interactions

2. Workflows (Orchestration Layer)

Guild Workflows (src/workflows/guilds.ts)

• workflowSyncAllGuilds: Fetches and updates all guild data
• workflowSyncGuildLeaderboardInfo: Updates guild leaderboard statistics
• workflowSyncGuilds: Syncs specific guild data including members and territories

Player Workflows (src/workflows/players.ts)

• workflowSyncOnline: Tracks currently online players and their server locations
• Integrates with PlayerDB API for UUID resolution

Item Workflows (src/workflows/items.ts)

• workflowSyncItemDatabase: Synchronizes Wynncraft item database
• Uses hash-based change detection to minimize updates

Discord Workflows (src/workflows/discord.ts)

• workflowDiscordInteraction: Handles Discord slash commands and interactions
• Manages response lifecycle and modal interactions

3. Activities (Business Logic)

Activities are the atomic units of work in Temporal:

• Database Activities: Direct PostgreSQL operations
• Guild Activities: Fetch and update guild data from Wynncraft API
• Player Activities: Track online players and fetch UUIDs
• Leaderboard Activities: Process guild rankings and statistics
• Discord Activities: Send messages and handle interactions

4. Services

PostgreSQL Service (src/services/pg/index.ts)

• Manages database connections
• Provides SQL query interface
• Configured via environment variables

Temporal Service (src/services/temporal/index.ts)

• Manages Temporal client connections
• Custom data converter configuration
• Graceful shutdown handling

Wynncraft API Service (src/lib/wynn/wapi.ts)

• Centralized API client for Wynncraft endpoints
• Implements intelligent caching with BentoCache
• Request coalescing and retry logic
• Namespace-based cache organization

5. Data Models

Guild System

• Guilds: UUID, name, prefix, level, XP, territories, war stats
• Guild Members: Player association, rank, join date, contributions
• Season Results: Historical guild performance data

Player System

• Players: UUID, username, current server location
• Online Status: Real-time tracking of player locations

Item System

• Items: Internal name, display name, tier, type, full JSON data
• Metadata: Hash tracking for change detection

6. API Contract (src/apiserver/contract.ts)

REST API using ts-rest for in-game authentication:

• GET /api/v1/ingame/challenge: Generate authentication challenge
• POST /api/v1/ingame/solve: Solve challenge and receive token

Key Patterns

Dependency Injection

All services use constructor injection via @needle-di/core:

@injectable()
class MyService {
  constructor(private pg: PG) {}
}

Error Handling

• Temporal retry policies for transient failures
• Transaction rollback on database errors
• Structured logging with context

Caching Strategy

• Multi-tier caching with Redis backend
• TTL-based expiration
• Stale-while-revalidate for better performance
• Request deduplication

Database Patterns

• Upsert operations with ON CONFLICT
• Transactional consistency for related updates
• Prepared statements for performance

Configuration

Environment variables (loaded from .env):

• DISCORD_TOKEN: Discord bot authentication
• TEMPORAL_ADDRESS: Temporal server location
• TEMPORAL_NAMESPACE: Workflow namespace
• DATABASE_URL or individual DB params
• REDIS_URL: Cache backend
• WYNN_API_URL: Wynncraft API endpoint

Development

Path Aliases

• #/* maps to ./src/* for clean imports

Build Tools

• TypeScript with strict mode
• Barrelsby for automatic barrel exports
• Webpack bundling for Temporal workflows

Commands

• yarn barrels: Generate barrel export files

Security Considerations

• No hardcoded credentials
• Environment-based configuration
• Prepared statements for SQL injection prevention
• Token-based authentication for API

Performance Optimizations

• Connection pooling for database
• Request caching and coalescing
• Hash-based change detection
• Batch operations where possible
• Indexed database queries

Monitoring and Observability

• Structured logging with Pino
• Request IDs for tracing
• Error tracking with full context
• Performance metrics via Temporal