Technical Blueprints & Operational Contracts

import uuid
import time
import logging
from typing import Callable
from fastapi import FastAPI, Request, Response, status
from fastapi.middleware.cors import CORSMiddleware
from pythonjsonlogger import jsonlogger

# 1. Structured JSON Logging Setup
logger = logging.getLogger("ai_product_api")
log_handler = logging.StreamHandler()
formatter = jsonlogger.JsonFormatter(
    fmt="%(asctime)s %(levelname)s %(name)s %(correlation_id)s %(message)s"
)
log_handler.setFormatter(formatter)
logger.addHandler(log_handler)
logger.setLevel(logging.INFO)

app = FastAPI(
    title="AI Product Core Engine",
    version="1.0.0",
    docs_url="/docs",
    redoc_url="/redoc"
)

# 2. CORS Security Configuration
app.add_middleware(
    CORSMiddleware,
    allow_origins=["https://yourproduct.com", "http://localhost:3000"],
    allow_credentials=True,
    allow_methods=["GET", "POST", "PUT", "DELETE", "OPTIONS"],
    allow_headers=["*"],
)

# 3. Correlation ID & Latency Logging Middleware
@app.middleware("http")
async def correlation_and_metrics_middleware(request: Request, call_next: Callable) -> Response:
    correlation_id = request.headers.get("X-Correlation-ID", str(uuid.uuid4()))
    request.state.correlation_id = correlation_id
    start_time = time.perf_counter()
    
    response = await call_next(request)
    
    duration_ms = round((time.perf_counter() - start_time) * 1000, 2)
    response.headers["X-Correlation-ID"] = correlation_id
    
    logger.info(
        "HTTP Request Processed",
        extra={
            "correlation_id": correlation_id,
            "method": request.method,
            "path": request.url.path,
            "status_code": response.status_code,
            "duration_ms": duration_ms,
            "client_ip": request.client.host if request.client else "unknown"
        }
    )
    return response

# 4. Health & Readiness Probes
@app.get("/healthz", status_code=status.HTTP_200_OK)
async def health_check():
    """Liveness probe for container orchestrators (Railway / Kubernetes / Fly)."""
    return {"status": "healthy", "service": "ai-product-core"}

@app.get("/readyz", status_code=status.HTTP_200_OK)
async def readiness_check():
    """Readiness probe verifying DB and cache connectivity."""
    # Add DB / Redis ping checks here
    return {"status": "ready", "database": "connected", "cache": "connected"}