FastAPI Microservice Suite

A production-like microservice suite demonstrating how to build a scalable retrieval and ingestion platform for AI data.

Architecture Overview

This project consists of three main services:

1. Auth Service - User registration, login, JWT issuance, and RBAC
2. File Ingestion Service - File upload, text extraction, chunking, and embedding generation
3. Vector Search Service - k-NN search using Pinecone vector database

Project Structure

├── main.py                 # FastAPI application entry point
├── shared/                 # Shared utilities and models
│   ├── config.py          # Configuration management
│   ├── database.py        # Database connection
│   ├── models.py          # SQLModel/Pydantic schemas
│   ├── security.py        # JWT and password utilities
│   └── logging_config.py  # Structured logging
├── services/
│   ├── auth/              # Authentication service
│   ├── ingest/            # File ingestion service
│   └── vector/            # Vector search service
├── tests/                 # Test suite
├── infra/                 # Docker configuration
└── docs/                  # Documentation

Quick Start

Prerequisites

• Python 3.11+
• PostgreSQL (or use Docker)
• Pinecone API key (optional, for vector search)
• OpenAI API key (optional, for embeddings)

Local Development

1. Copy environment configuration:

cp .env.example .env

2. Configure your environment variables in .env

3. Install dependencies:

pip install -r requirements.txt

4. Run the application:

uvicorn main:app --host 0.0.0.0 --port 5000 --reload

Using Docker

cd infra
docker-compose up --build

API Documentation

Once running, visit:

• Swagger UI: http://localhost:5000/docs
• ReDoc: http://localhost:5000/redoc

API Endpoints

Authentication

Method	Endpoint	Description
POST	/api/v1/auth/register	Register new user
POST	/api/v1/auth/login	Login and get JWT
GET	/api/v1/auth/me	Get current user info

File Ingestion

Method	Endpoint	Description
POST	/api/v1/ingest/upload	Upload a file
POST	/api/v1/ingest/process/{id}	Process uploaded file
GET	/api/v1/ingest/documents	List user's documents
DELETE	/api/v1/ingest/documents/{id}	Delete a document

Vector Search

Method	Endpoint	Description
POST	/api/v1/search/query	Search vectors
GET	/api/v1/search/stats	Get index statistics

Testing

Run the test suite:

pytest -v

Run with coverage:

pytest --cov=. --cov-report=html

Environment Variables

Variable	Description	Required
DATABASE_URL	PostgreSQL connection string	Yes
SESSION_SECRET	JWT signing secret	Yes
PINECONE_API_KEY	Pinecone API key	Optional
PINECONE_INDEX_NAME	Pinecone index name	Optional
OPENAI_API_KEY	OpenAI API key for embeddings	Optional

Security Considerations

• JWT tokens expire after 30 minutes
• Passwords are hashed using bcrypt
• API keys are loaded from environment variables
• Input validation using Pydantic schemas
• File size limits enforced (10MB default)