Technology Stack

This document defines the standard technology stack and versions for backend projects. Adherence to these versions ensures compatibility and stability across the ecosystem.

Versioning & pinning (required; Docker not required)

These standards do not require Docker for local development.

Supported versions (baseline)

Python: 3.12.x (projects may use newer patch versions; do not mix major/minor versions within a repo)
PostgreSQL: 16+ (project may use a managed provider or a locally installed Postgres)

Where versions are pinned (single source of truth)

Projects must make it obvious (to humans and AI agents) where versions are pinned:

Python version (pick one):
- .python-version (recommended), or
- pyproject.toml requires-python
Python dependencies (pick one mechanism; do not introduce a second):
- requirements.txt (pinned), optionally with a separate requirements-dev.txt, or
- pyproject.toml + lock file (e.g., Poetry), or
- pyproject.toml + uv.lock (uv)

Rule: repositories must not have two competing dependency sources (e.g., both Poetry + requirements.txt) unless explicitly documented as a temporary migration in that repo.

Local development without Docker (standard path)

For local dev, projects should assume a non-Docker workflow:

Run Postgres via a local install (e.g., OS package manager) or use a managed/dev database.
Configure connection strings via environment variables (see Security → Data Handling & Secrets).

Core Framework

FastAPI

Modern, high-performance web framework for building APIs.

Async/await support
Automatic OpenAPI documentation
Pydantic validation
Dependency injection
WebSocket support (available when bi-directional messaging is required; prefer SSE for one-way streaming updates)

Uvicorn

ASGI server for running FastAPI applications.

HTTP/1.1 and HTTP/2 support
WebSocket support (capability; not required for typical SSE streaming)
Process management
Production-ready

Database

PostgreSQL

Primary relational database.

ACID compliance
Advanced indexing
JSON support
Full-text search

pgvector

PostgreSQL extension for vector operations.

Vector similarity search
Embedding storage
Cosine similarity
Optimized indexing

SQLAlchemy

Python SQL toolkit and ORM.

Async support
Declarative models
Query builder
Migration support

asyncpg

High-performance PostgreSQL adapter.

Async/await native
Connection pooling
Prepared statements
Type conversions

Alembic

Database migration tool.

Version control for schemas
Up/down migrations
Auto-generation
Multi-environment support

AI and ML

OpenAI

GPT-4o/4.1 model suite.

Plan-aware model selection
Structured outputs
Streaming responses
Function/tool calling support

Pydantic AI

Framework for orchestrating OpenAI agents.

Structured outputs
Tool integration
Retry management
Type-safe responses

TikToken

Token counting for OpenAI models.

Accurate token counting
Cost estimation
Context window management

Data Processing

PyMuPDF

PDF processing library.

PDF parsing
Text extraction
Document analysis

python-docx

Microsoft Word document processing.

DOCX reading
Content extraction
Metadata access

Authentication & Security

PyJWT

JSON Web Token implementation.

Token generation
Token verification
Claims handling

python-jose

JOSE (JWT, JWS, JWE) implementation.

Encryption
Digital signatures
Key management

bcrypt

Password hashing.

Secure hashing
Salt generation
Verification

passlib

Password hashing library.

Multiple algorithms
Context handling
Migration support

bleach

HTML sanitization.

XSS prevention
Tag whitelisting
Attribute filtering

Rate Limiting

slowapi

Rate limiting for FastAPI.

IP-based limiting
User-based limiting
Custom key functions
In-memory storage

External Integrations

Stripe

Payment platform for online checkout, billing, and subscriptions.

Accept one-time payments (cards, wallets)
Manage subscriptions and recurring billing
Generate invoices and handle billing cycles
Sync customers, products, and prices; react to events via webhooks

Google Cloud Storage

Cloud file storage.

Bucket management
File upload/download
Signed URLs
Access control

Google Analytics Admin

Analytics integration.

Event tracking
User properties
Conversion tracking

Resend

Email delivery service.

Transactional emails
Template support
Delivery tracking

ClickSend SMS API

SMS delivery service.

Template-based SMS messages
HTTPS API requests with async httpx
Sender ID configured via environment variables

Data Validation

Pydantic

Data validation and settings management.

Runtime type checking
JSON schema generation
Settings management
Field validation

Pydantic Settings

Configuration management.

Environment variables
Multiple sources
Type conversion
Validation

email-validator

Email address validation.

Syntax validation
DNS checking
Internationalization

phonenumbers

Phone number validation and formatting.

International formats
Carrier detection
Validation

Testing

pytest

Testing framework.

Fixture support
Parameterized tests
Coverage reporting
Plugin ecosystem

pytest-asyncio

Async testing support.

Async fixtures
Event loop management
Async test discovery

HTTPX

Async HTTP client for testing.

Async/sync modes
HTTP/2 support
Request/response mocking

Utilities

aiofiles

Async file operations.

Non-blocking I/O
Context managers
Multiple modes

aiohttp

Async HTTP client/server.

WebSocket support (capability; use when needed)
Client sessions
Server implementation

python-multipart

Multipart form data parsing.

File uploads
Form handling
Streaming support

python-dotenv

Environment variable loading.

.env file support
Variable parsing
Override management

Date & Time

python-dateutil

Date and time utilities.

Parsing
Timezone handling
Relative dates

pytz

Timezone definitions.

IANA timezone database
Conversion utilities
DST handling

Async Utilities

anyio

Async compatibility layer.

Async/await abstractions
Task groups
Cancellation

backoff

Retry with exponential backoff.

Automatic retries
Customizable delays
Exception handling

Logging & Monitoring

logtail-python

Log aggregation service.

Structured logging
Real-time streaming
Search and filtering

rich

Terminal formatting.

Colored output
Tables and trees
Progress bars