Streaming Service

A lightweight Flask-based streaming catalog API backed by PostgreSQL, designed for both Docker Compose and Kubernetes deployments.

Architecture

The repository is organized around a Kubernetes-native topology that makes the runtime model easy to reason about:

flowchart TD
    NS[Namespace: streaming-service]
    NS --> DEPLOY[Deployment: streaming-api]
    DEPLOY --> HPA[HorizontalPodAutoscaler]
    NS --> STATEFUL[StatefulSet: streaming-db]
    DEPLOY --> NP[NetworkPolicy]
    STATEFUL --> PVC[PersistentVolumeClaim]
    NS --> CM[ConfigMap + Secret]

Loading

Runtime components

• Namespace: isolates the streaming-service workload.
• Deployment: runs the Flask API as a horizontally scalable frontend tier.
• HPA: automatically scales the API pods based on CPU and memory utilization.
• StatefulSet: runs PostgreSQL with stable storage for movie data.
• NetworkPolicy: constrains ingress and egress traffic between the API and database.

Quick start with Docker Compose

Prerequisites

• Docker Desktop or Docker Engine
• Docker Compose v2

Start the stack

docker compose up --build -d

Verify the API

curl http://localhost:5000/health

Expected response:

{
  "status": "healthy",
  "database": "connected"
}

Stop the stack

docker compose down

Example API calls

Create a movie:

curl -X POST http://localhost:5000/api/movies \
  -H "Content-Type: application/json" \
  -d '{
    "code": "MOV1234567",
    "title": "The Matrix",
    "director": "Lana Wachowski",
    "year": 1999,
    "duration": 136,
    "genres": ["Action", "Sci-fi"],
    "language": "English",
    "rating": 8.7,
    "seasons": 0,
    "rental_cost": 3.99
  }'

List movies:

curl http://localhost:5000/api/movies

Search movies:

curl "http://localhost:5000/api/movies/search?q=matrix"

Kubernetes deployment

The Kubernetes manifests live in the yaml directory.

1. Apply namespace, config, and secrets

kubectl apply -f yaml/01-namespace-configmap-secret.yaml

2. Deploy the API and database resources

kubectl apply -f yaml/02-deployment-service.yaml

3. Check rollout status

kubectl get pods -n streaming-service
kubectl get svc -n streaming-service

4. Access the service

The deployment exposes the API through a LoadBalancer service on port 80, mapped to the Flask app on port 5000.

API endpoints

Method	Endpoint	Description	Status
GET	/health	Health check for the API and database connection	200 / 503
GET	/	Service metadata and available routes	200
POST	/api/movies	Create a new movie	201 / 400 / 409
GET	/api/movies	List all movies or fetch one by code using ?code=...	200 / 404
GET	/api/movies/search?q=...	Search movies by code, title, director, genres, or language	200 / 400
PUT	/api/movies/	Update supported movie fields	200 / 400 / 404
DELETE	/api/movies/	Delete a movie by code	200 / 404

Testing

Run the pytest suite:

pytest -q

Project structure

src/           Flask application and SQLAlchemy models
config/        environment-specific config
database/      SQL init scripts for local Postgres
docker/        container build files
yaml/          Kubernetes manifests
tests/         pytest coverage for the API