Specx Component Architecture

specx Scope Architecture

Use this skill before broad structural changes or when a feature crosses more than one layer. Read references/boundaries.md for the full rules.

Boundary Model

• core//: application behavior and contracts. Inner packages are

capabilities/, dtos/, entities, exceptions/, gateways/, repositories/, services/, and use_cases/.

• core//infrastructure/: scope-owned external IO adapters such as

SQLAlchemy repositories, Redis stores, HTTP clients, file storage, and queues. Inner core packages must not import it.

• Scoped specx foundation packages: packaged base classes under

specx.core.foundation, specx.delivery.foundation, and specx.infrastructure.foundation. Every non-foundation source class must inherit an explicit packaged base directly or through a project-local base; local bases explicitly inherit the packaged or framework base they extend.

• foundation/: optional project-local extension point for base definitions

only: real project-local base categories or stateful framework bases that must not be shared globally, such as a SQLAlchemy declarative base.

• delivery/: runnable framework apps, controllers, schemas, auth

dependencies, request parsing, response serialization, HTTP error translation, app lifecycle managers, and delivery-only services.

• infrastructure/: app-wide technical resources such as SQLAlchemy session

factories, logging, telemetry, and external client factories.

• Runtime logging lives in top-level infrastructure/logging. Configure it

once with a BaseConfigurator; do not inject logging.Logger.

• shared/: tiny stable cross-scope primitives. It is not a dumping ground.
• ioc/: diwire container creation and explicit bindings.

Decision Rules

• Use a use case for an externally meaningful action.
• Use a service for focused reusable business/application behavior.
• Use a capability for one small replaceable injectable ability that is

narrower than a service.

• Name every service class with a Service suffix.
• Name direct concrete BaseCapability subclasses with a Capability suffix.
• Do not call small collaborators services by default.
• Core services inherit BasePureService, BaseReadService, or

BaseEffectService; do not add or use a generic BaseService.

• Do not add base_ prefixes to project-local foundation module filenames.

Class names stay prefixed, for example clock.py defines BaseClock.

• Use gateway ports under core//gateways/ for outbound business

capabilities such as OpenAI summaries, payments, email, queues, and external APIs. Gateway ports inherit BaseGateway, declare external effects, and do not return entities.

• Put concrete gateway implementations under

core//infrastructure//.

• Use packaged scoped specx foundation bases before adding project-local bases.
• Do not create an empty local foundation/ package.
• Add a project-local foundation base only when a real project-local base

category exists or a stateful framework base must own project-local state, such as SQLAlchemy MetaData.

• Use a port or ABC only for a real external boundary or multiple

implementations.

• Use one delivery controller per scoped set of use cases.
• Use core/health when readiness checks any required external dependency or

probe policy is reusable across delivery layers. Keep a simple framework-specific liveness probe in delivery, and do not invent core probe services and use cases solely to satisfy the layer diagram.

• When core/health is justified, keep framework route/status/header mapping

in delivery and technical checks behind gateway adapters.

• Keep request/response schemas in top-level delivery/. Keep use-case DTOs in

core//dtos/.

• Prefer @dataclass(frozen=True, kw_only=True, slots=True) for commands,

queries, DTOs, entities, and other core data classes unless the user asks for another model type. Keep Pydantic at delivery schemas and settings edges.

• Use BaseStrEnum for limited known application value sets instead of plain

str or Literal[...].

• When creating or reshaping a repo, keep root AGENTS.md architecture

guidance aligned with these boundaries.

• Define each use-case input as a same-file Command or Query: commands are

state-changing, queries are read-only, and even empty inputs are explicit.

• Keep commands and queries independent from DTOs. They inherit BaseCommand

or BaseQuery, not BaseDTO, and live beside the use case that consumes them.

• Use cases return DTOs, not entities.
• Persistence use cases inject UnitOfWorkManager for transactional work and

open the active UoW inside execute(...). They do not inject repositories, SQLAlchemy sessions/engines/session factories, or concrete infrastructure adapters directly.

• Services may receive an active UoW from a use case, but services must not

open UoW scopes or own commit/rollback.

• Give every project source class a docstring that explains scope and includes

a concrete Example:; the packaged rule checks abstract ports, local bases, enums, and errors as well as concrete behavior classes.

• Keep controller-only helpers such as auth and rate limiting in delivery/.
• Keep FastAPI lifespan ownership in delivery/fastapi/lifecycle.py. The

lifecycle releases app-owned resources and closes the DI container on shutdown.

• Keep SQL and external API calls in scope infrastructure adapters.
• Classes that actually emit logs create a private stdlib logger in

__post_init__ using the full module plus class name. Do not add logger fields to DTOs, entities, commands, queries, or classes with no log records.

• Logs should describe important application events and failures without

secrets, credentials, request bodies, full external URLs, or infrastructure topology.

• Do not create bare classes without explicit bases.
• Packaged framework-neutral guardrails run by default when select is

omitted. New generated projects use select = ["ALL"], which enables every rule whose required project surface exists. Projects with a narrower base selection enable technology families explicitly, for example extend-select = ["fastapi"]. Do not copy FastAPI paths or guidance into a project that uses another delivery technology.

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/boundaries.md - layout, import rules, naming, and architecture

test targets.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: maksimzayats
• Source: maksimzayats/specx
• License: MIT
• Homepage: https://specx.dev

Install and usage instructions live in the source repository linked above.