# miw-upm/apaw-practice architecture

> Architecture diagram of the GitHub repository miw-upm/apaw-practice, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/miw-upm/apaw-practice
- Repository: https://github.com/miw-upm/apaw-practice

## Overview

1. This repository is a Spring Boot, Java, Maven application built as a layered teaching example. It is not a single business app; it contains many independent sample domains under one codebase, all following the same architecture.

2. The core architectural rule is one-way dependency flow: HTTP resources call domain services; domain services depend on domain persistence ports and domain models; MongoDB adapters implement those ports and map to storage entities. The domain layer stays separated from infrastructure concerns.

3. The API boundary lives in `adapters/resources`. Each business area has its own REST resource set, such as airport, bank, clinic, clothing store, football, music, recipes, recruiting, shop, sports academy, student council, university, vehicle, video website, videogame, warehouse, and winery. `SystemResource` provides a general system endpoint, and `ApiExceptionHandler` centralizes API error translation.

4. The business boundary lives in `domain/services` and `domain/models`. Every sample domain has its own service class set and its own model package, so each vertical slice is isolated rather than sharing a large generic model. Domain packages also contain enums, DTOs, and update/search helper objects when the use case needs them.

5. Persistence is abstracted through `domain/persistenceports`. These interfaces define what the domain needs from storage without binding it to MongoDB. This makes the domain layer portable and testable, and it explains the strong separation between “port” interfaces and concrete persistence implementations.

6. The MongoDB adapter layer is in `adapters/mongodb`. Each domain has its own subpackage with:
   - Spring Data repositories in `daos`
   - storage documents in `entities`
   - MongoDB-based persistence adapters in `persistence`
   - seeders to preload demo data  
   This layer is the concrete bridge between domain objects and MongoDB collections.

7. The data flow for a typical request is: REST resource receives the HTTP call, service applies business rules, service invokes a persistence port, the MongoDB adapter uses a repository to read/write entity documents, and the result is mapped back into a domain model and then into the API response. The same pattern repeats across all sample domains.

8. Seed data is part of the architecture, not an afterthought. Each domain has a dedicated seeder, and there is also a global `DatabaseSeeder`. This indicates the application is meant to run with reproducible demo datasets, especially in local and test environments.

9. The repo includes an outbound integration boundary in `domain/restclients` and `adapters/restclients`. `UserRestClient`/`UserRestClientImpl` represent calls to an external user service, so the application is not purely self-contained; at least one use case depends on another HTTP service.

10. Configuration and cross-cutting concerns are centralized in `config`. `SecurityConfiguration`, `LoggingFilter`, and `RestTestConfiguration` affect all modules, so they sit outside the domain slices and enforce application-wide behavior.

11. Testing is organized by architectural layer. There are service tests and service integration tests under `domain/services`, repository and persistence integration tests under `adapters/mongodb`, and functional tests for REST resources under `functionaltests`. That structure mirrors the runtime flow and validates each boundary separately.

12. The repository is built for containerized local execution and CI. `Dockerfile`, `docker-compose.yml`, and `docker-compose-db.yml` indicate a Docker-based runtime with MongoDB. GitHub Actions runs continuous integration, and SonarCloud is used for code quality gates, which are part of the project’s delivery pipeline.

