"""
=============================================================================
FASTAPI MAIN APPLICATION
=============================================================================

This is the entry point for the FastAPI backend.

FastAPI Features:
- Automatic API documentation (Swagger UI at /docs)
- Request validation with Pydantic
- Async support for high performance
- Easy dependency injection

To run the server:
    uvicorn main:app --reload --port 8000

Or use the provided run script:
    python run.py
"""

from fastapi import FastAPI
from fastapi.middleware.cors import CORSMiddleware
from contextlib import asynccontextmanager

# Import configuration
from config import settings

# Import routers (API endpoints grouped by feature)
from routers import ai, projects, health


# =============================================================================
# APPLICATION LIFECYCLE
# =============================================================================

@asynccontextmanager
async def lifespan(app: FastAPI):
    """
    Manage application lifecycle events.
    
    This runs code on startup (before yield) and shutdown (after yield).
    Great for:
    - Initializing database connections
    - Loading ML models
    - Setting up caches
    """
    # Startup
    print("🚀 Starting Hack Nation Backend...")
    print(f"📍 Environment: {settings.ENVIRONMENT}")
    print(f"🤖 AI Provider: {settings.AI_PROVIDER} ({settings.AI_MODEL})")
    
    yield  # Application runs here
    
    # Shutdown
    print("👋 Shutting down...")


# =============================================================================
# CREATE APPLICATION
# =============================================================================

app = FastAPI(
    title="Hack Nation API",
    description="""
    Backend API for Hack Nation hackathon template.
    
    Features:
    - AI text generation (OpenAI / Anthropic)
    - Supabase database integration
    - User authentication
    """,
    version="1.0.0",
    lifespan=lifespan,
)


# =============================================================================
# MIDDLEWARE
# =============================================================================

# CORS - Allow frontend to call API
app.add_middleware(
    CORSMiddleware,
    allow_origins=settings.cors_origins_list,  # Origins allowed to call API
    allow_credentials=True,                     # Allow cookies/auth headers
    allow_methods=["*"],                        # Allow all HTTP methods
    allow_headers=["*"],                        # Allow all headers
)


# =============================================================================
# ROUTERS
# =============================================================================

# Include routers with prefixes
# Each router handles a specific feature area
app.include_router(
    health.router,
    prefix="/api",
    tags=["Health"],
)

app.include_router(
    ai.router,
    prefix="/api/ai",
    tags=["AI"],
)

app.include_router(
    projects.router,
    prefix="/api/projects",
    tags=["Projects"],
)


# =============================================================================
# ROOT ENDPOINT
# =============================================================================

@app.get("/")
async def root():
    """
    Root endpoint - useful for health checks and API info.
    """
    return {
        "name": "Hack Nation API",
        "version": "1.0.0",
        "docs": "/docs",
        "health": "/api/health",
    }