Skip to content

[!CAUTION] These design documents are generated by AI and may not be fully accurate or complete. They are intended to provide a starting point for understanding the system architecture and design patterns used in the template-fastapi application.

Internal Design Specification

Architecture Overview

The template-fastapi application follows a layered architecture pattern with clear separation of concerns, enabling maintainability, testability, and scalability.

System Architecture

graph TB
    Client[Client Applications]
    LB[Load Balancer]

    subgraph "FastAPI Application"
        App[app.py - Main Application]
        Router[Router Layer]
        Logic[Business Logic Layer]
        Repo[Repository Layer]
        Models[Data Models]
    end

    subgraph "Azure Cloud Services"
        CosmosDB[(Azure CosmosDB)]
        BlobStorage[(Azure Blob Storage)]
        OpenAI[Azure OpenAI]
        Speech[Azure AI Speech]
        AIFoundry[Azure AI Foundry]
        AppInsights[Application Insights]
    end

    Client --> LB
    LB --> App
    App --> Router
    Router --> Logic
    Logic --> Repo
    Repo --> Models

    Repo --> CosmosDB
    Repo --> BlobStorage
    Repo --> OpenAI
    Repo --> Speech
    Repo --> AIFoundry
    App --> AppInsights

Package Structure and Responsibilities

Core Application (template_fastapi/)

graph LR
    subgraph "Application Core"
        App[app.py]
        Core[core.py]
        Settings[settings/]
        OpenTel[opentelemetry.py]
    end

    subgraph "API Layer"
        Routers[routers/]
        Items[items.py]
        Files[files.py]
        Foodies[foodies.py]
        Speeches[speeches.py]
        Chats[chats.py]
        Demos[demos.py]
        Agents[agents/]
    end

    subgraph "Data Layer"
        Models[models/]
        Repositories[repositories/]
        Internals[internals/]
    end

    subgraph "Infrastructure"
        Templates[templates/]
        Static[static files]
    end

    App --> Routers
    App --> Settings
    App --> OpenTel
    Routers --> Models
    Routers --> Repositories

Package Responsibilities

app.py - Application Bootstrap

  • FastAPI application initialization
  • Router registration and configuration
  • Middleware setup (CORS, logging, monitoring)
  • Azure Application Insights integration
  • Telemetry and observability configuration

routers/ - API Endpoint Handlers

  • Purpose: HTTP request routing and response handling
  • Responsibilities:
  • Request validation using Pydantic models
  • HTTP status code management
  • Error handling and exception transformation
  • Business logic delegation to repositories
  • Response formatting

repositories/ - Data Access Layer

  • Purpose: External service integration and data persistence
  • Responsibilities:
  • Azure service client management
  • Data transformation between external APIs and internal models
  • Connection pooling and retry logic
  • Service-specific error handling

models/ - Data Models

  • Purpose: Data structure definitions and validation
  • Responsibilities:
  • Pydantic model definitions for request/response
  • Data validation rules and constraints
  • Serialization/deserialization logic
  • Type safety enforcement

settings/ - Configuration Management

  • Purpose: Environment-based configuration
  • Responsibilities:
  • Environment variable loading
  • Service connection configuration
  • Feature flag management
  • Logging configuration

Service Communication Flow

Request Processing Flow

sequenceDiagram
    participant Client
    participant Router
    participant Repository
    participant Azure
    participant Logger

    Client->>Router: HTTP Request
    Router->>Logger: Log request start
    Router->>Router: Validate request data
    Router->>Repository: Call business method
    Repository->>Azure: External service call
    Azure-->>Repository: Service response
    Repository->>Repository: Transform data
    Repository-->>Router: Return result
    Router->>Logger: Log request completion
    Router-->>Client: HTTP Response

Error Handling Flow

