Hexagonal Architecture/Clean Architecture

Use case: for application that reads data from API, from SQL, performs some logic (validating data, parsing parts of data from json response), and saves data and modifies via another API.

This structure separates your business logic from the technical details, making your code testable and easy to maintain.

Layer	Responsibility	Content
Application	Business logic and use cases. The "Orchestrator." Coordinates the flow of data. This layer acts as the conductor. It doesn't care how the SQL works; it just calls the methods defined in the Domain interfaces.	Use Cases, Services.
Domain	Contains business rules and data structures.	Models, Entities, Logic, Interfaces, Repository
Infrastructure	Integration with external systems (DB, Network, Disk, API, etc)	SQL Alchemy, Requests/HTTP clients, File IO.

Repository

Data mapping can be done in repository, that is the reason of repository. A Repository is a design pattern that acts as a "mediator" between your domain logic and the data source (SQL database, NoSQL, or even a CSV file).

The Repository has two parts: The Interface (Domain Layer): Defines what the repository can do (e.g., get_by_id, save). This keeps your business logic independent of the database. The Implementation (Infrastructure Layer): Contains the actual SQL or ORM code (SQLAlchemy, Django ORM, etc.).

project_root/
│
├── domain/
│   ├── models.py          # Data classes (e.g., User, Transaction)
│   └── interfaces.py      # Abstract definitions (Protocols)
│
├── application/
│   └── sync_service.py    # The logic that links everything together
│
├── infrastructure/
│   ├── database.py        # SQL implementation
│   ├── api_client.py      # Requests/Httpx implementation
│   └── repositories.py    # Concrete implementations of interfaces
│
└── main.py                # Entry point (Dependency Injection)

Example:

Layer	Analogy	Responsibility
Application	The Chef	Follows the recipe. It asks for flour, gets a bowl, mixes it, and puts it in the oven. It never sees the plastic bag the flour came in.
Domain	The Recipe	Defines what a "Cake" is (ingredients, proportions). It doesn't care where the flour comes from.
Infrastructure	The Supplier	Goes to the store, buys a bag of flour (JSON), and unpacks it into a bowl (Domain Model) before handing it over.
		Action: Parsing/Mapping → Infrastructure Layer. * Why? Because if the API changes a field name from `email` to `user_email`, you only change one file in Infrastructure. Your business logic stays the same. Action: Validation (Formatting) → Infrastructure Layer. • Why? Checking if the API gave you a valid integer for an ID is a technical check. Action: Validation (Business Rules) → Domain Layer. • Why? Checking if a user is allowed to buy a product is a business rule, not a technical one. Action: Workflow (Step 1, then Step 2) → Application Layer. • Why? It coordinates the "Use Case" (e.g., "The process of updating a user profile").

Layer	Service	Responsibilities
`Application`	`AccountExportService`	- Validates the account exists- Queries the DB for all transactions belonging to the account- Passes the data to Infrastructure to generate an XML file- Returns the XML file to the Presentation layer
`Domain`	`TaxCalculationService`	- Based on applicable tax rates and account funds will calculate and return the amount of tax that needs to be applied- Doesn’t update the state of any entities.
`Infrastructure`	`EmailService`	- Sends Emails via a 3rd party service such as SendGrid or Mail Chimp.

Entity and Value object

https://medium.com/@nomannayeem/everything-you-need-to-know-about-domain-driven-design-with-python-microservices-2c2f6556b5b1
Entities: These are objects that have a distinct identity, such as a Customer or an Order. They change over time and have attributes like name, address, or status.
Value Objects: Unlike entities, value objects are defined only by their attributes. For example, a Money object with a currency and amount. They are immutable and interchangeable if they have the same value.
Aggregates: Aggregates are clusters of entities and value objects that are treated as a single unit. They help enforce business rules and maintain consistency. For example, an Order aggregate might contain OrderItems, ensuring all items are processed together.
Repositories: These are responsible for retrieving and storing aggregates. They act as a bridge between the domain and the data layer.

The best architecture to work with external APIs

Infrastructure → application → domain
Crate DTO and repositories