# Stack Knowledge

> Project technology stack patterns for FastAPI + PostgreSQL + SQLAlchemy + Alembic + PyTorch + pandas

- Skill: `zachjxyz/stack-knowledge-2` (Agent Skill)
- Install (CLI): `npx skillmds@latest add zachjxyz/stack-knowledge-2`
- Raw SKILL.md: https://api.skillmd.com/api/skills/zachjxyz/stack-knowledge-2/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Data & Analytics
- Author: zachjxyz (https://skillmd.com/u/zachjxyz)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/zachjxyz/stack-knowledge-2

---


# Stack Knowledge

This skill provides stack-specific patterns for agents making architectural and implementation decisions.

## FastAPI

- Async route handlers by default — use `async def` for all endpoints
- Dependency injection with `Depends()` for database sessions, auth, shared logic
- Pydantic V2 models for all request/response schemas — never return raw dicts
- Use `lifespan` context manager for startup/shutdown (DB connections, ML model loading)
- Router organization: `src/api/routes/` with one router per domain
- Error handling: `HTTPException` for expected errors, exception handlers for unexpected
- Consistent error shape: `{ "error": str, "message": str, "details": dict }`
- Background tasks with `BackgroundTasks` for non-blocking operations

## PostgreSQL + SQLAlchemy

- SQLAlchemy 2.0 style — use `select()`, `insert()`, `update()`, `delete()` statements
- Async engine with `create_async_engine()` and `async_sessionmaker()`
- Connection string via `DATABASE_URL` env var
- Models in `src/models/` with one file per entity
- Use `mapped_column()` with explicit types — no implicit column inference
- Index every column used in WHERE, JOIN, or ORDER BY
- Relationship loading: use `selectinload()` for collections, `joinedload()` for single relations
- Session management: request-scoped sessions via `Depends(get_db)`

## Alembic Migrations

- Config in `alembic.ini`, env in `alembic/env.py`
- Development: `alembic revision --autogenerate -m "description"`
- Production: manually reviewed migrations, never autogenerate blindly
- Always test migrations both up and down (rollback)
- One migration per logical change — don't batch unrelated schema changes

## PyTorch / ML

- Models in `src/models/ml/` — separate from SQLAlchemy ORM models
- Training scripts in `src/training/`
- Inference endpoints load models at startup via lifespan, not per-request
- Reproducibility: set seeds (`torch.manual_seed`, `numpy.random.seed`), log hyperparameters
- Model versioning: save checkpoints with metadata (epoch, metrics, config)
- Data pipelines in `src/pipelines/` — pandas for ETL, torch DataLoaders for training

## pandas / Data Processing

- Use `pandas` for data loading, cleaning, transformation
- Prefer vectorized operations over iterrows — never loop over DataFrame rows
- Type hints with `pd.DataFrame` and column schemas documented
- For large datasets: chunked reading with `chunksize`, or use `polars` for performance-critical paths
- CSV/Parquet I/O: explicit dtypes on read, compression on write

## Testing (pytest)

- Test structure mirrors source: `tests/api/`, `tests/models/`, `tests/pipelines/`
- Use `httpx.AsyncClient` with `ASGITransport` for API tests
- Fixtures in `conftest.py` for database sessions, test client, sample data
- Use `pytest-asyncio` for async test support
- Factory fixtures for test data — never hard-code test objects across files
- ML tests: test model forward pass shapes, loss convergence on tiny datasets

## Project Structure

```
src/
├── api/
│   ├── routes/          # FastAPI routers (one per domain)
│   ├── deps.py          # Shared dependencies (get_db, get_current_user)
│   └── middleware.py     # CORS, auth, logging middleware
├── models/
│   ├── db/              # SQLAlchemy ORM models
│   └── ml/              # PyTorch model definitions
├── schemas/             # Pydantic request/response schemas
├── pipelines/           # Data processing pipelines
├── training/            # ML training scripts
├── services/            # Business logic layer
├── config.py            # Settings via pydantic-settings
└── main.py              # FastAPI app factory
alembic/                 # Database migrations
tests/                   # Mirror of src/ structure
```