Nikolay Tatarinov
37d4226beb
- 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.
50 lines
2.7 KiB
Markdown
50 lines
2.7 KiB
Markdown
# 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](CONTRIBUTING.md) and [README.md](README.md) for full setup.
|
|
- **Lint:** `ruff check duty_teller tests`
|
|
- **Security:** `bandit -r duty_teller -ll`
|
|
|
|
## Documentation
|
|
|
|
- User and architecture docs: [docs/](docs/), [docs/architecture.md](docs/architecture.md).
|
|
- Configuration reference: [docs/configuration.md](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](https://www.conventionalcommits.org/) (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](AGENTS.md) is the single versioned reference for AI and maintainers.
|