maksimzayats/specx/specx-add-infrastructure-adapter

specx Add Infrastructure Adapter

Use this skill whenever code talks to external systems. Read references/adapter.md before writing adapters.

Workflow

1. Define or reuse a repository under repositories/ for owned persistence.

Repository ports inherit BaseRepository and mark required methods with @abstractmethod.

1. Define or reuse a gateway under gateways/ for outbound business

capabilities to external systems such as OpenAI, payments, email, queues, or external HTTP APIs. Gateway ports inherit BaseGateway, mark required methods with @abstractmethod, declare external effects, and do not return entities.

1. Put concrete implementations under

core/<scope>/infrastructure/<technology>/.

1. Inject external clients, session factories, Redis clients, SDK clients, or

project-owned client factories. Do not hide client construction inside business methods. Generated HTTP adapters use httpx2, imported from the httpx2 namespace; do not generate new legacy httpx imports.

1. A bounded short-lived client factory may stay beside its scope adapter. Put

every app-owned pooled client factory or wrapper under top-level infrastructure/<technology>/, even with only one current consumer.

1. Give long-lived app-owned infrastructure resources an explicit async

close() method; FastAPI lifecycle owns calling it on shutdown.

1. Keep technical query/request code in infrastructure.
2. Repositories may return entities. Gateways must not return entities; return

DTOs, primitives, enums, or explicit result objects. Do not return ORM models or SDK response objects to core.

1. Translate low-level exceptions into core exceptions only when callers need to

handle them. Catch narrow driver or SDK exceptions, preserve the cause, and never expose raw provider messages, SQL, parameters, bodies, or URLs.

1. For transactional persistence, implement an active UnitOfWork and a

UnitOfWorkManager; register the manager, not repositories, active UoWs, or UoW providers for use-case injection.

1. Register adapter bindings in private _register_dependencies(...) inside

ioc/container.py. Register every technical resource once at its owner boundary and close that same app-scoped instance from lifecycle.

1. Add focused integration tests only when the adapter has meaningful

project-owned behavior to protect; do not add generic CRUD or upstream library tests just because an adapter file exists.

1. For SQLAlchemy adapters, add or update Alembic migrations with

$specx-sqlalchemy-migrations.

Logging is top-level runtime infrastructure, not a core-scope adapter. Put stdlib logging setup in infrastructure/logging/configurator.py with a LoggingConfigurator that inherits BaseConfigurator; do not create gateway ports or injected logger bindings for it.

For /readyz, implement required dependency checks as core/health gateway adapters, for example core/health/infrastructure/sqlalchemy/readiness_check_gateway.py, and bind them to ReadinessCheckGateway in ioc/container.py. Bound every dependency check with a short application timeout and return only a non-sensitive core status.

Code Style

Use blank lines as logical separators in all code. Keep related statements together, but separate independent setup, action, assertion, response, branch, and transformation groups so long blocks stay readable.

References

• references/adapter.md - adapter layout, port binding, SQLAlchemy/UoW, Redis,

HTTP client, migration, and test patterns.