architecture-for-apps

Architecture for ArchiPy Apps

Use this when building applications that depend on the archipy package (not when maintaining ArchiPy itself).

Live concepts: https://syntaxarc.github.io/ArchiPy/getting-started/concepts/

Layer Map

your_app/
├── configs/          # BaseConfig subclasses, DI containers
├── models/           # Entities, DTOs, errors, types — data structures only
│   └── dtos/{domain}/
│       ├── domain/v{n}/   # Versioned — cross service boundary
│       └── repository/    # Internal — never versioned
├── repositories/
│   └── {domain}/
│       ├── adapters/              # Domain wrappers around ArchiPy adapters
│       └── {domain}_repository.py # Orchestrate adapters; map to DTOs
├── logics/
│   └── {domain}/         # Use-case / unit-of-work boundaries
└── services/
    └── {domain}/v{n}/    # Transport (HTTP/gRPC routers), versioned

Optional app-local helpers (prefer archipy.helpers first): helpers/{utils,decorators,interceptors}/.

Call Flow

services → logics (atomic UoW) → repositories → adapters → ArchiPy

Plugin shorthand @atomic means a real *_sqlalchemy_atomic_decorator — there is no decorator named atomic.

Layer Rules

Layer details live in the matching using-archipy-*.mdc / config-and-di.mdc / testing-bdd-for-apps.mdc rules when those files are open. This always-on rule keeps only the global map:

• models/ — data only (no I/O, no business rules).
• repositories/ — domain data access; adapters under repositories/{domain}/adapters/; no cross-domain repo calls; map driver errors with raise ... from e.
• logics/ — business rules + UoW (*_sqlalchemy_atomic_decorator); may call other logics; never other domains' repositories; no FastAPI/gRPC.
• services/ — thin transport; versioned v{n}/; no UoW / business rules.
• helpers/ — pure only; prefer ArchiPy; no adapter construction at module level.
• configs/ — extend BaseConfig; set_global once; no secrets in code.