# cra1zer2/nbp-subscription-manager architecture

> Architecture diagram of the GitHub repository cra1zer2/nbp-subscription-manager, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/cra1zer2/nbp-subscription-manager
- Repository: https://github.com/cra1zer2/nbp-subscription-manager

## Overview

1. **Project shape**
   - This is a single Spring Boot backend service in `subscriptionmanager/`, packaged as a Dockerized REST API.
   - The repository root also contains `docker-compose.yml` to run the app together with PostgreSQL, so the deployment unit is “API + database,” not a standalone library.

2. **Request entrypoint**
   - `SubscriptionController` is the HTTP boundary for `/api/v1/subscriptions`.
   - It exposes the CRUD endpoints plus a dedicated `/total` endpoint for cost aggregation.
   - `SubscriptionmanagerApplication` is the bootstrapping class that starts the Spring context.

3. **Core domain model**
   - `domain/Subscription` is the persistence/domain entity around which the app is built.
   - It represents provider name, amount, currency, and next payment date, and is the object stored in the database and manipulated by the service layer.

4. **DTO boundary**
   - `dto/SubscriptionRequest` and `dto/SubscriptionResponse` isolate API payloads from the entity model.
   - This keeps the controller and service from leaking persistence details directly into the external contract.

5. **Mapping layer**
   - `mapper/SubscriptionMapper` is the transformation boundary between request/response DTOs and the domain entity.
   - The architecture intentionally separates serialization shapes from the internal model, which is important for diagramming the API edge versus internal data handling.

6. **Service layer orchestration**
   - `service/SubscriptionService` contains the main business flow: create, read, update, delete, and calculate total monthly cost.
   - It also coordinates currency conversion when aggregating the total, so the service is the central place where database data and external exchange-rate data meet.

7. **Persistence layer**
   - `repository/SubscriptionRepository` is the database access boundary, likely a Spring Data repository for the subscriptions table.
   - The database schema is managed by Liquibase under `src/main/resources/db/changelog/`, with `01-init-schema.sql` defining the initial table structure.

8. **External dependency: exchange-rate API**
   - `client/NbpClient` is the outbound integration to the NBP exchange-rate service.
   - Its role is important architecturally because the `/total` calculation depends on live rate lookup, and the README notes an offline fallback path with predefined safe rates for USD/EUR if the API is unavailable.

9. **Error handling boundary**
   - `exception/GlobalExceptionHandler` provides centralized REST error translation.
   - `ResourceNotFoundException` and `ErrorResponse` show a consistent error model, so controller/service failures are converted into stable JSON responses rather than leaking raw stack traces.

10. **Runtime and infrastructure**
   - The app is container-first: `Dockerfile` builds the Spring Boot service, and `docker-compose.yml` wires it to PostgreSQL.
   - `application.properties` holds runtime configuration, while Liquibase runs on startup to prepare the schema before the API serves requests.

11. **End-to-end data flow**
   - For create/update: HTTP request → controller → validation/DTO mapping → service → repository → PostgreSQL → response DTO.
   - For list/retrieve: controller → service → repository → entity-to-response mapping.
   - For total cost: controller → service → repository to load subscriptions → NBP client for exchange rates → service computes PLN total → numeric response.

12. **Testing boundary**
   - `src/test/java/.../SubscriptionServiceTest.java` indicates unit tests focused on service logic, which is the most important orchestration layer here.
   - The presence of `test.http` suggests manual/API-level verification is also part of the workflow, but the main automated test boundary is the service layer.

13. **What to emphasize in an architecture diagram**
   - Show three internal layers: controller/API, service/business logic, repository/database.
   - Add two side boundaries: Liquibase migration path into PostgreSQL, and the NBP client out to the external exchange-rate API.
   - Also show the shared DTO/mapper and centralized exception handling as cross-cutting concerns around the request path.

