# marcosvs98/cqrs-architecture-with-python architecture

> Architecture diagram of the GitHub repository marcosvs98/cqrs-architecture-with-python, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/marcosvs98/cqrs-architecture-with-python
- Repository: https://github.com/marcosvs98/cqrs-architecture-with-python

## Overview

##### Project type and purpose
- This is a backend service built in Python 3.10 on FastAPI, implementing Hexagonal Architecture (Ports & Adapters), CQRS, and Event Sourcing in an event-driven microservices style.
- Its primary bounded context is “Ordering,” with sub-domains for Order, Product, Delivery, Maps, and Payment. The service exposes a REST API to place orders, orchestrates domain logic, stores and publishes events, and interacts with external systems (MongoDB, Redis, Kafka, Google Maps API, PayPal).

##### File structure
- Top-level: configuration files (Dockerfile, docker-compose.yaml, Makefile, pyproject.toml, mypy.ini), scripts for installation and pre-commit, start-up scripts.
- src/app.py and src/bootstrap.py: entry points that wire adapters to ports and launch the FastAPI server.
- src/adapters: concrete implementations of outbound ports (Redis cache, MongoDB, Kafka publisher, Google Maps, PayPal, cost-calculator).
- src/domain: hexagonal core organized by sub-domains (order, product, delivery, maps, payment). Each sub-domain has:
- ports (interfaces for inbound/outbound)
- adapters directory (if any)
- models, entities, value objects, events, exceptions, DTOs
- services (e.g. order_command, order_query, order_mediator)
- repositories and controllers under order.
- src/ports: generic interfaces shared across domains (e.g., cache_interface).
- Infrastructure births in adapters and docker-compose: MongoDB, Redis, Kafka, external APIs.

##### Extract architectural insights from the README
- Pattern: Ports & Adapters (Hexagonal) + CQRS + Event Sourcing
- Bounded Context: Ordering, with domain model defining Ubiquitous Language
- Tech Stack: FastAPI (REST), MongoDB (event store and query store), Redis (cache), Kafka (event bus), external services (Google Maps, PayPal).

