Event Booking System

A backend-only REST API for booking event tickets, with two roles - Event Organizer (manages events) and Customer (browses events, books tickets, pays via a mocked Razorpay flow). No frontend in scope.

Full design rationale (data model, payment flow, deferred items) lives in PLAN.md. Architecture and coding conventions live in CLAUDE.md. Individual design/judgment calls made along the way, with reasoning, live in decisions.md.

• Live deployment: https://eventbooking.mridulabs.dev - see Deployment below
• Architecture diagram + DBML schema: docs/architecture/
• Runnable API collection: bruno/ (Bruno collection, alternative to Swagger UI - see its own README for setup)

Tech Stack

• Framework: Flask
• Validation: Pydantic, wired through spectree - request schemas double as the OpenAPI spec
• Database: PostgreSQL via SQLAlchemy
• Background jobs: Celery, broker = Redis
• Auth: JWT (Flask-JWT-Extended), stateless, 2-day default expiry (configurable)
• Rate limiting: Flask-Limiter, backed by Redis - stricter on /v1/sessions//v1/users, a generous default elsewhere
• Containerization: Docker / docker-compose

Architecture

Layered - Controller (HTTP) → Service (business logic) → Repository (DB access) - organized domain-first: each domain (app/users/, app/events/, app/bookings/, app/payments/, app/organizer_profiles/, app/reviews/, app/jobs/) owns its own model.py, dao_interface.py, repository.py, service.py, controller.py.

app/
├── users/               registration, login, JWT issuance
├── events/              event catalog (organizer-managed, browsable by city)
├── bookings/            ticket booking, capacity enforcement
├── payments/            real webhook receiver + gateway_client.py (calls the mock service below)
├── organizer_profiles/  organizer company/bank/PAN details, separate from the User account
├── reviews/             post-event reviews (only once a booking is confirmed and the event has passed)
└── jobs/                Celery task audit log (DB-only, no API)

The mock Razorpay API (app/payments/mock_controller.py) runs as its own service (mock-razorpay, entrypoint mock_razorpay_app.py) rather than living inside the main app. POST /v1/bookings and the async payment flow make real outbound HTTP calls to it (order creation, webhook delivery - Razorpay auto-captures by default, so there's no separate capture call; see decisions.md #27) - if it lived in the same process as the API, that self-call would deadlock a single-worker gunicorn (the one worker would be both the caller and the callee). Running it as a separate service also just mirrors reality: the real Razorpay is a separate company's servers, never the same process as your app.

Deployment

Live at https://eventbooking.mridulabs.dev - Swagger UI, Flower (Basic Auth protected).

• Infrastructure: a single AWS EC2 instance (t3.micro, sized from measured Docker resource usage rather than guessed - see decisions.md), with an Elastic IP so the address survives stop/start.
• All 6 services (app, worker, flower, db, redis, mock-razorpay) run via the same docker-compose.yml as local dev - no managed DB/cache, no orchestrator, deliberately: this is a low-traffic personal project, not a production system at scale.
• nginx reverse-proxies :80/:443 → app:5000, and /flower/ → flower:5555 (Flower itself never has a public port open - nginx reaches it over the instance's own loopback interface).
• TLS via Let's Encrypt (certbot), auto-configured HTTP→HTTPS redirect.
• DNS via Cloudflare (eventbooking.mridulabs.dev → the instance's Elastic IP).
• Migrations are applied manually (docker compose run --rm app flask --app run db upgrade) as part of each deploy - same explicit, non-automatic step as local dev (see Database migrations below).

Running it

cp .env.example .env.local   # fill in real values
docker compose up --build -d db redis mock-razorpay
docker compose run --rm app flask --app run db upgrade   # explicit, manual - see below
docker compose up --build

This starts app (API, port 5000), worker (Celery), mock-razorpay (the mocked gateway, internal only - no host port), flower (Celery monitoring, port 5555), db (Postgres), and redis.

Database migrations

Everything runs through docker compose - there's no local Python environment for this project.

# after changing a model: generate a new migration (bind-mounts migrations/ so the
# generated file lands on your host filesystem, not just inside the container - this
# mount is scoped to this one-off command, not a standing volume in docker-compose.yml)
docker compose run --rm --volume "$(pwd)/migrations:/app/migrations" app flask --app run db migrate -m "description"

# apply it - a separate, manual, explicit step, deliberately NOT wired into the
# app service's boot command: upgrading is tied to whether a new migration exists,
# not to the app process's lifecycle, so it shouldn't fire on every container start
docker compose run --rm app flask --app run db upgrade

API Docs

Once running, the OpenAPI spec is auto-generated from the Pydantic schemas - no hand-maintained spec to drift out of sync:

• Swagger UI: /apidoc/swagger/
• ReDoc: /apidoc/redoc/
• Raw spec: /apidoc/openapi.json

Endpoints

All endpoints are versioned under /v1 (added after the initial demo video was recorded - the video shows unversioned paths, e.g. /auth/register instead of /v1/users; the underlying behavior is unchanged).

Operational endpoints (unversioned - infrastructure concerns, not part of the resource API):

Two more endpoints exist as throwaway stand-ins for Razorpay's own servers, deliberately excluded from the docs above (and not versioned - they mimic Razorpay's own URL shape, not this API's) since they aren't part of this API - they run on the separate mock-razorpay service, not app: - POST /mock/razorpay/orders (HTTP Basic Auth via RAZORPAY_KEY_ID/KEY_SECRET) - mocks Razorpay's real Orders API, called by POST /v1/bookings to get an order_id before creating the booking's payment record - POST /mock/razorpay/simulate-webhook (x-api-key protected) - mocks Razorpay auto-capturing a payment and delivering the resulting webhook back to app's real /v1/webhooks/razorpay

Testing

docker compose run --rm test

Runs via a dedicated test service (Dockerfile.test, profile-gated so docker compose up never starts it) - no local Python needed. It deliberately doesn't use .env.local, so it falls back to tests/conftest.py's own isolated defaults (sqlite in-memory, fresh every run) instead of hitting the real dev Postgres/Redis.

Unit tests use pytest with parametrization, plus in-memory fake repositories for isolating service-layer logic from the database.