Skip to content
OpenAgentSkill
Browsing is open · Catalog captured 2026-11-21 · Automatic updates and account services are paused.
Design & UI

specx-component-architecture

Design or review specx core scope boundaries in Python services. Use when deciding where code belongs across packaged scoped foundation bases, optional local foundation extensions, `core/`, capabilities, delivery, infrastructure, `shared/`, and `ioc`; when adding guardrails or splitting use cases, services, DTOs, schemas, ports, and adapters.

maksimzayats · AI review on file

Installation

Read the source and dependencies before running a command. Copying does not install or execute anything.

npx skills add maksimzayats/specx --skill specx-component-architecture

About this skill


name: specx-component-architecture description: Design or review specx core scope boundaries in Python services. Use when deciding where code belongs across packaged scoped foundation bases, optional local foundation extensions, core/, capabilities, delivery, infrastructure, shared/, and ioc; when adding guardrails or splitting use cases, services, DTOs, schemas, ports, and adapters.

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/<scope>/: application behavior and contracts. Inner packages are capabilities/, dtos/, entities, exceptions/, gateways/, repositories/, services/, and use_cases/.
  • core/<scope>/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/<scope>/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/<scope>/infrastructure/<technology>/.
  • 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/<scope>/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 `__pos
Read the complete source ↗