Files

Nikolay Tatarinov 37d4226beb chore: update project documentation and configuration files

- Added AGENTS.md for AI agent documentation and maintainers, outlining project structure and conventions.
- Updated CONTRIBUTING.md to specify that all project documentation must be in English, including README and docstrings.
- Enhanced README.md to reference documentation guidelines and the new AGENTS.md file.
- Cleaned up .gitignore by removing unnecessary entries for cursor-related files.
- Introduced new .cursor rules for backend, frontend, project architecture, and testing to standardize development practices.

2026-03-02 20:02:20 +03:00

2.7 KiB

Raw Blame History

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), Vanilla JS webapp. 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/`
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.
Lint: ruff check duty_teller tests
Security: bandit -r duty_teller -ll

Documentation

User and architecture docs: docs/, docs/architecture.md.
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.
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.

2.7 KiB Raw Blame History