Skip to content

Web Server Component

The Web Server component handles HTTP requests, API endpoints, and web traffic for your Aegis Stack application.

Current Implementation: FastAPI

FastAPI is the current web server implementation, chosen for its high performance, automatic API documentation, and excellent async support.

Why FastAPI?

  • High Performance: Built on Starlette and Pydantic, one of the fastest Python frameworks
  • Async Native: Perfect match for Aegis Stack's async-first architecture
  • Type Safety: Automatic validation and serialization using Python type hints
  • Auto Documentation: Generates OpenAPI/Swagger docs automatically
  • Modern: Designed for Python 3.6+ with modern language features

How It's Integrated

FastAPI is set up in the app/backend/ directory:

# app/backend/main.py
from fastapi import FastAPI
from fastapi.middleware.cors import CORSMiddleware

def create_backend_app(app: FastAPI) -> FastAPI:
    """Configure FastAPI app with all backend concerns"""

    # Basic CORS
    app.add_middleware(
        CORSMiddleware,
        allow_origins=["*"],
        allow_credentials=True,
        allow_methods=["*"],
        allow_headers=["*"],
    )

    # Include all routes
    include_routers(app)

    return app

Adding API Routes

Routes are organized in app/backend/api/:

# app/backend/api/health.py
from fastapi import APIRouter

router = APIRouter()

@router.get("/health")
async def health_check():
    return {"status": "healthy", "service": "aegis-stack"}

Register routes in app/backend/api/routing.py:

from app.backend.api import health

def include_routers(app: FastAPI) -> None:
    app.include_router(health.router, tags=["health"])

Configuration

FastAPI is configured through the integration layer and runs with:

  • CORS enabled for cross-origin requests
  • Automatic JSON serialization
  • Built-in validation using Pydantic models
  • Exception handling for clean error responses

Development Features

  • Auto-reload during development
  • Interactive docs at /docs (Swagger UI)
  • Alternative docs at /redoc
  • OpenAPI schema at /openapi.json

Integration with Aegis Stack

FastAPI aligns perfectly with Aegis Stack's core principles:

  • Python-First: Pure Python with excellent type safety
  • Async-Native: Built for async/await from the ground up
  • Developer Experience: Automatic validation, serialization, and documentation
  • Production Ready: High performance with excellent error handling

Performance Characteristics

FastAPI provides:

  • Async request handling for high concurrency
  • Automatic validation without performance penalty
  • JSON serialization optimized with orjson under the hood
  • Middleware support for cross-cutting concerns

FastAPI's async-first design allows Aegis Stack to handle thousands of concurrent connections efficiently while maintaining type safety and developer productivity.