<<<<<<< HEAD

Lyftr AI — Backend Assignment

Containerized FastAPI service that ingests WhatsApp-like webhook messages exactly once, exposes query & analytics APIs, emits structured logs, and exports Prometheus-style metrics.

---

🚀 Features

• POST /webhook
  • HMAC-SHA256 signature verification
  • Exactly-once ingestion (DB-level idempotency)
  • Proper HTTP semantics (401 / 422 / 200)
• GET /messages
  • Pagination (limit, offset)
  • Filtering (from, since, q)
  • Deterministic ordering
• GET /stats
  • Aggregate analytics
• GET /metrics
  • Prometheus-compatible counters
• Health probes
  • /health/live
  • /health/ready
• Structured JSON logging
  • One log line per request
• Docker + Docker Compose
  • SQLite with persistent volume
  • 12-factor environment configuration

---

🛠 Tech Stack

• Python 3.12
• FastAPI
• Pydantic v2
• SQLite
• Docker & Docker Compose
• Prometheus-style metrics (text exposition)

---

▶️ Running with Docker Compose (Recommended)

1️⃣ Set environment variable

export WEBHOOK_SECRET="devsecret"

=======
#Lyftr AI – Backend Assignment

#Overview

This project is a FastAPI-based backend service that ingests inbound WhatsApp-like webhook messages,
ensures idempotent storage, exposes paginated APIs, provides analytics and metrics, and follows
production-ready backend practices.

#How to Run

Prerequisites: Docker, Docker Compose

#Start the Service:

docker compose up --build

#Service URL:

http://localhost:8000

#API Endpoints

POST /webhook
Ingests inbound WhatsApp-like messages exactly once and validates authenticity using HMAC-SHA256.

GET /messages
Returns stored messages with pagination and optional filters.

GET /stats
Returns aggregated analytics over stored messages.

GET /metrics
Exposes Prometheus-compatible application metrics.

#Design Decisions

HMAC Verification:
Webhook authenticity is verified using HMAC-SHA256 computed from raw request body bytes and compared
using a constant-time comparison to prevent timing attacks. Invalid signatures return HTTP 401.

Pagination:
The /messages endpoint uses limit-offset pagination. Responses include total, limit, and offset. Results are
deterministically ordered by timestamp and message_id.

Stats and Metrics:
The /stats endpoint aggregates message counts, sender distribution, and first/last timestamps using SQL
aggregation. The /metrics endpoint exposes Prometheus-compatible counters for HTTP and webhook events.

#Health Checks
/health/live verifies the process is running.
/health/ready verifies database connectivity and configuration readiness.

#Logging
All requests emit structured JSON logs including request ID, latency, status code, and webhook processing results
where applicable.

#Setup Used
VS Code, Docker, Docker Compose, and occasional ChatGPT assistance.
>>>>>>> c6651228aac96b0b7dd24c1de2b381f544bb2d08