190 lines
6.4 KiB
Markdown
190 lines
6.4 KiB
Markdown
|
# 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:
|
||
|
|
```typescript
|
||
|
|
@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
|