How cra1zer2/nbp-subscription-manager works
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: SubscriptionController.java Subscriptions API · SubscriptionService.java Subscription Service · SubscriptionRepository.java Repository · Subscription.java Subscription
Components 17
Runtime
Application bootstrap and deployment
- App Boot · Starts the Spring application context
subscriptionmanager/src/main/java/com/tsuprenko/subscriptionmanager/SubscriptionmanagerApplication.java
API
HTTP boundary and request/response contracts
- Subscriptions API · HTTP boundary for subscription CRUD and total cost endpoints
subscriptionmanager/src/main/java/com/tsuprenko/subscriptionmanager/controller/SubscriptionController.java - Request DTO · Incoming subscription create and update payload
subscriptionmanager/src/main/java/com/tsuprenko/subscriptionmanager/dto/SubscriptionRequest.java - Response DTO · Outgoing subscription representation
subscriptionmanager/src/main/java/com/tsuprenko/subscriptionmanager/dto/SubscriptionResponse.java - Mapper · Transforms between DTOs and the domain entity
subscriptionmanager/src/main/java/com/tsuprenko/subscriptionmanager/mapper/SubscriptionMapper.java - Error Handler · Centralized translation of exceptions to API errors
subscriptionmanager/src/main/java/com/tsuprenko/subscriptionmanager/exception/GlobalExceptionHandler.java - Error Response · Standard JSON error payload
subscriptionmanager/src/main/java/com/tsuprenko/subscriptionmanager/exception/ErrorResponse.java
Core
Business logic and domain model
- Subscription Service · Coordinates CRUD flows and total monthly cost calculation
subscriptionmanager/src/main/java/com/tsuprenko/subscriptionmanager/service/SubscriptionService.java - Subscription · Persistent subscription model stored in the database
subscriptionmanager/src/main/java/com/tsuprenko/subscriptionmanager/domain/Subscription.java - Not Found · Signals missing subscription resources
subscriptionmanager/src/main/java/com/tsuprenko/subscriptionmanager/exception/ResourceNotFoundException.java
Persistence
Database access and schema management
- Repository · Database access boundary for subscriptions
subscriptionmanager/src/main/java/com/tsuprenko/subscriptionmanager/repository/SubscriptionRepository.java - Schema Migration · Initial database schema definition
subscriptionmanager/src/main/resources/db/changelog/changesets/01-init-schema.sql - Changelog Master · Liquibase entrypoint for schema migrations
subscriptionmanager/src/main/resources/db/changelog/db.changelog-master.yaml
Integration
Outbound external dependencies
- NBP Client · Fetches exchange rates for total cost conversion
subscriptionmanager/src/main/java/com/tsuprenko/subscriptionmanager/client/NbpClient.java
Ops
Container and local deployment
- Dockerfile · Builds the Spring Boot service image
subscriptionmanager/Dockerfile - Compose Stack · Runs the API together with PostgreSQL
docker-compose.yml - App Config · Spring runtime and datasource configuration
subscriptionmanager/src/main/resources/application.properties
Connections 18
- 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