##### Final advice
- Be exhaustive but clear: show each sub-domain’s ports and adapters if space allows.
- Essential flows: HTTP → Domain → Persistence → Messaging → External APIs → Cache.
- Iterate: start with high-level blocks (API, Domain, Infra), then drill into details of CQRS and adapters.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "API Layer"
        App["FastAPI App"]:::api
        Boot["Bootstrap"]:::api
    end

    subgraph "Controllers (Inbound Ports)"
        OrderCtrl["OrderController"]:::inport
    end

    subgraph "Application Layer (CQRS)"
        CmdSvc["OrderCommandService"]:::app
        QuerySvc["OrderQueryService"]:::app
        Mediator["OrderMediatorService"]:::app
    end

    subgraph "Domain Core"
        Entities["OrderAggregate & ValueObjects"]:::domain
        Events["OrderEvents"]:::domain
        DTOs["OrderDTOs"]:::domain
        Exc["OrderExceptions"]:::domain
    end

    subgraph "Ports (Interfaces)"
        OrderCmdPort["OrderCommandPort"]:::port
        OrderQryPort["OrderQueryPort"]:::port
        MedPort["OrderMediatorPort"]:::port
        PubPort["EventPublisherPort"]:::port
        AggRepoPort["OrderAggregateRepositoryPort"]:::port
        EventRepoPort["OrderEventStoreRepositoryPort"]:::port
        StoreConnPort["StoreConnectorPort"]:::port
    end

    subgraph "Adapters Layer"
        RedisAd["RedisAdapter"]:::cache
        MongoConnAd["MongoDBConnectorAdapter"]:::storage
        KafkaPubAd["KafkaPublisherAdapter"]:::messaging
        OrderEventPubAd["OrderEventPublisherAdapter"]:::messaging
        CostCalcAd["CostCalculatorAdapter"]:::externalapi
        GoogleMapsAd["GoogleMapsAdapter"]:::externalapi
        PaypalAd["PaypalAdapter"]:::externalapi
        ProductAd["ProductServiceAdapter"]:::externalapi
    end

    subgraph "Repositories (Concrete Implementations)"
        AggRepo["OrderAggregateRepository"]:::storage
        AggCacheRepo["OrderAggregateCacheRepository"]:::cache
        EventStoreRepo["OrderEventStoreRepository"]:::storage
    end

    subgraph "Shared Ports"
        CacheIntf["CacheInterface"]:::port
        EventAdapterIntf["EventAdapterInterface"]:::port
    end

    subgraph "Infrastructure & External Systems"
        MongoDB[(MongoDB)]:::db
        Redis[(Redis)]:::db
        Kafka[(Kafka Cluster)]:::cloud
        GoogleMaps[(Google Maps API)]:::cloud
        Paypal[(PayPal API)]:::cloud
    end

    App --> Boot
    App --> OrderCtrl
    OrderCtrl -->|"placeOrder()"| CmdSvc
    OrderCtrl -->|"getOrder()"| QuerySvc
    CmdSvc -->|"invoke()"| OrderCmdPort
    QuerySvc -->|"invoke()"| OrderQryPort
    OrderCmdPort --> Entities
    OrderQryPort --> Entities
    Entities -->|"emitEvent()"| Events
    Events -->|"storeEvent()"| EventRepoPort
    EventRepoPort --> EventStoreRepo
    EventStoreRepo --> MongoDB
    Events -->|"publishEvent()"| PubPort
    PubPort --> OrderEventPubAd
    OrderEventPubAd --> KafkaPubAd
    KafkaPubAd --> Kafka
    CmdSvc -->|"calculateCost()"| CostCalcAd
    CmdSvc -->|"getRoute()"| GoogleMapsAd
    CmdSvc -->|"chargePayment()"| PaypalAd
    QuerySvc -->|"fetch()"| AggRepoPort
    AggRepoPort --> AggRepo
    AggRepo --> MongoDB
    AggRepoPort --> AggCacheRepo
    AggCacheRepo --> Redis
    RedisAd --> CacheIntf
    AggCacheRepo --> RedisAd

    classDef api fill:#f9f,stroke:#333
    classDef inport fill:#ff9,stroke:#333
    classDef app fill:#bbf,stroke:#333
    classDef domain fill:#ddd,stroke:#333
    classDef port fill:#cfc,stroke:#333
    classDef cache fill:#afa,stroke:#333
    classDef storage fill:#aaf,stroke:#333
    classDef messaging fill:#fea,stroke:#333
    classDef externalapi fill:#fdd,stroke:#333
    classDef db fill:#fcc,stroke:#333,stroke-width:2px
    classDef cloud fill:#cdf,stroke:#333

    click App "https://github.com/marcosvs98/cqrs-architecture-with-python/blob/main/src/app.py"
    click Boot "https://github.com/marcosvs98/cqrs-architecture-with-python/blob/main/src/bootstrap.py"
    click OrderCtrl "https://github.com/marcosvs98/cqrs-architecture-with-python/blob/main/src/domain/order/controllers/order_controller.py"
    click CmdSvc "https://github.com/marcosvs98/cqrs-architecture-with-python/blob/main/src/domain/order/services/order_command.py"
    click QuerySvc "https://github.com/marcosvs98/cqrs-architecture-with-python/blob/main/src/domain/order/services/order_query.py"
    click Mediator "https://github.com/marcosvs98/cqrs-architecture-with-python/blob/main/src/domain/order/services/order_mediator.py"
    click Entities "https://github.com/marcosvs98/cqrs-architecture-with-python/blob/main/src/domain/order/model/entities.py"
    click Entities "https://github.com/marcosvs98/cqrs-architecture-with-python/blob/main/src/domain/order/model/value_objects.py"
    click Events "https://github.com/marcosvs98/cqrs-architecture-with-python/blob/main/src/domain/order/model/events.py"
    click DTOs "https://github.com/marcosvs98/cqrs-architecture-with-python/blob/main/src/domain/order/dtos/order_dtos.py"
    click Exc "https://github.com/marcosvs98/cqrs-architecture-with-python/blob/main/src/domain/order/exceptions/order_exceptions.py"
    click OrderCmdPort "https://github.com/marcosvs98/cqrs-architecture-with-python/blob/main/src/domain/order/ports/order_command_interface.py"
    click OrderQryPort "https://github.com/marcosvs98/cqrs-architecture-with-python/blob/main/src/domain/order/ports/order_query_interface.py"
    click MedPort "https://github.com/marcosvs98/cqrs-architecture-with-python/blob/main/src/domain/order/ports/order_mediator_interface.py"
    click PubPort "https://github.com/marcosvs98/cqrs-architecture-with-python/blob/main/src/domain/order/ports/event_publisher_interface.py"
    click AggRepoPort "https://github.com/marcosvs98/cqrs-architecture-with-python/blob/main/src/domain/order/ports/order_aggregate_repository_interface.py"
    click EventRepoPort "https://github.com/marcosvs98/cqrs-architecture-with-python/blob/main/src/domain/order/ports/order_event_store_repository_interface.py"
    click StoreConnPort "https://github.com/marcosvs98/cqrs-architecture-with-python/blob/main/src/domain/order/ports/store_connector_adapter_interface.py"
    click RedisAd "https://github.com/marcosvs98/cqrs-architecture-with-python/blob/main/src/adapters/redis_adapter.py"
    click MongoConnAd "https://github.com/marcosvs98/cqrs-architecture-with-python/blob/main/src/domain/order/adapters/mongo_db_connector_adapter.py"
    click KafkaPubAd "https://github.com/marcosvs98/cqrs-architecture-with-python/blob/main/src/domain/order/adapters/kafka_publisher_adapter.py"
    click OrderEventPubAd "https://github.com/marcosvs98/cqrs-architecture-with-python/blob/main/src/domain/order/adapters/order_event_publisher_adapter.py"
    click CostCalcAd "https://github.com/marcosvs98/cqrs-architecture-with-python/blob/main/src/domain/delivery/adapters/cost_calculator_adapter.py"
    click GoogleMapsAd "https://github.com/marcosvs98/cqrs-architecture-with-python/blob/main/src/domain/maps/adapters/google_maps_adapter.py"
    click PaypalAd "https://github.com/marcosvs98/cqrs-architecture-with-python/blob/main/src/domain/payment/adapters/paypal_adapter.py"
    click ProductAd "https://github.com/marcosvs98/cqrs-architecture-with-python/blob/main/src/domain/product/adapters/product_adapter.py"
    click AggRepo "https://github.com/marcosvs98/cqrs-architecture-with-python/blob/main/src/domain/order/repositories/order_aggregate_repository.py"
    click AggCacheRepo "https://github.com/marcosvs98/cqrs-architecture-with-python/blob/main/src/domain/order/repositories/order_aggregate_cache_repository.py"
    click EventStoreRepo "https://github.com/marcosvs98/cqrs-architecture-with-python/blob/main/src/domain/order/repositories/order_event_store_repository.py"
    click CacheIntf "https://github.com/marcosvs98/cqrs-architecture-with-python/blob/main/src/ports/cache_interface.py"
    click EventAdapterIntf "https://github.com/marcosvs98/cqrs-architecture-with-python/blob/main/src/domain/base/ports/event_adapter_interface.py"
    click settings "https://github.com/marcosvs98/cqrs-architecture-with-python/blob/main/src/settings.py"
```
