Nikolay Tatarinov
16bf1a1043
- Replaced the previous webapp with a new Mini App built using Next.js, improving performance and maintainability. - Updated the `.gitignore` to exclude Next.js build artifacts and node modules. - Revised documentation in `AGENTS.md`, `README.md`, and `architecture.md` to reflect the new Mini App structure and technology stack. - Enhanced Dockerfile to support the new build process for the Next.js application. - Updated CI workflow to build and test the Next.js application. - Added new configuration options for the Mini App, including `MINI_APP_SHORT_NAME` for improved deep linking. - Refactored frontend testing setup to accommodate the new structure and testing framework. - Removed legacy webapp files and dependencies to streamline the project.
52 lines
3.3 KiB
Markdown
52 lines
3.3 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), 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/`) |
|
|
| 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. 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/), [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.
|
|
- **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.
|
|
- **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.
|