Files

Nikolay Tatarinov 16bf1a1043 feat: migrate to Next.js for Mini App and enhance project structure

- 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.

2026-03-03 16:04:08 +03:00

3.3 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), 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 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.
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.
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.

3.3 KiB Raw Blame History