duty-teller/AGENTS.md

Duty Teller — AI agent documentation

This file is for AI assistants (e.g. Cursor) and maintainers. All project documentation and docstrings must be in English. User-facing UI strings remain localized (ru/en) in duty_teller/i18n/.

Project summary

Duty Teller is a Telegram bot plus Mini App for team duty shift calendar and group reminders. Stack: python-telegram-bot v22, FastAPI, SQLite (SQLAlchemy), Next.js (static export) Mini App. The bot and web UI support Russian and English; configuration and docs are in English.

Key entry points

• CLI / process: main.py or, after pip install -e ., the duty-teller console command. Both delegate to duty_teller.run.main().
• Application setup: duty_teller/run.py — builds the Telegram Application, registers handlers via register_handlers(app), runs polling and FastAPI in a thread, calls config.require_bot_token() so the app exits clearly if BOT_TOKEN is missing.
• HTTP API: duty_teller/api/app.py — FastAPI app, route registration, static webapp mounted at /app.

Where to change what

Area	Location
Telegram handlers	duty_teller/handlers/
REST API	duty_teller/api/
Business logic	duty_teller/services/
Database (models, repository, schemas)	duty_teller/db/
Translations (ru/en)	duty_teller/i18n/
Duty-schedule parser	duty_teller/importers/
Config (env vars)	duty_teller/config.py
Miniapp frontend	webapp-next/ (Next.js, Tailwind, shadcn/ui; static export in webapp-next/out/)
Admin panel (Mini App)	webapp-next/src/app/admin/page.tsx; API: GET /api/admin/me, GET /api/admin/users, PATCH /api/admin/duties/:id
Migrations	alembic/ (config in pyproject.toml under [tool.alembic])

Running and testing

• Tests: From repository root: pytest. Use PYTHONPATH=. if imports fail. See CONTRIBUTING.md and README.md for full setup. Frontend: cd webapp-next && npm test && npm run build.
• Lint: ruff check duty_teller tests
• Security: bandit -r duty_teller -ll

Documentation

• User and architecture docs: docs/, docs/architecture.md.
• Mini App design guideline — Theme, layout, safe areas, component patterns, accessibility for webapp-next.
• Configuration reference: docs/configuration.md.
• Build docs: pip install -e ".[docs]", then mkdocs build / mkdocs serve.

Docstrings and code comments must be in English (Google-style docstrings). UI strings are the only exception; they live in duty_teller/i18n/.

Conventions

• Commits: Conventional Commits (e.g. feat:, fix:, docs:).
• Branches: Gitea Flow; changes via Pull Request.
• Testing: pytest, 80% coverage target; unit and integration tests.
• Config: Environment variables (e.g. .env); no hardcoded secrets.
• Database: One logical transaction per session_scope — a single commit at the end of the business operation (e.g. in run_import). Repository helpers used inside such a flow (e.g. get_or_create_user_by_full_name) accept commit=False and let the caller commit once.
• Error handling: Do not send str(exception) from parsers or DB to the user. Use generic i18n keys (e.g. import.parse_error_generic, import.import_error_generic) and log the full exception server-side.
• Mini App (webapp-next): When adding or changing UI in webapp-next/, follow the Mini App design guideline: use only design tokens and Tailwind aliases from it, apply layout/safe-area/accessibility rules, and use the checklist for new screens or components.
• Cursor: The project does not version .cursor/. You can mirror this file in .cursor/rules/ locally; AGENTS.md is the single versioned reference for AI and maintainers.