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.

Template FastAPI Documentation

Welcome to the comprehensive documentation for the template-fastapi application. This documentation covers the complete feature set, API endpoints, and operational guides.

Quick Start

Prerequisites

  • Python 3.10 or higher
  • uv package manager
  • Azure account with appropriate service subscriptions

Installation and Setup

# Clone and install
git clone https://github.com/ks6088ts-labs/template-fastapi.git
cd template-fastapi
make install-deps-dev

# Configure environment
cp .env.template .env
# Edit .env with your Azure service credentials

# Start development server
make dev

The application will be available at http://localhost:8000 with interactive API documentation at http://localhost:8000/docs.

Docker Setup

See ks6088ts/template-fastapi for Docker images.

# Configure environment
cp .env.template .env
# Edit .env with your Azure service credentials

# Run Docker container
docker run --rm -p 8000:8000 \
  --volume "$PWD/.env:/app/.env" \
  ks6088ts/template-fastapi:latest

Architecture Overview

For detailed architecture information, see:

Service Guides

Items Management

Basic CRUD operations with Azure CosmosDB backend.

# Run FastAPI server
make dev

# Test endpoints
curl -X GET "http://localhost:8000/items/"
curl -X GET "http://localhost:8000/items/search/?q=hammer"

File Management

Upload, download, and manage files using Azure Blob Storage.

# Upload file via CLI
uv run python scripts/files.py upload-file ./path/to/file.txt

# List files
uv run python scripts/files.py list-files

# Download file
uv run python scripts/files.py download-file "file.txt"

Restaurant Discovery

Geospatial search and vector-based restaurant recommendations.

# Import sample data
uv run python scripts/foodies_restaurants.py import-data --csv-file ./datasets/foodies_restaurants.csv

# Search by text
uv run python scripts/foodies_restaurants.py search --query "sushi"

# Find nearby restaurants
uv run python scripts/foodies_restaurants.py find-nearby --latitude 35.681167 --longitude 139.767052 --distance 5.0

Speech Transcription

Batch audio transcription using Azure AI Speech.

# Create transcription job
AUDIO_URL="https://your-storage.blob.core.windows.net/audio/file.wav?sas-token"
uv run python scripts/speeches.py create-transcription "$AUDIO_URL" --locale "ja-JP"

# Monitor job status
uv run python scripts/speeches.py get-transcription "$JOB_ID"

# Get results when completed
uv run python scripts/speeches.py get-transcription-result "https://result-url"

Agent Systems

LangGraph Agents

AI agents with custom tools for calculations, time queries, and web search.

# Interactive chat
uv run python scripts/agents_langgraph.py interactive

# Single query
uv run python scripts/agents_langgraph.py chat "京都の今の時間から12時間後は何時？"

# Available tools
uv run python scripts/agents_langgraph.py tools

# API endpoint
curl -X GET "http://localhost:8000/agents/langgraph/tools"

Azure AI Foundry Agents

Enterprise-grade conversational AI with thread management.

# Create agent
uv run python scripts/agents_azure_ai_foundry.py create-agent "Research Assistant" --instructions "You are a helpful research assistant."

# List agents
uv run python scripts/agents_azure_ai_foundry.py list-agents

# Chat with agent
uv run python scripts/agents_azure_ai_foundry.py chat <agent_id> "Tell me about machine learning trends"

Real-time Chat

WebSocket-based chat interface with agent integration.

# Start server
make dev

# Access chat interface
open http://localhost:8000/chats/

Microsoft Graph Integration

Access SharePoint sites and user profiles.

# Get access token
uv run python scripts/microsoft_graphs.py get-access-token

# Get user profile
uv run python scripts/microsoft_graphs.py get-my-profile --access-token $ACCESS_TOKEN

# Access SharePoint sites
uv run python scripts/microsoft_graphs.py get-sites --site-id $SITE_ID --access-token $ACCESS_TOKEN

Development and Testing

Running Tests

# All tests
make test

# Specific test file
pytest tests/test_api.py -v

# With coverage
pytest --cov=template_fastapi

Code Quality

# Format code
make format

# Lint code
make lint

# Run all CI checks
make ci-test

Docker Development

# Build and run with Docker
make docker-build
make docker-run

# Full Docker CI pipeline
make ci-test-docker

Monitoring and Observability

Logging Configuration

Configure log levels via environment variables:

# In .env file
LOG_LEVEL=DEBUG  # DEBUG, INFO, WARNING, ERROR, CRITICAL

Application Insights

Enable telemetry by setting:

APPLICATIONINSIGHTS_CONNECTION_STRING="your-connection-string"

Health Monitoring

# Check service health
curl -X GET "http://localhost:8000/demos/roll_dice"  # Should return 1-6
curl -X GET "http://localhost:8000/agents/langgraph/health"

Azure Services Configuration

Required Azure Services

  • Azure CosmosDB: Document database for items and restaurants
  • Azure Blob Storage: File storage and management
  • Azure OpenAI: Language models for AI features
  • Azure AI Speech: Batch transcription services
  • Azure AI Foundry: Enterprise AI agent platform
  • Application Insights: Monitoring and telemetry

Service Setup Tips

# Enable CosmosDB local auth (development only)
az resource update \
  --resource-group $RESOURCE_GROUP \
  --name $COSMOS_DB_ACCOUNT_NAME \
  --resource-type "Microsoft.DocumentDB/databaseAccounts" \
  --set properties.disableLocalAuth=false

Deployment

Azure Functions

Deploy as serverless functions:

# Export requirements
uv export --format requirements-txt --no-dev --no-hashes --output-file requirements.txt

# Deploy with Azure Functions Core Tools
func azure functionapp publish <function-app-name>

Container Deployment

# Build production image
docker build -t template-fastapi .

# Run with environment file
docker run --env-file .env -p 8000:8000 template-fastapi

References