# AGENTS.md

## Project Role

Slack invitation + data collection service with extensible multi-team support.

## Tech Stack

- FastAPI
- Tailwind CSS (CDN) for all templates in `app/templates/`
- SQLModel
- Alembic
- Celery + Redis
- uv
- pytest

## Key Directories and Entrypoints

- `app/main.py` - FastAPI app entry
- `app/core/config.py` - environment config
- `app/core/db.py` - engine/session factory
- `app/models/` - SQLModel table models
- `app/routes/` - API routes
- `app/managers/` - business logic
- `app/tasks/` - Celery tasks
- `app/alembic/` - DB migrations (`app/alembic.ini`)
- `tests/` - pytest suite

## Critical Conventions

- **Alembic migrations**: Do **not** create migration files manually. Always use the Alembic CLI to generate them (`alembic revision --autogenerate -m "short_name"`). Use short, descriptive migration names (e.g. `add_teams_table`, `add_invite_link_column`).
- Keep existing HTTP paths and response contracts unchanged.
- Keep existing table/column names and data types unchanged.
- Team config must come from `teams` table, never hardcode team list.
- Invite link source is `teams.invite_link`.
- We do **not** use Slack Admin API to invite users: `admin.users.invite` is Enterprise-only. Invites are done by having users click a pre-generated invite link stored in `teams.invite_link`.
- Use clear task names:
  - `sync_slack_users_task`
  - `sync_slack_channels_task`
  - `run_sync_for_all_teams_task`
  - `refresh_invite_links_task`

## Common Commands

```bash
uv sync
uv run alembic -c app/alembic.ini upgrade head
# Create new migration (use short name, e.g. add_teams_table):
uv run alembic -c app/alembic.ini revision --autogenerate -m "short_name"
uv run fastapi dev app/main.py
uv run pytest
uv run celery -A app.celery_app:celery_app worker -l info
uv run celery -A app.celery_app:celery_app beat -l info
```