hitstar/README.md

Hitstar Backend - Deno 2 + TypeScript

Modern backend rewrite using Deno 2 and TypeScript with clean architecture principles.

Architecture

This backend follows Clean Architecture principles with clear separation of concerns:

src/server-deno/
├── domain/           # Domain models, types, and business rules (no dependencies)
├── application/      # Use cases and application services
├── infrastructure/   # External concerns (file system, networking, etc.)
├── presentation/     # HTTP routes, WebSocket handlers
├── shared/           # Shared utilities, constants, types
└── main.ts          # Application entry point and DI setup

Layers

1. Domain Layer: Pure business logic and types

   • No external dependencies
   • Models: Player, Room, Track, GameState
   • Domain services for core game logic

2. Application Layer: Use cases and orchestration

   • Game service (start game, process guesses, etc.)
   • Track service (load tracks, manage playlists)
   • Room service (create/join rooms, manage players)

3. Infrastructure Layer: External concerns

   • File system operations
   • Audio streaming
   • Token management
   • Metadata parsing

4. Presentation Layer: API and WebSocket

   • REST routes for HTTP endpoints
   • Socket.IO handlers for real-time game

Running

Development

deno task dev

Production

deno task start

Testing

deno task test
deno task test:watch

Code Quality

deno task lint
deno task fmt
deno task check

Dependencies

• @oak/oak: Modern HTTP framework for Deno
• socket.io: Real-time bidirectional event-based communication
• music-metadata: Audio file metadata parsing
• lru-cache: Token and cover art caching

Environment Variables

See .env.example for all available configuration options.