Tech11 Backend API

A FastAPI-based backend server built with modern Python tooling and best practices.

Features

• 🚀 FastAPI - Modern, fast web framework for building APIs
• 📦 uv - Ultra-fast Python package manager
• 🧪 pytest - Testing framework with coverage reporting
• 🎨 Code Quality - Black, isort, and Ruff for formatting and linting
• 🔄 Hot Reload - Development server with automatic reloading
• 📊 API Documentation - Automatic OpenAPI/Swagger documentation

Prerequisites

• Python 3.12 or higher
• uv package manager

Installing uv

Search in Internet!

Installing poe the poet

Serath in Internet!

Quick Start

1. Clone the Repository

git clone <your-repo-url>
cd tech11-be

2. Install Dependencies

uv sync

3. Set Up Database

# Apply database migrations
uv run alembic upgrade head

4. Run the Development Server

poe run

The server will start at http://localhost:8000 with hot reload enabled.

Available Endpoints

API Endpoints

• GET / - Welcome message
• GET /items/{item_id} - Get item by ID with optional query parameter

Documentation

• Swagger UI: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc
• OpenAPI Schema: http://localhost:8000/openapi.json

Development

Project Structure

tech11-be/
├── app/
│   └── main.py          # FastAPI application
├── pyproject.toml       # Project configuration and dependencies
├── uv.lock             # Locked dependency versions
└── README.md           # This file

Available Commands

The project uses poethepoet for task management:

# Run the development server
poe run

# Run tests with coverage
poe test

# Run tests in watch mode
poe watch-test

# Format and lint code
poe lint

Code Quality

The project includes several tools for maintaining code quality:

• Black - Code formatting
• isort - Import sorting
• Ruff - Fast Python linter
• pytest - Testing framework
• pytest-cov - Coverage reporting

Running Tests

# Run all tests
poe test

# Run tests in watch mode (reruns on file changes)
uv run poe watch-test

# Run tests manually
uv run pytest

Code Formatting and Linting

# Format and lint all code
 poe lint

Environment Variables

Create a .env file in the project root with the following configuration:

# Environment Configuration
ENVIRONMENT=development

# Database Configuration
DATABASE_URL=sqlite:///./app.db

# Security
SECRET_KEY=supersecret-change-in-production

# Project
PROJECT_NAME=FastAPI Tech11 Backend

# Azure OpenAI Configuration
AOAI_ENDPOINT=https://your-resource-name.openai.azure.com/
AOAI_API_KEY=your-api-key-here
AOAI_DEPLOY_GPT4O_MINI=gpt-4o-mini
AOAI_DEPLOY_GPT4O=gpt-4o
AOAI_DEPLOY_EMBED_3_LARGE=text-embedding-3-large
AOAI_DEPLOY_EMBED_3_SMALL=text-embedding-3-small
AOAI_DEPLOY_EMBED_ADA=text-embedding-ada-002

# AWS S3 Configuration (Required for PDF downloads)
S3_BUCKET=your-s3-bucket-name
AWS_ACCESS_KEY=your-aws-access-key
AWS_SECRET_KEY=your-aws-secret-key

Important:

• The S3 configuration is required for the research PDF download functionality (/research_download endpoint). If these variables are not set, you will receive a validation error.
• When using Docker Compose, all variables from .env are automatically loaded into the container via the env_file directive.

Production Deployment

Using uvicorn

# Install production dependencies
uv sync --no-dev

# Run production server
uv run uvicorn app.main:app --host 0.0.0.0 --port 8000

Using Docker (Optional)

Create a Dockerfile:

FROM python:3.12-slim

WORKDIR /app

# Install uv
COPY --from=ghcr.io/astral-sh/uv:latest /uv /bin/uv

# Copy project files
COPY pyproject.toml uv.lock ./
COPY app/ ./app/

# Install dependencies
RUN uv sync --frozen --no-dev

# Expose port
EXPOSE 8000

# Run the application
CMD ["uv", "run", "uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]

Contributing

1. Clone the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Run tests and linting (uv run poe test && uv run poe lint)
5. Commit your changes (git commit -m 'Add some amazing feature')
6. Push to the branch (git push origin feature/amazing-feature)
7. Open a Pull Request

Support

If you encounter any issues or have questions, please open an issue on GitHub or contact the development team.