Backend Documentation

The Financial Data Extractor backend is built with FastAPI, providing a high-performance, async API for managing companies, documents, financial statement extractions, and compiled statements.

Architecture Overview

The backend uses a layered architecture with clear separation of concerns:

API Layer - REST API endpoints with automatic exception handling
Service Layer - Business logic with service exceptions
Repository Layer - Database operations with repository pattern
Database Layer - PostgreSQL with connection pooling

Key Features

Layered Exception Handling: Database → Service → API exception translation
Repository Pattern: Clean separation of database operations
Dependency Injection: FastAPI’s dependency system for services and repositories
Connection Pooling: Async connection pool management
Comprehensive Testing: Unit tests (124) and integration tests (4) with testcontainers

Documentation

Architecture

Backend Architecture - Connection pool management, dependency injection, repository pattern, and exception handling
Backend Testing - pytest setup, unit tests, integration tests with testcontainers

Database Schema - Table structures and relationships
Database Migrations - Alembic migration workflows
API Reference - Complete REST API documentation

Technology Stack

FastAPI - High-performance async web framework
PostgreSQL - Primary database with JSONB support
SQLAlchemy - ORM for database models
Alembic - Database migrations
pytest - Testing framework
testcontainers - Integration testing with real databases

Quick Start

⚠️ IMPORTANT: Configure environment variables first!

cd backend
# Copy .env.example to .env and configure required values (especially OPEN_ROUTER_API_KEY)
cp .env.example .env
# Edit .env with your configuration

# Install dependencies
make install-dev

# Run database migrations
make migrate

# Start the server
make run

See the Backend README and Installation Guide for detailed setup instructions.

Backend Architecture