shishki_bot

Deterministic Telegram booking and lightweight operations reference for one stylist. Booking, authorization, reminders, and financial totals stay in tested code and database transactions rather than an LLM.

Current Status

• The clean-clone public proof is the automated test and integrity suite. It covers booking rules, admin authorization, reminders, referrals, and finance calculations with synthetic/in-memory data and fake senders.
• Current deployment, current operator use, real clients, adoption, and outcome metrics are not verified by public repository artifacts. Historical runtime notes are not current operating evidence.
• The implementation is deterministic: no LLM behavior or external agent skill is in the booking decision path.
• Machine-readable claim status: docs/evidence/public_operating_status.json.

Start Here

• docs/PROJECT_BRIEF.md - product brief and constraints.
• docs/ARCHITECTURE.md - architecture and mode decision.
• docs/DETERMINISTIC_CASE_STUDY.md - why v1 should stay deterministic and where future AI is blocked.
• docs/spec.md - product behavior and acceptance criteria.
• docs/tasks.md - implementation task graph.
• docs/CODEX_PROMPT.md - current Codex handoff state.
• docs/IMPLEMENTATION_CONTRACT.md - implementation rules.

Current Verification

python3 -m venv .venv
. .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -r requirements-dev.txt -e .
python -m ruff check app tests
python -m ruff format --check app tests
python -m pytest tests -q
python3 tools/integrity_check.py --root .
python3 tools/skill_security_gate.py --root . --discover-agent-skills --require-scanner

The CI workflow runs the same lint, format, test, integrity, and external skill security checks on push and pull request.

Passing these checks demonstrates repository behavior against fixtures. It does not demonstrate a live bot, real bookings, zero incidents, operator adoption, or business impact.

Local Setup

python3 -m venv .venv
. .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -r requirements-dev.txt -e .

Runtime configuration is read only from environment variables:

Variable	Required	Notes
BOT_TOKEN	yes	Telegram bot token. Do not commit it.
ADMIN_TELEGRAM_IDS	yes	Comma-separated Telegram numeric user IDs allowed to use admin actions.
DATABASE_URL	yes	Local prototype can use sqlite+aiosqlite:///./shishki_bot.db; production should use PostgreSQL.
TIMEZONE	yes	Business timezone, for example Asia/Tbilisi.
DEFAULT_PLACE	yes	Default appointment address shown to clients.
STYLIST_CONTACT_URL	yes	Public contact link for complex-service redirects.
DEFAULT_MAP_URL	no	Optional map link in client-facing messages.
YANDEX_PLACE / YANDEX_MAP_URL	no	Optional Yandex Maps link shown as Yandex in address lines.
GOOGLE_PLACE / GOOGLE_MAP_URL	no	Optional Google Maps link shown as Google in address lines.
WEBHOOK_SECRET	no	Reserved for webhook deployment mode. Current runtime uses polling.
ENV	no	Environment label, defaults to local.

Example local environment:

export BOT_TOKEN="123456:test-token"
export ADMIN_TELEGRAM_IDS="111111111"
export DATABASE_URL="sqlite+aiosqlite:///./shishki_bot.db"
export TIMEZONE="Asia/Tbilisi"
export DEFAULT_PLACE="Studio address"
export STYLIST_CONTACT_URL="https://t.me/stylist"
export YANDEX_PLACE="https://yandex.example/..."
export GOOGLE_PLACE="https://google.example/..."

Before the first local startup, create the database schema:

python - <<'PY'
import asyncio

from app.db.session import create_all, create_database_engine


async def main() -> None:
    engine = create_database_engine()
    try:
        await create_all(engine)
    finally:
        await engine.dispose()


asyncio.run(main())
PY

Bot Startup

After installing dependencies and exporting environment variables:

shishki-bot

Equivalent module command:

python -m app.main

The current runtime starts aiogram polling. Deployment and operator notes live in docs/DEPLOYMENT.md and docs/ADMIN_GUIDE.md.

Repository Layout

• app/config.py - environment-backed settings.
• app/main.py - import-safe application entrypoint.
• app/bot/handlers/ - Telegram handler modules for admin and client flows.
• app/bot/keyboards.py - reusable bot menu and callback payload definitions.
• app/db/models.py - SQLAlchemy models for users, clients, slots, bookings, status history, notifications, reminders, expenses, referrals, manual credits, and bonuses.
• app/db/session.py - async engine/session helpers.
• app/scheduler.py - reminder recovery, runtime delivery, and referral-bonus admin reminder scheduler.
• app/services/ - booking, notification, reminder, finance, client history, and referral services.
• tests/ - smoke, model, service, notification, and handler tests.

Workflow

This repository uses Codex for implementation. Claude Code slash commands are not required. If a playbook instruction mentions /bootstrap-new, use docs/CODEX_PROMPT.md and docs/tasks.md as the Codex equivalent entrypoint.