python-primitives-architecture

Primitives-first architecture in Python separates pure domain dataclasses from services and interfaces to maximize testability. You need it when building CLI, SDK, or Web components that require strict layer boundaries and robust type safety.

Structure your Python project by dividing it into distinct PRIMITIVES, SERVICES, and INTERFACES layers. Implement dependency injection using Protocols, allowing slim interfaces to call services that operate on pure dataclasses.

Handle errors in clean Python architecture by using a Result-based pattern within your service layer. Services return Result objects instead of raising exceptions, keeping domain primitives pure and interface boundaries intact.

Yes, primitives-first design works for CLI, SDK, and Web interfaces. By enforcing pure dataclasses and protocol-based dependency injection, the underlying services remain decoupled from the delivery mechanism, ensuring high reusability.

Start by creating a Python package with a documented layout, implement an immutable primitive using dataclasses, build a service that returns a Result, and finally expose it through a thin interface using Protocols for dependency injection.

You should avoid using pure dataclasses for domain primitives if your application does not require strict separation between domain logic and interface layers, as the overhead of Protocols and Result-based handling may complicate simple scripts.