Sports Operations Automation

Operational backend system designed to automate sports team convocations, structured communication workflows, and real-world coordination processes inside sports organizations.

Project Focus

• Operational workflow automation
• Structured communication generation
• Controlled AI-assisted refinement
• WhatsApp delivery integration
• Deterministic backend orchestration
• Real-world organizational utility

---

Core Workflow

1. Select scheduled match
2. Generate deterministic convocation draft
3. Adjust player availability
4. Optionally refine message using AI
5. Confirm final communication
6. Deliver through WhatsApp

---

Architecture

Layered modular monolith with hexagonal-inspired boundaries:

app/
├── presentation/    # HTTP routes, request/response schemas
├── application/     # Use cases, workflow orchestration
├── domain/          # Entities, business rules (no external dependencies)
├── infrastructure/  # Database, AI adapter, WhatsApp adapter
├── config/          # Settings, logging
└── shared/          # Cross-cutting utilities

Dependency direction: presentation → application → domain
Infrastructure is injected; domain never depends on it.

---

Stack

Layer	Technology
Backend	Python 3.12, FastAPI
ORM	SQLAlchemy 2.x
Database	PostgreSQL 16
Migrations	Alembic
Config	Pydantic Settings
AI	OpenAI API (optional refinement)
Messaging	WhatsApp API
Infrastructure	Docker, Fly.io

---

Local Setup

Prerequisites

• Docker and Docker Compose installed
• Python 3.12 (for running outside Docker)

1. Clone and configure environment

git clone <repository-url>
cd convocation-automation-system
cp .env.example .env

Edit .env and fill in OPENAI_API_KEY and WHATSAPP_API_KEY.

2. Run with Docker Compose

docker-compose up --build

The API will be available at http://localhost:8000.

3. Verify

curl http://localhost:8000/health
# {"status": "ok"}

4. Run migrations

docker-compose exec api alembic upgrade head

Running without Docker

python -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install -r requirements.txt
uvicorn app.main:app --reload

Requires a running PostgreSQL instance and a valid DATABASE_URL in .env.

---

Engineering Principles

• AI is treated as a constrained external dependency
• Operational truth comes from structured persistence
• Human confirmation remains the final authority
• Simplicity is prioritized over premature complexity