Local Development

This guide covers everything you need to know about developing the Activity Challenge Bot on your local machine.

Development Workflow

Starting Your Development Session

# 1. Pull latest changes
git pull origin main

# 2. Install/update dependencies
bun install

# 3. Start the database (if using containers)
bun run pod:up

# 4. Start the bot in development mode
bun run dev

The bot will automatically restart when you make changes to any TypeScript file.

Making Changes

1. Create a feature branch

   git checkout -b feature/your-feature-name

2. Make your changes

   • Edit code in src/
   • The bot restarts automatically with bun run dev
   • Test changes in Telegram immediately

3. Test your changes

   bun test

4. Lint your code

   bun run lint

5. Commit and push

   git add .
   git commit -m "feat: add new feature"
   git push origin feature/your-feature-name

Development Scripts

Bot Scripts

# Start bot in development mode (hot reload)
bun run dev

# Start bot in production mode
bun run start

# Add test data to database
bun run populate

# Clear all data from database (keeps schema)
bun run clear

Container Scripts

# Start services (bot + database) in development mode
bun run pod:dev

# Start services in background
bun run pod:up

# Stop services
bun run pod:down

# Restart just the bot
bun run pod:restart

# View bot logs (follow mode)
bun run pod:logs

# Open shell in bot container
bun run pod:shell

Container Utilities

# Populate test data in container
bun run pod:populate

# Clear data in container
bun run pod:clear

# Initialize guilds in container
bun run pod:init-guilds

# Run tests in container
bun run pod:test

Database Scripts

# Open PostgreSQL shell (container)
bun run pod:db:psql

# From there, you can run SQL queries:
# \dt          - List tables
# \d users     - Describe users table
# SELECT * FROM users;

Testing Scripts

# Run all tests once
bun test

# Run tests in watch mode (re-runs on file changes)
bun run test:watch

# Run tests with coverage report
bun run test:coverage

See Testing Guide for detailed testing patterns.

Documentation Scripts

# Start docs dev server
bun run docs:dev

# Build docs for production
bun run docs:build

# Preview production docs build
bun run docs:preview

Web App Scripts

# Install webapp dependencies
bun run webapp:install

# Start webapp dev server
bun run webapp:dev

# Build webapp for production
bun run webapp:build

Working with the Database

Direct Database Access

Using the Container

# Open psql in the container
bun run pod:db:psql

# Now you're in the PostgreSQL shell
activity_challenge_bot=# \dt                    # List tables
activity_challenge_bot=# SELECT * FROM users;   # Query users
activity_challenge_bot=# \q                     # Quit

Using Local PostgreSQL

psql -U postgres -d activity_challenge_bot

Next Steps

• Understand Testing - Testing strategies
• Explore Project Structure - Code organization
• Review Architecture Overview - System design
• Read Contributing Guidelines - Contribution process