Workout Bot

Personal Telegram bot for tracking workouts and daily steps. See ../docs/spec.md for the product spec.

Prerequisites

• Node.js LTS (≥ 22.x)
• Docker + Docker Compose (for local Postgres and Redis)
• A Telegram bot token from @BotFather

Local setup

cp .env.example .env       # then put your BOT_TOKEN in
docker compose up -d       # start postgres and redis (DB only)
npm install
npm run migrate            # apply Prisma migrations
npm run dev                # start the bot (long polling)
npm run worker             # in a second terminal: BullMQ worker

Locally docker compose runs only Postgres and Redis. The bot and worker run on the host via npm run dev / npm run worker so code changes pick up without rebuilds. The production app container lives in docker-compose.prod.yml for VPS deploys (docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d).

The HTTP /health endpoint is available at http://localhost:3001/health once the bot process is up.

Scripts

Command	What it does
npm run dev	Bot in watch mode (tsx).
npm run worker	BullMQ worker in watch mode.
npm run build	Type-check and emit to dist/.
npm start	Run the compiled bot (dist/index.js).
npm run migrate	prisma migrate dev.
npm run migrate:deploy	prisma migrate deploy (production).
npm test	Vitest.
npm run lint	ESLint.
npm run format	Prettier.

Project layout

src/
├── bot/        # grammY composers, command handlers, dialogs
├── domain/     # pure business logic (no I/O)
├── infra/      # adapters: db, telegram, queue, time
├── jobs/       # BullMQ producers and consumers
├── config/     # env parsing (zod), feature flags
├── i18n/       # string catalogs (ru only on v1)
├── lib/        # generic utilities
└── index.ts    # bot entrypoint
prisma/
└── schema.prisma
tests/
docker-compose.yml
.env.example