Epic: FastStack v1 — Hybrid FastAPI Framework #1

Overview

Build FastStack v1: a hybrid FastAPI framework with a pip-installable runtime core (faststack_core) and a CLI generator (faststack). Users can scaffold complete async FastAPI projects from YAML entity definitions, with protocol-based testing, structured logging, and RFC 7807 errors out of the box.

Design plan: docs/design/fastapi-generator-plan.md
Architecture decisions: docs/architecture/adr/
Implementation plan: docs/implementation/v1-implementation-plan.md

Phases

Phase 0: Project Bootstrap ✅ (#2)

• pyproject.toml — package config, dependencies, CLI entry point, ruff/black/pytest config
• Package directory structure with __init__.py files
• Makefile — ~15 targets (install, test, lint, format, typecheck, check, clean, help)
• Root conftest.py — pytest-asyncio configuration
• Verify: poetry install, make check, python -c "import faststack_core"

Phase 1: Runtime Core ✅ (#4)

• faststack_core/base/entity.py — Entity, AuditedEntity, SoftDeleteEntity, FullAuditedEntity
• faststack_core/base/repository.py — Repository Protocol + SqlAlchemyRepository (async)
• faststack_core/base/service.py — CrudService with 6 async lifecycle hooks
• faststack_core/base/permissions.py — @require_permission, @require_role
• faststack_core/exceptions/domain.py — DomainError hierarchy (8 exception classes)
• faststack_core/exceptions/handlers.py — RFC 7807 global exception handlers
• faststack_core/database/session.py — DatabaseConfig, async get_db
• Tests for all core components (69 tests)
• Verify: make check passes

Phase 2: Logging & Middleware ✅ (#5)

• faststack_core/logging/ — Structured logger (dual-format), sensitive data masking, config
• faststack_core/middleware/ — Correlation ID, request logging, security headers
• faststack_core/health/endpoints.py — /health + /health/detailed
• faststack_core/settings/config.py — FastStackConfig dataclass
• faststack_core/setup.py — setup_app(app, config) one-call registration
• Tests for logging, middleware, health, setup (100 total)
• Verify: smoke test with minimal FastAPI app + make check

Phase 3: CLI Foundation + YAML Parser ✅ (#6)

• cli/__init__.py — Click CLI group
• cli/field_mappings.py — 13-type YAML → SQLAlchemy → Pydantic mapping
• cli/yaml_parser.py — Entity/field definitions, relationship resolution
• cli/model_introspector.py — AST-based model reader (highest risk item)
• Tests for parser, field mappings, introspector (246 total)
• Verify: parse example YAML, introspect a model, verify round-trip

Phase 4: Project Scaffolding (faststack init) ✅ (#7)

• 8 project templates: pyproject.toml.j2, main.py.j2, config.py.j2, Dockerfile.j2, docker-compose.yml.j2, alembic.ini.j2, alembic_env.py.j2, conftest.py.j2
• cli/cmd_init.py — faststack init command
• Tests: scaffold to temp dir, verify structure, verify generated Python parses (281 total)
• Verify: faststack init test-project produces valid project

Phase 5: Simple Mode Entity Templates ✅ (#8)

• 9 entity templates: model.py.j2, schema.py.j2, repository.py.j2, service.py.j2, router.py.j2, factory.py.j2, fake_repository.py.j2, test_unit_service.py.j2, test_integration.py.j2
• Tests: render all templates for User/Post/Category/Tag, verify valid Python, cross-template consistency (337 total)
• Verify: generated code passes ruff check + black --check, fake satisfies Protocol

Phase 6: Entity CLI Commands ✅ (#9)

• cli/cmd_add_entity.py — add-entity (--fields, --from-yaml, --update)
• cli/cmd_generate.py — regenerate REGENERATABLE files, skip PRESERVED, hash tracking
• cli/cmd_migrate.py — Alembic wrapper (generate/upgrade/downgrade)
• cli/cmd_list.py — entity status + staleness detection
• Registry generation (dependencies.py, router registration, integration conftest)
• Tests for all CLI commands (393 total, 90% coverage)
• Verify: full end-to-end workflow (init → add entity → generate → list), 20-entity rag_modulo project generates 160 passing tests

Quality Gates ✅ (#16)

• pytest-cov with 85% coverage threshold
• Pre-commit hooks (ruff, black, AST check, debug statements, private key detection)
• Pytest markers (unit, integration, e2e)
• GitHub Actions CI (lint.yml, pre-commit.yml, ci.yml, dependency-review.yml)
• Makefile with ContextForge-style help system

Key Constraints (from ADRs)

• Async-first (ADR-001): All repos/services use AsyncSession
• Protocol-based repos (ADR-002): In-memory fakes for testing, no mocks
• YAML input, model source of truth (ADR-003): AST introspection for regeneration
• RFC 7807 errors (ADR-004): Domain exception hierarchy
• Lifecycle hooks (ADR-005): 6 async hooks on CrudService
• PRESERVED vs REGENERATABLE (ADR-006): Repos are PRESERVED, schemas/fakes are REGENERATABLE
• v1 = simple mode only (ADR-007): DDD/auth/events/frontend deferred to v2
• Makefile for DX (ADR-008): Single entry point for dev commands