rangonroyutsab/flight-promotion-service

Purpose and Entry Points

Flight Promotion Service is a Django microservice that selects eligible US flights, generates Gemini marketing copy, persists promotion payloads in MinIO, and serves them over REST. Runtime entry points are manage.py, the HTTP ASGI/WSGI project configuration in config/asgi.py and config/wsgi.py, and management commands in promotions/management/commands/generate_flight_promotions.py and promotions/management/commands/run_scheduler.py.

Django Application and HTTP Boundary

config/urls.py mounts the promotions API; promotions/api/urls.py defines health, promotion-list/date, and promotion-detail routes. promotions/api/views.py is the request boundary: it delegates reads to application services rather than exposing storage details. Response and exception shaping are centralized in promotions/api/responses.py and promotions/api/exceptions.py.

Generation Pipeline

promotions/services/generation_pipeline.py orchestrates a daily run: check idempotency, query candidate flights, generate copy, store payloads, create audit records, and publish a manifest. The pipeline is invoked manually by generate_flight_promotions.py or on a midnight schedule by run_scheduler.py. A prior daily manifest terminates the run; deterministic UUIDs based on date and flight identity make reruns stable.

External Source and AI Adapters

Flight eligibility is queried through promotions/clients/elasticsearch_client.py against Elasticsearch’s sample flight index. Promotion prompts are assembled in promotions/services/prompt_builder.py, then sent through the Gemini REST adapter at promotions/clients/ai/gemini.py. Pydantic contracts, especially promotions/schemas/ai_response.py, validate structured AI responses before they enter durable storage.

Storage, Manifest, and Audit Boundary

Generated promotion JSON is the source of served content and is stored through promotions/clients/minio_client.py and promotions/services/promotion_storage.py. promotions/services/manifest_service.py writes/reads a per-run manifest that acts as the daily publication pointer and idempotency marker. Schema contracts for these objects reside in promotions/schemas/promotion_object.py, promotions/schemas/run_manifest.py, and promotions/schemas/latest_pointer.py. PostgreSQL holds Django model audit/pointer data in promotions/models.py, rather than full promotion content.

Read Path

List/detail requests resolve the relevant manifest and promotion object keys, then retrieve JSON from MinIO. promotions/services/promotion_reader.py coordinates this path; promotions/services/concurrent_object_reader.py parallelizes list-object reads with a bounded thread pool, limiting MinIO latency exposure. The API returns validated promotion representations rather than querying PostgreSQL for content.

Runtime Infrastructure

Docker Compose provisions the Django web process, dedicated scheduler process, PostgreSQL 16, Elasticsearch 8.15, and S3-compatible MinIO; deployment topology is defined in docker-compose.yml. Initialization scripts create the MinIO bucket and load Kibana/Elasticsearch sample data: docker/minio-init/create-bucket.sh and docker/kibana-init/install-sample-data.sh. Django settings in config/settings.py supply environment-driven service endpoints, credentials, retry limits, timezone, and AI-provider selection.