sequenceDiagram
    participant Client
    participant Router
    participant Repository
    participant Azure
    participant Logger

    Client->>Router: HTTP Request
    Router->>Repository: Call method
    Repository->>Azure: Service call
    Azure-->>Repository: Service error
    Repository->>Logger: Log error details
    Repository->>Repository: Transform to application error
    Repository-->>Router: Raise HTTPException
    Router->>Logger: Log error response
    Router-->>Client: Error response (4xx/5xx)

Agent System Architecture

LangGraph Agent Flow

flowchart TD
    Request[User Request] --> LangRouter[LangGraph Router]
    LangRouter --> ToolSelector[Tool Selection]

    ToolSelector --> Calculator[Calculator Tool]
    ToolSelector --> TimeQuery[Time Query Tool]
    ToolSelector --> WebSearch[Web Search Tool]

    Calculator --> MathExecution[Math Expression Eval]
    TimeQuery --> TimeAPI[System Time API]
    WebSearch --> SearchAPI[External Search API]

    MathExecution --> Response[Formatted Response]
    TimeAPI --> Response
    SearchAPI --> Response

    Response --> LangRouter
    LangRouter --> Client[Client Response]

Azure AI Foundry Agent Flow

sequenceDiagram
    participant Client
    participant Router
    participant Repository
    participant AIFoundry
    participant Thread

    Client->>Router: Create Agent Request
    Router->>Repository: Create Agent
    Repository->>AIFoundry: POST /agents
    AIFoundry-->>Repository: Agent Created
    Repository-->>Router: Agent Response
    Router-->>Client: Agent Details

    Client->>Router: Chat Request
    Router->>Repository: Chat with Agent
    Repository->>Thread: Retrieve/Create Thread
    Repository->>AIFoundry: POST /threads/{id}/messages
    AIFoundry-->>Repository: Message Response
    Repository-->>Router: Chat Response
    Router-->>Client: AI Response

Data Models and Relationships

Core Entity Relationships

