Developer Guide

◈ Developer Guide

Welcome to the development side of WordSeek. This guide provides an overview of the project structure, technology choices, and how to contribute to the codebase.

---

◈ Project Structure

WordSeek is organized into a clean, modular structure:

• src/: Core source code.
  • commands/: Command handlers (e.g., /new, /score).
  • handlers/: Message and callback query handlers.
  • services/: Business logic (Game engine, user management).
  • queues/: Background jobs (BullMQ).
  • config/: Environment and constant configurations.
  • helpers/: Reusable utility functions.
• migrations/: Database schema migrations (Kysely).
• wiki_drafts/: Source files for this documentation.

---

◈ Tech Stack Rationale

▪ Bun.js: Chosen for its incredible startup speed and built-in support for TypeScript and SQLite (for tests).
▪ grammY: The most modern and extensible Telegram framework, allowing for clean composer-based logic.
▪ Kysely: Provides full type-safety for SQL queries, preventing runtime database errors.
▪ Redis: Essential for managing game state and high-frequency ranking updates.

---

◈ Development Workflow

▪ Local Setup

Follow the Getting Started guide to set up your environment. Use bun run dev to start the bot with hot-reloading.

▪ Database Migrations

We use Kysely for migrations. To create a new migration:

bun run kysely:make my_migration_name

To apply migrations:

bun run db:migrate

▪ Adding a Command

1. Create a new file in src/commands/.
2. Implement your logic using a Composer.
3. Export the composer and register it in src/commands/index.ts.

---

◈ Contributing

We welcome contributions!

1. Fork the repository.
2. Create a feature branch.
3. Commit your changes with clear messages.
4. Open a Pull Request.

---

Next: For common issues and solutions, see the FAQ & Troubleshooting guide.