Main entry points: [`subscriptionmanager/src/main/java/com/tsuprenko/subscriptionmanager/controller/SubscriptionController.java`](https://github.com/cra1zer2/nbp-subscription-manager/blob/main/subscriptionmanager/src/main/java/com/tsuprenko/subscriptionmanager/controller/SubscriptionController.java) (Subscriptions API), [`subscriptionmanager/src/main/java/com/tsuprenko/subscriptionmanager/service/SubscriptionService.java`](https://github.com/cra1zer2/nbp-subscription-manager/blob/main/subscriptionmanager/src/main/java/com/tsuprenko/subscriptionmanager/service/SubscriptionService.java) (Subscription Service), [`subscriptionmanager/src/main/java/com/tsuprenko/subscriptionmanager/repository/SubscriptionRepository.java`](https://github.com/cra1zer2/nbp-subscription-manager/blob/main/subscriptionmanager/src/main/java/com/tsuprenko/subscriptionmanager/repository/SubscriptionRepository.java) (Repository), [`subscriptionmanager/src/main/java/com/tsuprenko/subscriptionmanager/domain/Subscription.java`](https://github.com/cra1zer2/nbp-subscription-manager/blob/main/subscriptionmanager/src/main/java/com/tsuprenko/subscriptionmanager/domain/Subscription.java) (Subscription)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_app(("App Boot<br/>spring boot entrypoint"))
end

subgraph group_api["API"]
  node_controller["Subscriptions API<br/>REST controller"]
  node_request["Request DTO<br/>api payload"]
  node_response["Response DTO<br/>api payload"]
  node_mapper{{"Mapper"}}
  node_errors["Error Handler<br/>rest exception handler"]
  node_errorresp["Error Response<br/>api error model<br/>[ErrorResponse.java]"]
end

subgraph group_core["Core"]
  node_service["Subscription Service<br/>business service"]
  node_subscription[("Subscription<br/>domain entity<br/>[Subscription.java]")]
  node_notfound(("Not Found<br/>domain exception"))
end

subgraph group_persistence["Persistence"]
  node_repo["Repository<br/>data access"]
  node_changelog["Schema Migration<br/>liquibase changelog<br/>[01-init-schema.sql]"]
  node_dbmaster["Changelog Master<br/>liquibase master"]
end

subgraph group_integration["Integration"]
  node_nbpclient["NBP Client<br/>outbound client<br/>[NbpClient.java]"]
end

subgraph group_ops["Ops"]
  node_dockerfile["Dockerfile<br/>container build"]
  node_compose["Compose Stack<br/>deployment orchestration<br/>[docker-compose.yml]"]
  node_config["App Config<br/>runtime config"]
end

node_app -->|"starts"| node_controller
node_controller -->|"accepts"| node_request
node_controller -->|"maps"| node_mapper
node_controller -->|"calls"| node_service
node_controller -.->|"handled by"| node_errors
node_service -->|"loads"| node_repo
node_service -->|"manages"| node_subscription
node_service -->|"rates"| node_nbpclient
node_service -->|"uses"| node_mapper
node_repo -->|"persists"| node_subscription
node_dbmaster -->|"includes"| node_changelog
node_changelog -.->|"supports"| node_repo
node_compose -->|"builds"| node_dockerfile
node_compose -->|"configures"| node_config
node_errors -->|"produces"| node_errorresp
node_service -.->|"throws"| node_notfound
node_controller -->|"returns"| node_response
node_controller -.->|"reads"| node_subscription

click node_app "https://github.com/cra1zer2/nbp-subscription-manager/blob/main/subscriptionmanager/src/main/java/com/tsuprenko/subscriptionmanager/SubscriptionmanagerApplication.java"
click node_controller "https://github.com/cra1zer2/nbp-subscription-manager/blob/main/subscriptionmanager/src/main/java/com/tsuprenko/subscriptionmanager/controller/SubscriptionController.java"
click node_request "https://github.com/cra1zer2/nbp-subscription-manager/blob/main/subscriptionmanager/src/main/java/com/tsuprenko/subscriptionmanager/dto/SubscriptionRequest.java"
click node_response "https://github.com/cra1zer2/nbp-subscription-manager/blob/main/subscriptionmanager/src/main/java/com/tsuprenko/subscriptionmanager/dto/SubscriptionResponse.java"
click node_mapper "https://github.com/cra1zer2/nbp-subscription-manager/blob/main/subscriptionmanager/src/main/java/com/tsuprenko/subscriptionmanager/mapper/SubscriptionMapper.java"
click node_service "https://github.com/cra1zer2/nbp-subscription-manager/blob/main/subscriptionmanager/src/main/java/com/tsuprenko/subscriptionmanager/service/SubscriptionService.java"
click node_subscription "https://github.com/cra1zer2/nbp-subscription-manager/blob/main/subscriptionmanager/src/main/java/com/tsuprenko/subscriptionmanager/domain/Subscription.java"
click node_repo "https://github.com/cra1zer2/nbp-subscription-manager/blob/main/subscriptionmanager/src/main/java/com/tsuprenko/subscriptionmanager/repository/SubscriptionRepository.java"
click node_changelog "https://github.com/cra1zer2/nbp-subscription-manager/blob/main/subscriptionmanager/src/main/resources/db/changelog/changesets/01-init-schema.sql"
click node_dbmaster "https://github.com/cra1zer2/nbp-subscription-manager/blob/main/subscriptionmanager/src/main/resources/db/changelog/db.changelog-master.yaml"
click node_nbpclient "https://github.com/cra1zer2/nbp-subscription-manager/blob/main/subscriptionmanager/src/main/java/com/tsuprenko/subscriptionmanager/client/NbpClient.java"
click node_errors "https://github.com/cra1zer2/nbp-subscription-manager/blob/main/subscriptionmanager/src/main/java/com/tsuprenko/subscriptionmanager/exception/GlobalExceptionHandler.java"
click node_notfound "https://github.com/cra1zer2/nbp-subscription-manager/blob/main/subscriptionmanager/src/main/java/com/tsuprenko/subscriptionmanager/exception/ResourceNotFoundException.java"
click node_errorresp "https://github.com/cra1zer2/nbp-subscription-manager/blob/main/subscriptionmanager/src/main/java/com/tsuprenko/subscriptionmanager/exception/ErrorResponse.java"
click node_dockerfile "https://github.com/cra1zer2/nbp-subscription-manager/tree/main/subscriptionmanager/Dockerfile"
click node_compose "https://github.com/cra1zer2/nbp-subscription-manager/blob/main/docker-compose.yml"
click node_config "https://github.com/cra1zer2/nbp-subscription-manager/blob/main/subscriptionmanager/src/main/resources/application.properties"

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_app toneBlue
class node_controller,node_request,node_response,node_mapper,node_errors,node_errorresp toneAmber
class node_service,node_subscription,node_notfound toneMint
class node_repo,node_changelog,node_dbmaster toneRose
class node_nbpclient toneIndigo
class node_dockerfile,node_compose,node_config toneTeal
```

## Components

### Runtime

Application bootstrap and deployment

- [App Boot](https://github.com/cra1zer2/nbp-subscription-manager/blob/main/subscriptionmanager/src/main/java/com/tsuprenko/subscriptionmanager/SubscriptionmanagerApplication.java): spring boot entrypoint · Starts the Spring application context · `subscriptionmanager/src/main/java/com/tsuprenko/subscriptionmanager/SubscriptionmanagerApplication.java`

### API

HTTP boundary and request/response contracts

- [Subscriptions API](https://github.com/cra1zer2/nbp-subscription-manager/blob/main/subscriptionmanager/src/main/java/com/tsuprenko/subscriptionmanager/controller/SubscriptionController.java): REST controller · HTTP boundary for subscription CRUD and total cost endpoints · `subscriptionmanager/src/main/java/com/tsuprenko/subscriptionmanager/controller/SubscriptionController.java`
- [Request DTO](https://github.com/cra1zer2/nbp-subscription-manager/blob/main/subscriptionmanager/src/main/java/com/tsuprenko/subscriptionmanager/dto/SubscriptionRequest.java): api payload · Incoming subscription create and update payload · `subscriptionmanager/src/main/java/com/tsuprenko/subscriptionmanager/dto/SubscriptionRequest.java`
- [Response DTO](https://github.com/cra1zer2/nbp-subscription-manager/blob/main/subscriptionmanager/src/main/java/com/tsuprenko/subscriptionmanager/dto/SubscriptionResponse.java): api payload · Outgoing subscription representation · `subscriptionmanager/src/main/java/com/tsuprenko/subscriptionmanager/dto/SubscriptionResponse.java`
- [Mapper](https://github.com/cra1zer2/nbp-subscription-manager/blob/main/subscriptionmanager/src/main/java/com/tsuprenko/subscriptionmanager/mapper/SubscriptionMapper.java): dto mapper · Transforms between DTOs and the domain entity · `subscriptionmanager/src/main/java/com/tsuprenko/subscriptionmanager/mapper/SubscriptionMapper.java`
- [Error Handler](https://github.com/cra1zer2/nbp-subscription-manager/blob/main/subscriptionmanager/src/main/java/com/tsuprenko/subscriptionmanager/exception/GlobalExceptionHandler.java): rest exception handler · Centralized translation of exceptions to API errors · `subscriptionmanager/src/main/java/com/tsuprenko/subscriptionmanager/exception/GlobalExceptionHandler.java`
- [Error Response](https://github.com/cra1zer2/nbp-subscription-manager/blob/main/subscriptionmanager/src/main/java/com/tsuprenko/subscriptionmanager/exception/ErrorResponse.java): api error model · Standard JSON error payload · `subscriptionmanager/src/main/java/com/tsuprenko/subscriptionmanager/exception/ErrorResponse.java`

### Core

Business logic and domain model

- [Subscription Service](https://github.com/cra1zer2/nbp-subscription-manager/blob/main/subscriptionmanager/src/main/java/com/tsuprenko/subscriptionmanager/service/SubscriptionService.java): business service · Coordinates CRUD flows and total monthly cost calculation · `subscriptionmanager/src/main/java/com/tsuprenko/subscriptionmanager/service/SubscriptionService.java`
- [Subscription](https://github.com/cra1zer2/nbp-subscription-manager/blob/main/subscriptionmanager/src/main/java/com/tsuprenko/subscriptionmanager/domain/Subscription.java): domain entity · Persistent subscription model stored in the database · `subscriptionmanager/src/main/java/com/tsuprenko/subscriptionmanager/domain/Subscription.java`
- [Not Found](https://github.com/cra1zer2/nbp-subscription-manager/blob/main/subscriptionmanager/src/main/java/com/tsuprenko/subscriptionmanager/exception/ResourceNotFoundException.java): domain exception · Signals missing subscription resources · `subscriptionmanager/src/main/java/com/tsuprenko/subscriptionmanager/exception/ResourceNotFoundException.java`

### Persistence

Database access and schema management

- [Repository](https://github.com/cra1zer2/nbp-subscription-manager/blob/main/subscriptionmanager/src/main/java/com/tsuprenko/subscriptionmanager/repository/SubscriptionRepository.java): data access · Database access boundary for subscriptions · `subscriptionmanager/src/main/java/com/tsuprenko/subscriptionmanager/repository/SubscriptionRepository.java`
- [Schema Migration](https://github.com/cra1zer2/nbp-subscription-manager/blob/main/subscriptionmanager/src/main/resources/db/changelog/changesets/01-init-schema.sql): liquibase changelog · Initial database schema definition · `subscriptionmanager/src/main/resources/db/changelog/changesets/01-init-schema.sql`
- [Changelog Master](https://github.com/cra1zer2/nbp-subscription-manager/blob/main/subscriptionmanager/src/main/resources/db/changelog/db.changelog-master.yaml): liquibase master · Liquibase entrypoint for schema migrations · `subscriptionmanager/src/main/resources/db/changelog/db.changelog-master.yaml`

### Integration

Outbound external dependencies

- [NBP Client](https://github.com/cra1zer2/nbp-subscription-manager/blob/main/subscriptionmanager/src/main/java/com/tsuprenko/subscriptionmanager/client/NbpClient.java): outbound client · Fetches exchange rates for total cost conversion · `subscriptionmanager/src/main/java/com/tsuprenko/subscriptionmanager/client/NbpClient.java`

### Ops

Container and local deployment

- [Dockerfile](https://github.com/cra1zer2/nbp-subscription-manager/tree/main/subscriptionmanager/Dockerfile): container build · Builds the Spring Boot service image · `subscriptionmanager/Dockerfile`
- [Compose Stack](https://github.com/cra1zer2/nbp-subscription-manager/blob/main/docker-compose.yml): deployment orchestration · Runs the API together with PostgreSQL · `docker-compose.yml`
- [App Config](https://github.com/cra1zer2/nbp-subscription-manager/blob/main/subscriptionmanager/src/main/resources/application.properties): runtime config · Spring runtime and datasource configuration · `subscriptionmanager/src/main/resources/application.properties`

## Connections

- App Boot → Subscriptions API: starts · Bootstraps the web application
- Subscriptions API → Request DTO: accepts · Validates incoming payloads
- Subscriptions API → Mapper: maps · Converts request and response shapes
- Subscriptions API → Subscription Service: calls · Delegates request handling
- Subscriptions API → Error Handler: handled by · Exceptions are translated centrally
- Subscription Service → Repository: loads · Reads and stores subscriptions
- Subscription Service → Subscription: manages · Operates on the domain entity
- Subscription Service → NBP Client: rates · Looks up exchange rates for totals
- Subscription Service → Mapper: uses · Transforms between entity and DTOs where needed
- Repository → Subscription: persists · Maps the entity to database records
- Changelog Master → Schema Migration: includes · Liquibase master points to schema changesets
- Schema Migration → Repository: supports · Provides the underlying table schema
- Compose Stack → Dockerfile: builds · Compose uses the container image for the API
- Compose Stack → App Config: configures · Supplies runtime settings
- Error Handler → Error Response: produces · Converts failures into stable error payloads
- Subscription Service → Not Found: throws · Signals missing resources
- Subscriptions API → Response DTO: returns · Sends subscription responses to clients
- Subscriptions API → Subscription: reads · Uses entity data indirectly via service flows