erDiagram
    Item ||--o{ ItemSearch : searchable
    Restaurant ||--o{ RestaurantLocation : "has location"
    Restaurant ||--o{ RestaurantEmbedding : "has embedding"

    File ||--|| BlobMetadata : "stored as"

    TranscriptionJob ||--o{ TranscriptionFile : "produces"
    TranscriptionJob ||--|| AudioSource : "processes"

    Agent ||--o{ Thread : "manages"
    Thread ||--o{ Message : "contains"

    ChatSession ||--o{ WebSocketConnection : "maintains"

    Item {
        string id PK
        string name
        string description
        float price
        float tax
    }

    Restaurant {
        string id PK
        string name
        string description
        string cuisine_type
        float latitude
        float longitude
        float rating
    }

    File {
        string name PK
        int size
        string content_type
        datetime last_modified
        string url
    }

    Agent {
        string id PK
        string name
        string model
        string instructions
        datetime created_at
    }

    Thread {
        string id PK
        string agent_id FK
        datetime created_at
        json metadata
    }

Service Integration Patterns

Repository Pattern Implementation

classDiagram
    class BaseRepository {
        <<abstract>>
        +logger: Logger
        +settings: Settings
        +initialize_client()
        +handle_errors()
    }

    class ItemRepository {
        +cosmos_client: CosmosClient
        +list_items(limit, offset)
        +get_item(id)
        +create_item(item)
        +update_item(id, item)
        +delete_item(id)
        +search_items(query)
    }

    class FileRepository {
        +blob_client: BlobServiceClient
        +list_files(prefix)
        +upload_file(name, data)
        +download_file(name)
        +delete_file(name)
        +get_file_info(name)
    }

    class RestaurantRepository {
        +cosmos_client: CosmosClient
        +openai_client: OpenAIClient
        +list_restaurants(limit, offset)
        +search_restaurants(query, k)
        +find_nearby_restaurants(lat, lng, radius)
    }

    BaseRepository <|-- ItemRepository
    BaseRepository <|-- FileRepository
    BaseRepository <|-- RestaurantRepository

Configuration Management Pattern

classDiagram
    class BaseSettings {
        <<abstract>>
        +env_prefix: str
        +validate_settings()
    }

    class AzureOpenAISettings {
        +endpoint: str
        +api_key: str
        +api_version: str
        +model_chat: str
        +model_embedding: str
    }

    class AzureCosmosDBSettings {
        +connection_string: str
        +database_name: str
        +container_name: str
    }

    class LoggingSettings {
        +log_level: str
        +configure_logging()
        +get_logger(name)
    }

    BaseSettings <|-- AzureOpenAISettings
    BaseSettings <|-- AzureCosmosDBSettings
    BaseSettings <|-- LoggingSettings

Security and Monitoring Integration

Logging and Telemetry Flow

flowchart TD
    App[FastAPI Application] --> LogConfig[Logging Configuration]
    LogConfig --> StructuredLogs[Structured Logging]

    App --> OpenTelemetry[OpenTelemetry SDK]
    OpenTelemetry --> Traces[Distributed Tracing]
    OpenTelemetry --> Metrics[Custom Metrics]

    StructuredLogs --> AppInsights[Application Insights]
    Traces --> AppInsights
    Metrics --> AppInsights

    AppInsights --> Dashboard[Azure Dashboard]
    AppInsights --> Alerts[Alert Rules]

    LogConfig --> Console[Console Output]
    LogConfig --> FileOutput[File Output]

Environment-based Configuration

flowchart LR
    EnvTemplate[.env.template] --> LocalEnv[.env]
    EnvTemplate --> ProdEnv[Production Environment]

    LocalEnv --> DevConfig[Development Settings]
    ProdEnv --> ProdConfig[Production Settings]

    DevConfig --> LocalServices[Local/Mock Services]
    ProdConfig --> AzureServices[Azure Cloud Services]

    DevConfig --> DebugLogging[DEBUG Logging]
    ProdConfig --> InfoLogging[INFO Logging]

Performance and Scalability Considerations

Caching Strategy

graph TB
    Request[Client Request] --> FastAPI[FastAPI Router]
    FastAPI --> Cache{Cache Hit?}

    Cache -->|Yes| CacheReturn[Return Cached Response]
    Cache -->|No| Repository[Repository Layer]

    Repository --> Azure[Azure Services]
    Azure --> Repository
    Repository --> CacheStore[Store in Cache]
    CacheStore --> Response[Return Response]

    CacheReturn --> Client[Client Response]
    Response --> Client

Connection Pooling

graph LR
    App[Application Startup] --> PoolInit[Initialize Connection Pools]

    PoolInit --> CosmosPool[CosmosDB Pool]
    PoolInit --> BlobPool[Blob Storage Pool]
    PoolInit --> OpenAIPool[OpenAI Pool]

    Request[Request Handler] --> PoolManager[Connection Pool Manager]
    PoolManager --> CosmosPool
    PoolManager --> BlobPool
    PoolManager --> OpenAIPool

    CosmosPool --> CosmosOps[Database Operations]
    BlobPool --> BlobOps[Storage Operations]
    OpenAIPool --> AIOps[AI Operations]

Testing Strategy

Test Architecture

graph TB
    subgraph "Test Layers"
        UnitTests[Unit Tests]
        IntegrationTests[Integration Tests]
        E2ETests[End-to-End Tests]
    end

    subgraph "Test Utilities"
        Fixtures[Pytest Fixtures]
        Mocks[Mock Services]
        TestClient[FastAPI TestClient]
    end

    subgraph "Coverage Areas"
        RouterTests[Router Layer Tests]
        RepoTests[Repository Tests]
        ModelTests[Model Validation Tests]
        CoreTests[Core Logic Tests]
    end

    UnitTests --> RouterTests
    UnitTests --> RepoTests
    UnitTests --> ModelTests
    UnitTests --> CoreTests

    Fixtures --> UnitTests
    Mocks --> UnitTests
    TestClient --> IntegrationTests

This internal design specification provides a comprehensive view of the application's architecture, data flow, and component interactions, enabling developers to understand and extend the system effectively.