Telegram Support Control Center

Portfolio/demo repository for a Telegram-first support and sales operations dashboard.

This codebase demonstrates a full-stack workflow: Telegram Mini App UI, NestJS API, Prisma persistence, Socket.IO live updates, a Telegraf bot entrypoint, and reusable n8n automation templates. The repository is intentionally prepared as a public demo with synthetic seed data and placeholder credentials. It is not presented as a full production client repository.

Quick Links

• Repository: MaryanKostrubyak/react-bot
• Release notes: see the GitHub Releases page
• Validation flow: docs/release-checklist.md
• Contribution guide: CONTRIBUTING.md
• Security policy: SECURITY.md

What This Project Is

react-bot is a public showcase of a Telegram-centric support operations stack:

• a Next.js dashboard that can work as a Telegram Mini App
• a NestJS API with auth, ticket workflows, stats, and realtime updates
• a Telegraf bot entrypoint for Telegram-driven ticket creation
• n8n automation templates for manager notifications and follow-up flows

It is aimed at recruiters, clients, and engineers who want to review architecture, product thinking, and full-stack implementation in one repository.

How To Review This Repo Quickly

If you are opening this repo for the first time, the fastest path is:

1. Read the screenshots section below.
2. Scan the architecture and tech stack sections.
3. Run the local demo or smoke test.
4. Open apps/web, apps/api, and n8n/templates to inspect the main product surfaces.

Screenshots

Dashboard

Kanban Board

Ticket Inbox

What This Demo Shows

• Telegram Mini App compatible dashboard built with Next.js App Router and Tailwind CSS.
• Role-aware ticket operations for admins, managers, and operators.
• Ticket queue, Kanban board, calendar view, ticket detail view, messages, and automation controls.
• NestJS API with JWT auth, Telegram initData validation, Prisma models, audit logs, and health checks.
• Socket.IO events for live ticket and message refreshes.
• Telegraf bot flow for creating tickets from Telegram conversations.
• n8n workflow templates for ticket-created, status-changed, and reminder automations.
• Docker Compose setup for API, web, n8n, Caddy gateway, and optional ngrok exposure.

Architecture

apps/
  api/      NestJS API, Prisma, auth, tickets, stats, automations, Socket.IO
  bot/      Telegraf bot for Telegram commands and ticket creation
  web/      Next.js Mini App dashboard
packages/
  shared/   Shared enums, DTO schemas, JWT types, Telegram initData validation
n8n/
  templates/ Demo workflow templates with placeholder credentials
docs/
  screenshots/ README screenshots captured from seeded demo data

Tech Stack

Layer	Tools
Web app	Next.js 14, React 18, Tailwind CSS, Headless UI, Heroicons
API	NestJS 10, Prisma, JWT, Socket.IO
Bot	Telegraf
Shared contracts	TypeScript, Zod
Database	SQLite for demo, Prisma schema can be adapted to PostgreSQL
Automations	n8n webhook templates
Local infra	Docker Compose, Caddy

Quick Start: UI/API Demo

This path is enough to review the dashboard with synthetic data.

npm install
Copy-Item .env.example .env

In terminal 1:

$env:DATABASE_URL='file:./dev.db'
$env:JWT_SECRET='local-demo-secret'
$env:DEV_LOGIN_TOKEN='dev-token'
$env:ADMIN_TG_USER_ID='123456789'
$env:BOT_TOKEN='local-demo-bot-token'

npm --workspace apps/api run prisma:generate
npm --workspace apps/api run prisma:push
npm --workspace apps/api run prisma:seed
npm run dev:api

In terminal 2:

$env:NEXT_PUBLIC_API_URL='http://localhost:3001/api'
$env:NEXT_PUBLIC_WS_URL='http://localhost:3001'
$env:NEXT_PUBLIC_DEV_LOGIN_TOKEN='dev-token'

npm run dev:web

Open http://localhost:3000.

Validate the running dev stack:

$env:SMOKE_WEB_URL='http://localhost:3000'
$env:SMOKE_API_URL='http://localhost:3001/api'
$env:DEV_LOGIN_TOKEN='dev-token'
node scripts/e2e-smoke.mjs

Docker Demo

For a containerized API/web demo through the Caddy gateway:

Copy-Item .env.example .env
docker compose up --build api web gateway
docker compose exec api npm --workspace apps/api run prisma:push
docker compose exec api npm --workspace apps/api run prisma:seed

Open http://localhost:8080.

Smoke-check the gateway flow:

$env:SMOKE_BASE_URL='http://localhost:8080'
$env:DEV_LOGIN_TOKEN='dev-token-change-me'
node scripts/e2e-smoke.mjs

For the full Telegram and ngrok workflow, replace the placeholders in .env first, especially BOT_TOKEN, ADMIN_TG_USER_ID, JWT_SECRET, WEBAPP_URL, and NGROK_AUTHTOKEN, then run:

docker compose up --build

Demo Data

apps/api/prisma/seed.ts creates a synthetic workspace:

• 1 admin, 1 manager, and 1 operator.
• 6 demo tickets across NEW, QUALIFIED, IN_PROGRESS, WAITING_CUSTOMER, DONE, and LOST.
• Seeded messages, assignees, priorities, tags, due dates, and realistic support/sales scenarios.

No customer data is required for the demo.

n8n Templates

The n8n/templates folder contains importable demo workflows:

• template-ticket-created-sheets.json - append ticket data to Google Sheets.
• template-status-changed-telegram.json - notify a manager when a ticket status changes.
• template-ticket-created-reminder.json - wait 2 hours after ticket creation and notify a manager.

Each template uses placeholders such as <YOUR_BOT_TOKEN>, <MANAGER_CHAT_ID>, and <CONNECT_IN_UI>.

Public Repository Scope

This repository is formatted for portfolio review:

• Secrets are excluded through .gitignore.
• .env.example contains placeholders only.
• Full/decrypted n8n exports and local zip exports are ignored.
• README screenshots use seeded demo data.
• The code illustrates architecture and implementation style, not a complete production deployment package.
• Public repo metadata is intentionally aligned for GitHub discovery: README, changelog, issue templates, CI, and releases.

Before adapting this for production, add environment-specific hardening, persistent infrastructure, stricter secret management, telemetry, CI/CD, production database migrations, and deployment-specific security review.

GitHub Release Flow

• CI runs on every push to main and on pull requests.
• Release runs for tags matching v*.*.* and creates a GitHub release after build and smoke validation pass.
• The step-by-step checklist lives in docs/release-checklist.md.