Imported from arsen10fe/calendarmeet (
AGENTS.md). Install upstream withnpx skills add arsen10fe/calendarmeet. Copyright stays with the author.
AGENTS.md
Structural map for AI agents working on this project. Keep factual; update when the project structure changes significantly.
Project Overview
CalendarMeet is a meeting scheduling service (Calendly-style) with a Telegram bot that delivers booking notifications and meeting info to hosts. See .ai-factory/DESCRIPTION.md for the full specification.
Tech Stack
- Programming language: TypeScript
- Framework: Next.js (App Router) — full-stack, hosts both web UI and the Telegram bot webhook
- Database: PostgreSQL
- ORM: Prisma
- Styling: Tailwind CSS v4
- Bot: grammY (webhook mode inside Next.js)
Project Structure
app/ # Next.js App Router (presentation, thin adapters)
├── (auth)/login/ # login page + server action
├── (app)/schedule/ # day/week views, new-meeting form, meeting actions
├── (app)/profile/ # account info + Telegram link code
├── admin/employees/ # access management (admin only)
├── api/auth/[...nextauth]/ # Auth.js handlers
└── api/telegram/ # grammY webhook (secret-token protected)
lib/
├── domain/ # PURE logic: meeting validation, overlap, timezones (+ unit tests)
├── services/ # use-case orchestration: meetings (serializable tx), employees, auth guard, notifications, telegram linking
├── repositories/ # all Prisma data access
├── bot/ # grammY bot, commands, formatter, notification channel
├── infrastructure/ # db.ts (Prisma client), logger (pino), errors
└── generated/prisma/ # generated Prisma client (gitignored)
components/ # ui/ (shadcn), layout/, schedule/, admin/, profile/
prisma/ # schema + migrations (EXCLUDE constraint is hand-written!) + seed
scripts/ # set-webhook.ts, bot-dev.ts (long polling for local dev)
tests/ # vitest setup (test DB routing, migrate deploy)
e2e/ # Playwright specs + cleanup global-setup
docs/ # detailed documentation pages
.ai-factory/ # AI Factory artifacts (description, rules, plans, architecture)
Key Entry Points
| File | Purpose |
|---|---|
| .ai-factory/DESCRIPTION.md | Project specification and tech stack |
| .ai-factory/ARCHITECTURE.md | Architecture pattern, folder structure, dependency rules |
| .ai-factory/rules/base.md | Coding conventions (naming, modules, errors, timezones) |
| .ai-factory/config.yaml | AI Factory configuration (language, paths, git workflow) |
| .mcp.json | MCP servers: postgres (requires DATABASE_URL), shadcn + magicui component registries |
Documentation
| Document | Path | Description |
|---|---|---|
| README | README.md | Project landing page |
| Getting Started | docs/getting-started.md | Prerequisites, database, migrations, first run, tests |
| Configuration | docs/configuration.md | Environment variables reference |
| Telegram Bot | docs/telegram-bot.md | BotFather setup, webhook, account linking |
| Conflict Prevention | docs/conflict-prevention.md | Three-layer double-booking defense design |
AI Context Files
| File | Purpose |
|---|---|
| AGENTS.md | This file — structural map for AI agents |
| .ai-factory/DESCRIPTION.md | Enhanced project description and requirements |
| .ai-factory/ARCHITECTURE.md | Architecture guidelines |
Project Skills
| Skill | Use for |
|---|---|
| booking-domain | Slot computation, timezone rules, double-booking prevention, booking lifecycle |
| telegram-bot-nextjs | grammY bot in Next.js: webhook, commands, notifications |
| calendarmeet-design | Design language: tokens, typography, booking UI patterns — consult for ANY UI work |
| shadcn | Adding/composing shadcn/ui components (Calendar, Dialog, Combobox, Sonner) |
| web-design-guidelines | UI/accessibility review before shipping a page |
| nextjs-app-router-patterns | Server Components, streaming, data fetching |
| tailwind-design-system | Tailwind v4 tokens, component patterns |
| prisma-database-setup / prisma-client-api | Prisma configuration and query API |
| framer-motion-animator | UI animations (restrained — see calendarmeet-design) |
Agent Rules
- Decompose compound shell commands instead of chaining them:
- Incorrect:
git checkout main && git pull - Correct: first
git checkout main, thengit pull origin main
- Incorrect:
- All timestamps in the database are UTC; timezone conversion happens only at the presentation edge (see .ai-factory/rules/base.md).
- Booking-related code must go through
lib/domain/— the web UI and the Telegram bot share the same domain functions. - The Telegram webhook route must validate the secret token; never expose bot tokens in code or logs.