Skip to content

v2.0.0

Latest
Latest

Choose a tag to compare

View all tags
@tomasanchez tomasanchez released this 31 May 22:44
v2.0.0
084a287
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode.

Cosmic FastAPI v2.0.0

Cosmic FastAPI v2.0.0 turns the project into a reusable, agent-friendly FastAPI standard inspired by Architecture Patterns with Python. It preserves the book's domain-first dependency direction while adopting FastAPI, Pydantic 2, SQLAlchemy 2, Alembic, uv, Ruff, Pyrefly, and pytest.

This is a major release because the template structure and extension workflow changed substantially. New projects receive explicit architecture guidance, a modern persistence baseline, CQRS read paths, and a tested user-registration example that demonstrates how the pieces fit together.

Highlights

  • Added a complete modern Cosmic Python baseline: aggregate roots, repositories, unit of work, command handlers, domain events, message bus, composition root, and CQRS read models.
  • Added SQLAlchemy 2 persistence adapters and Alembic migrations.
  • Added immutable Pydantic command and event schemas with idiomatic snake_case Python fields and camelCase JSON contracts for HTTP, CLI, and future message-queue adapters.
  • Added ADR-driven agent guidance with compact decision pruning through make adr-context and validation through make adr-check.
  • Added a Cosmic Python coverage matrix that distinguishes built-in patterns from conditional extensions such as optimistic locking, transactional outbox, broker adapters, idempotency storage, and sagas.
  • Hardened registration consistency: timezone-aware timestamps and race-safe duplicate-email handling preserve the HTTP 409 contract.

Breaking Changes

  • Domain API schemas moved from src/template/domain/schemas.py to src/template/entrypoint/schemas.py.

  • Monitor response models moved out of domain events into entrypoint schemas.

  • New relational persistence requires applying Alembic migrations before normal local startup:

    make migrate

  • SQLAlchemy and Alembic are now runtime dependencies.

  • The redundant local template.utils.formatting.to_camel helper was removed. Import pydantic.alias_generators.to_camel directly.

Added

Modern Cosmic Python Architecture

  • Plain-Python User aggregate root and UserSettings value object.
  • Frozen Pydantic Command, Event, and Message bases.
  • RegisterUser command and UserRegistered domain event.
  • Generic in-process message bus with command dispatch, domain-event draining, and explicit unsupported-message rejection.
  • Application handlers, repository port, abstract unit of work, and explicit bootstrap composition root.
  • Thin FastAPI registration and lookup entrypoints.

Persistence and CQRS

  • SQLAlchemy 2 typed declarative records under adapters.
  • SQLAlchemy repository and unit-of-work adapters.
  • Alembic configuration and initial users-table migration.
  • Database settings with migrate-first defaults and opt-in schema creation for isolated demos and tests.
  • Purpose-built CQRS UserReadModel, reader port, and SQLAlchemy projection adapter so read-only endpoints do not rehydrate write aggregates by habit.

Architecture Guidance for Agents

  • Root AGENTS.md with Python style, GIVEN/WHEN/THEN testing conventions, architecture workflow, and Conventional Commits guidance.
  • ADR registry and lifecycle validation.
  • scripts/prune_decisions.py plus make adr-context and make adr-check.
  • ADRs covering modern Cosmic Python defaults, framework boundaries, SQLAlchemy adapters, explicit composition, async policy, tooling, Pyrefly, Conventional Commits, ADR lifecycle, Pydantic messages, camel-case JSON contracts, aggregate boundaries, and CQRS reads.
  • docs/cosmic-python-coverage.md pattern coverage matrix.

Tooling and Test Coverage

  • Pyrefly static type checking.
  • Expanded Ruff checks and formatting across source, tests, scripts, and migrations.
  • Updated pre-commit Ruff hooks.
  • Migration, persistence, unit-of-work, aggregate, command-schema, message-bus, CQRS, bootstrap, and FastAPI end-to-end tests.
  • 100% application coverage gate.

Changed

  • Refreshed README branding and terminology.
  • Documented database environment variables and migrate-first local startup.
  • Standardized JSON schema serialization on camelCase using Pydantic's built-in alias generator.
  • Added local ignores for IDE metadata and generated reports.
  • Normalized .dockerignore formatting.

Fixed

  • Configured created_at as timezone-aware in both SQLAlchemy metadata and the Alembic migration.
  • Moved transport-agnostic registration validation into the command schema so HTTP, CLI, and broker callers share the same contract.
  • Added nested command-settings serialization with camel-case JSON aliases.
  • Translated SQLAlchemy IntegrityError into an application-level conflict so concurrent duplicate registrations continue to return HTTP 409.
  • Updated the Uvicorn host default to satisfy static typing.

Removed

  • Removed domain-layer API response schemas.
  • Removed monitor schemas from domain events.
  • Removed the local camel-case formatting helper and its redundant tests.

Validation

  • uv run pre-commit run --all-files
  • make lint
  • make cover
  • make adr-check
  • git diff --check

Application coverage remains at 100%.

Full Commit Changelog

  • a98229a docs: update README with aligned branding and terminology changes
  • 592d97b docs: update README with aligned branding and terminology changes
  • 67d2cad Merge remote-tracking branch origin/develop into develop
  • 61a6ab2 Merge pull request #3 from tomasanchez/develop
  • 22c6561 chore: run Ruff format
  • 02c20d5 chore(Makefile): update Ruff tasks for format and lint commands
  • 740c1ea feat(architecture): add cosmic agent standard and ADR pruner
  • 630db51 chore(tooling): refresh hooks and local ignores
  • 3c0c981 feat(architecture): complete modern cosmic patterns
  • cd9370d docs(architecture): define cosmic agent standard
  • 54530b1 chore: normalize dockerignore newline
  • c8e0db9 refactor(formatting): remove redundant camel case helper
  • 6740a5d fix(architecture): address registration consistency review
  • 084a287 Merge pull request #5 from tomasanchez/develop

Links

Assets 2
Loading