Main entry points: [`src/main/java/es/upm/miw/apaw/domain/services`](https://github.com/miw-upm/apaw-practice/tree/develop/src/main/java/es/upm/miw/apaw/domain/services) (Services), [`src/main/java/es/upm/miw/apaw/adapters/resources`](https://github.com/miw-upm/apaw-practice/tree/develop/src/main/java/es/upm/miw/apaw/adapters/resources) (REST API), [`src/main/java/es/upm/miw/apaw/adapters/mongodb`](https://github.com/miw-upm/apaw-practice/tree/develop/src/main/java/es/upm/miw/apaw/adapters/mongodb) (MongoDB), [`src/main/java/es/upm/miw/apaw/domain/persistenceports`](https://github.com/miw-upm/apaw-practice/tree/develop/src/main/java/es/upm/miw/apaw/domain/persistenceports) (Ports)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_application(("Application<br/>Spring Boot entrypoint<br/>[Application.java]"))
  node_config["Config"]
end

subgraph group_adapters["Adapters"]
  node_api_boundary["REST API<br/>HTTP adapters"]
  node_api_errors["Errors<br/>API exception mapping"]
  node_system_resource["System"]
  node_mongo_adapter[("MongoDB<br/>Persistence adapters")]
  node_database_seeder["Seeder<br/>Demo data bootstrap"]
end

subgraph group_domain["Domain"]
  node_airport_slice["Airport<br/>Vertical slice"]
  node_commerce_slice["Commerce<br/>Vertical slice"]
  node_mobility_slice["Mobility<br/>Vertical slice"]
  node_media_slice["Media<br/>Vertical slice"]
  node_sports_slice["Sports<br/>Vertical slice"]
  node_education_slice["Education<br/>Vertical slice"]
  node_domain_services["Services"]
  node_domain_models["Models<br/>Domain model layer"]
  node_persistence_ports["Ports<br/>Persistence interfaces"]
end

subgraph group_integration["Integration"]
  node_user_rest_client["User client<br/>Outbound HTTP port"]
  node_user_rest_client_impl["User client impl<br/>HTTP client adapter"]
end

node_application -->|"loads"| node_config
node_application -->|"starts"| node_api_boundary
node_api_boundary -->|"uses"| node_api_errors
node_api_boundary -->|"calls"| node_domain_services
node_domain_services -->|"uses"| node_domain_models
node_domain_services -->|"depends on"| node_persistence_ports
node_mongo_adapter -->|"implements"| node_persistence_ports
node_mongo_adapter -->|"bootstraps"| node_database_seeder
node_database_seeder -->|"writes via"| node_mongo_adapter
node_domain_models -->|"shapes"| node_persistence_ports
node_airport_slice -.->|"example of"| node_domain_services
node_commerce_slice -.->|"example of"| node_domain_services
node_mobility_slice -.->|"example of"| node_domain_services
node_media_slice -.->|"example of"| node_domain_services
node_sports_slice -.->|"example of"| node_domain_services
node_education_slice -.->|"example of"| node_domain_services
node_user_rest_client_impl -->|"implements"| node_user_rest_client
node_domain_services -->|"calls"| node_user_rest_client

click node_application "https://github.com/miw-upm/apaw-practice/blob/develop/src/main/java/es/upm/miw/apaw/Application.java"
click node_config "https://github.com/miw-upm/apaw-practice/tree/develop/src/main/java/es/upm/miw/apaw/config"
click node_api_boundary "https://github.com/miw-upm/apaw-practice/tree/develop/src/main/java/es/upm/miw/apaw/adapters/resources"
click node_api_errors "https://github.com/miw-upm/apaw-practice/tree/develop/src/main/java/es/upm/miw/apaw/adapters/resources/exceptionshandler"
click node_system_resource "https://github.com/miw-upm/apaw-practice/blob/develop/src/main/java/es/upm/miw/apaw/adapters/resources/system/SystemResource.java"
click node_mongo_adapter "https://github.com/miw-upm/apaw-practice/tree/develop/src/main/java/es/upm/miw/apaw/adapters/mongodb"
click node_database_seeder "https://github.com/miw-upm/apaw-practice/blob/develop/src/main/java/es/upm/miw/apaw/adapters/mongodb/DatabaseSeeder.java"
click node_airport_slice "https://github.com/miw-upm/apaw-practice/tree/develop/src/main/java/es/upm/miw/apaw/domain/services/airport"
click node_commerce_slice "https://github.com/miw-upm/apaw-practice/tree/develop/src/main/java/es/upm/miw/apaw/domain/services"
click node_mobility_slice "https://github.com/miw-upm/apaw-practice/tree/develop/src/main/java/es/upm/miw/apaw/domain/services/metro"
click node_media_slice "https://github.com/miw-upm/apaw-practice/tree/develop/src/main/java/es/upm/miw/apaw/domain/services/music"
click node_sports_slice "https://github.com/miw-upm/apaw-practice/tree/develop/src/main/java/es/upm/miw/apaw/domain/services/sports"
click node_education_slice "https://github.com/miw-upm/apaw-practice/tree/develop/src/main/java/es/upm/miw/apaw/domain/services/university"
click node_domain_services "https://github.com/miw-upm/apaw-practice/tree/develop/src/main/java/es/upm/miw/apaw/domain/services"
click node_domain_models "https://github.com/miw-upm/apaw-practice/tree/develop/src/main/java/es/upm/miw/apaw/domain/models"
click node_persistence_ports "https://github.com/miw-upm/apaw-practice/tree/develop/src/main/java/es/upm/miw/apaw/domain/persistenceports"
click node_user_rest_client "https://github.com/miw-upm/apaw-practice/blob/develop/src/main/java/es/upm/miw/apaw/domain/restclients/UserRestClient.java"
click node_user_rest_client_impl "https://github.com/miw-upm/apaw-practice/blob/develop/src/main/java/es/upm/miw/apaw/adapters/restclients/UserRestClientImpl.java"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_application,node_config toneBlue
class node_api_boundary,node_api_errors,node_system_resource,node_mongo_adapter,node_database_seeder toneAmber
class node_airport_slice,node_commerce_slice,node_mobility_slice,node_media_slice,node_sports_slice,node_education_slice,node_domain_services,node_domain_models,node_persistence_ports toneMint
class node_user_rest_client,node_user_rest_client_impl toneRose
```

## Components

### Runtime

Bootstrapping and application-wide configuration

- [Application](https://github.com/miw-upm/apaw-practice/blob/develop/src/main/java/es/upm/miw/apaw/Application.java): Spring Boot entrypoint · Starts the application and wires the layered architecture. · `src/main/java/es/upm/miw/apaw/Application.java`
- [Config](https://github.com/miw-upm/apaw-practice/tree/develop/src/main/java/es/upm/miw/apaw/config): Cross-cutting config · Security, logging, and test wiring applied across the app. · `src/main/java/es/upm/miw/apaw/config`

### Adapters

HTTP and MongoDB boundaries plus the seeding bridge

- [REST API](https://github.com/miw-upm/apaw-practice/tree/develop/src/main/java/es/upm/miw/apaw/adapters/resources): HTTP adapters · Resource layer exposing all sample business domains. · `src/main/java/es/upm/miw/apaw/adapters/resources`
- [Errors](https://github.com/miw-upm/apaw-practice/tree/develop/src/main/java/es/upm/miw/apaw/adapters/resources/exceptionshandler): API exception mapping · Centralized translation of domain and infrastructure errors to HTTP responses. · `src/main/java/es/upm/miw/apaw/adapters/resources/exceptionshandler`
- [System](https://github.com/miw-upm/apaw-practice/blob/develop/src/main/java/es/upm/miw/apaw/adapters/resources/system/SystemResource.java): System endpoint · General endpoint outside the business slices. · `src/main/java/es/upm/miw/apaw/adapters/resources/system/SystemResource.java`
- [MongoDB](https://github.com/miw-upm/apaw-practice/tree/develop/src/main/java/es/upm/miw/apaw/adapters/mongodb): Persistence adapters · Concrete storage bridge for all vertical slices. · `src/main/java/es/upm/miw/apaw/adapters/mongodb`
- [Seeder](https://github.com/miw-upm/apaw-practice/blob/develop/src/main/java/es/upm/miw/apaw/adapters/mongodb/DatabaseSeeder.java): Demo data bootstrap · Global and per-domain seeders preload reproducible datasets. · `src/main/java/es/upm/miw/apaw/adapters/mongodb/DatabaseSeeder.java`

### Domain

Business services, models, and persistence ports

- [Airport](https://github.com/miw-upm/apaw-practice/tree/develop/src/main/java/es/upm/miw/apaw/domain/services/airport): Vertical slice · Representative sample domain with its own resources, services, models, and Mongo adapters. · `src/main/java/es/upm/miw/apaw/domain/services/airport`
- [Commerce](https://github.com/miw-upm/apaw-practice/tree/develop/src/main/java/es/upm/miw/apaw/domain/services): Vertical slice · Representative group for bank, clinic, clothing store, shop, and recruiting-style business examples. · `src/main/java/es/upm/miw/apaw/domain/services`
- [Mobility](https://github.com/miw-upm/apaw-practice/tree/develop/src/main/java/es/upm/miw/apaw/domain/services/metro): Vertical slice · Representative group for metro, vehicle, warehouse, and transport-style examples. · `src/main/java/es/upm/miw/apaw/domain/services/metro`
- [Media](https://github.com/miw-upm/apaw-practice/tree/develop/src/main/java/es/upm/miw/apaw/domain/services/music): Vertical slice · Representative group for music, video website, and videogame examples. · `src/main/java/es/upm/miw/apaw/domain/services/music`
- [Sports](https://github.com/miw-upm/apaw-practice/tree/develop/src/main/java/es/upm/miw/apaw/domain/services/sports): Vertical slice · Representative group for football, fighters, martial arts gym, and sports academy examples. · `src/main/java/es/upm/miw/apaw/domain/services/sports`
- [Education](https://github.com/miw-upm/apaw-practice/tree/develop/src/main/java/es/upm/miw/apaw/domain/services/university): Vertical slice · Representative group for university and student council examples. · `src/main/java/es/upm/miw/apaw/domain/services/university`
- [Services](https://github.com/miw-upm/apaw-practice/tree/develop/src/main/java/es/upm/miw/apaw/domain/services): Use-case services · Business logic layer coordinating rules and repository access across independent slices. · `src/main/java/es/upm/miw/apaw/domain/services`
- [Models](https://github.com/miw-upm/apaw-practice/tree/develop/src/main/java/es/upm/miw/apaw/domain/models): Domain model layer · Per-slice entities, DTOs, enums, and update/search helper objects. · `src/main/java/es/upm/miw/apaw/domain/models`
- [Ports](https://github.com/miw-upm/apaw-practice/tree/develop/src/main/java/es/upm/miw/apaw/domain/persistenceports): Persistence interfaces · Storage abstractions implemented by adapters and kept free of MongoDB concerns. · `src/main/java/es/upm/miw/apaw/domain/persistenceports`

### Integration

Outbound HTTP dependency

- [User client](https://github.com/miw-upm/apaw-practice/blob/develop/src/main/java/es/upm/miw/apaw/domain/restclients/UserRestClient.java): Outbound HTTP port · Domain-facing contract for the external user service. · `src/main/java/es/upm/miw/apaw/domain/restclients/UserRestClient.java`
- [User client impl](https://github.com/miw-upm/apaw-practice/blob/develop/src/main/java/es/upm/miw/apaw/adapters/restclients/UserRestClientImpl.java): HTTP client adapter · Concrete REST client implementation used by the application. · `src/main/java/es/upm/miw/apaw/adapters/restclients/UserRestClientImpl.java`

## Connections

- Application → Config: loads · Bootstrapping activates application-wide configuration.
- Application → REST API: starts · Spring Boot exposes the REST resources.
- REST API → Errors: uses · Resources rely on centralized error translation.
- REST API → Services: calls · HTTP resources delegate to use-case services.
- Services → Models: uses · Services operate on domain objects and DTOs.
- Services → Ports: depends on · Services access storage only through ports.
- MongoDB → Ports: implements · MongoDB adapters fulfill the domain contracts.
- MongoDB → Seeder: bootstraps · Seeders populate demo data through the adapter layer.
- Seeder → MongoDB: writes via · Seed data is inserted using MongoDB persistence infrastructure.
- Models → Ports: shapes · Models define the data expected by ports and services.
- Airport → Services: example of · One representative vertical slice in the layered pattern.
- Commerce → Services: example of · Representative business-domain cluster.
- Mobility → Services: example of · Representative transport and logistics cluster.
- Media → Services: example of · Representative content and media cluster.
- Sports → Services: example of · Representative sports-related cluster.
- Education → Services: example of · Representative education-related cluster.
- User client impl → User client: implements · Concrete adapter fulfills the outbound contract.
- Services → User client: calls · Selected use cases depend on external user data.