# nolifer-jpg/monochrome-backend architecture

> Architecture diagram of the GitHub repository nolifer-jpg/monochrome-backend, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-03-10). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/nolifer-jpg/monochrome-backend
- Repository: https://github.com/nolifer-jpg/monochrome-backend

## Overview

This is a **single-service Spring Boot REST backend** for **task/habit tracking**. It’s a classic layered monolith (not microservices) exposing JSON APIs to a future frontend (React/Next.js) and persisting data via **Spring Data JPA** into **H2 (in-memory)**.

- **External clients** (browser/frontend, curl/Postman)
- **HTTP REST API surface** (controllers + endpoints)
- **Layer boundaries** (controller → service → repository → database)
- **DTO mapping** and **validation**
- **Global exception handling** and how errors become HTTP responses
- **Runtime container** (Spring Boot app) and **build/run** (Maven)

From the tree + README, you have these concrete modules/components:

##### Application entrypoint
- `MonochromeApplication.java`
Bootstraps Spring context (component scanning, auto-config).

##### REST API layer
- `controller/HealthController.java` (health endpoint)
- `controller/TaskController.java` (tasks endpoints)

##### Business logic layer
- `service/TaskService.java` (service interface)
- `service/TaskServiceImpl.java` (implementation)

##### Data access layer
- `repository/TaskRepository.java` (Spring Data JPA repository)

##### Domain model (persistence)
- `domain/Task.java` (JPA entity)

##### API contracts (boundary objects)
- `dto/CreateTaskRequest.java` (POST input)
- `dto/TaskResponse.java` (output payload)

##### Error handling
- `exception/GlobalExceptionHandler.java` (maps exceptions/validation to responses)
- `exception/TaskNotFoundException.java`

##### Config/runtime dependencies
- `src/main/resources/application.properties` (H2/JPA/Spring config)
- `pom.xml`, `mvnw*`, `.mvn/**` (build tooling)
- Tests: `MonochromeApplicationTests.java`

##### TaskController
- deserializes JSON into `CreateTaskRequest`
- triggers validation (Bean Validation / Spring validation if present)
- calls **TaskService**
##### TaskServiceImpl
- applies business rules (e.g., default `completed=false`, timestamps, etc.)
- constructs/updates `Task` entity
- calls **TaskRepository**

##### Read path (get all tasks)
Client → `GET /tasks` → Controller → Service → Repository → DB → Service maps list to `TaskResponse[]` → Controller returns `200 OK`.

##### Command path (complete/delete)
Client → `PATCH /tasks/{id}/complete` or `DELETE /tasks/{id}`
- Repository may do `findById`
- If missing, service throws `TaskNotFoundException`
- Controller does not catch; **GlobalExceptionHandler** converts to `404 NOT_FOUND`
- On success returns `204 No Content`

##### Error paths (important to show explicitly)
- **Validation error** (e.g., blank description):
Client → Controller (validation fails) → GlobalExceptionHandler → `400 VALIDATION_ERROR` with field details
- **Not found**:
Service throws `TaskNotFoundException` → GlobalExceptionHandler → `404 NOT_FOUND`

##### Architectural patterns/design principles to highlight

- **Layered architecture** with strict direction:
- Controller (HTTP) depends on Service
- Service depends on Repository
- Repository depends on JPA/DB
- **DTO boundary**:
- Entities (`Task`) do not go directly over the wire
- `CreateTaskRequest`/`TaskResponse` are the API contract
- **Centralized exception translation**:
- Domain/service exceptions translated into proper HTTP semantics in one place
- **Stateless REST**:
- No auth/session currently
- **In-memory DB for dev** (H2), data resets on restart

How the backend sits in its world.
- Person: “Frontend Developer / End User”
- System: “MonoChrome Backend (Spring Boot)”
- External: “Future Frontend (React/Next.js)”
- Data store: “H2 In-Memory DB”
- Protocol: HTTP/JSON

Internal components *as they exist in packages*.
- Controllers
- Repository
- Domain entity
- DTOs
- GlobalExceptionHandler

This matches the file tree and avoids inventing components.

- `TaskController`, `HealthController`
- `TaskService` + `TaskServiceImpl`
- `TaskRepository`
- `Task` entity
- DTOs
- Exception handler + exceptions

On `TaskController`, list:
- `POST /tasks`
- `GET /tasks`
- `PATCH /tasks/{id}/complete`
- `DELETE /tasks/{id}`

On `HealthController`, list:
- `GET /health` (or whatever is implemented)

##### Transformations explicitly (DTO ↔ Entity)
- `CreateTaskRequest` → (mapping) → `Task`
- `Task` → (mapping) → `TaskResponse`

From `TaskServiceImpl`:
- throws `TaskNotFoundException` → handled by `GlobalExceptionHandler` → HTTP 404 payload

From controller/validation:
- `MethodArgumentNotValidException` (or similar) → `GlobalExceptionHandler` → HTTP 400 payload

##### Runtime boundary
Inside it: controllers/services/repositories/handler.
Outside: Client(s) and H2 DB.

##### “Don’t overthink it” but be very detailed (how to decompose further)
Because this repo is small, the best way to increase fidelity is to separate concerns inside each layer:

- “Request deserialization”
- “Validation”
- “HTTP status codes (201/200/204)”
- “Business rules”
- “Entity lifecycle (createdAt, completed default)”
- “NotFound guard”
- “DTO mapping”
- “Spring Data JPA (CrudRepository/JpaRepository)”
- “findById/save/findAll/deleteById”
- `application.properties` configures H2 + JPA
- In **Build/Run lane** (optional but useful):
- Maven Wrapper → Spring Boot plugin → produces runnable app

## Diagram (Mermaid)

```mermaid
flowchart TD

%% =========================
%% Diagram 1: Context / Container (C4 L1-L2)
%% =========================
subgraph CTX["Context & Container (C4 L1–L2)"]
direction TB

U["Person<br/>End User / Frontend Developer"]:::external
FE["Future Frontend<br/>(React/Next.js)"]:::external
APIClient["API Client<br/>(curl / Postman)"]:::external

subgraph SB["MonoChrome Backend<br/>(Spring Boot REST API)"]
direction TB
AppEntry["Spring Boot Runtime<br/>MonochromeApplication"]:::runtime
HttpSurface["HTTP/JSON REST Endpoints"]:::controller
end

DB[("H2 Database<br/>(In-memory)")]:::db
Cfg["Runtime Configuration<br/>(application.properties)"]:::config
Build["Build & Run Tooling<br/>(Maven Wrapper + pom.xml)"]:::build
Test["Tests<br/>(Spring Boot context)"]:::test

U -->|"uses"| FE
U -->|"uses"| APIClient
FE -->|"HTTP/JSON"| HttpSurface
APIClient -->|"HTTP/JSON"| HttpSurface

HttpSurface -->|"runs_in"| AppEntry
AppEntry -->|"JPA/Hibernate"| DB
Cfg -->|"configures"| AppEntry
Build -->|"builds_and_runs"| AppEntry
Test -->|"verifies_context"| AppEntry
end

%% =========================
%% Diagram 2: Component (C4 L3)
%% =========================
subgraph CMP["Component View (C4 L3) داخل Spring Boot Application"]
direction TB

subgraph RUNTIME["Runtime Boundary"]
direction TB

App["MonochromeApplication<br/>Bootstrap & Component Scan"]:::runtime

subgraph API["REST API Layer (Controllers)"]
direction TB
HealthC["HealthController<br/>GET /health"]:::controller
TaskC["TaskController<br/>POST /tasks<br/>GET /tasks<br/>PATCH /tasks/{id}/complete<br/>DELETE /tasks/{id}"]:::controller
end

subgraph BIZ["Business Logic Layer (Services)"]
direction TB
TaskSvc["TaskService<br/>(interface / inbound port)"]:::service
TaskSvcImpl["TaskServiceImpl<br/>Business rules + DTO mapping<br/>NotFound guard"]:::service
end

subgraph DATA["Data Access Layer"]
direction TB
TaskRepo["TaskRepository<br/>(Spring Data JPA)<br/>save/findAll/findById/deleteById"]:::repo
end

subgraph MODEL["Domain & API Contracts"]
direction TB
CreateReq["CreateTaskRequest<br/>(input DTO)"]:::model
TaskResp["TaskResponse<br/>(output DTO)"]:::model
TaskEnt["Task<br/>(JPA Entity)"]:::model
end

subgraph ERR["Error Handling"]
direction TB
GEH["GlobalExceptionHandler<br/>Exception → HTTP response"]:::error
TNF["TaskNotFoundException"]:::error
ValEx["Validation Exception<br/>(e.g., MethodArgumentNotValidException)"]:::error
end

DB2[("H2 Database<br/>(in-memory)")]:::db

end
end

%% --- Request/Response flows ---
Client1["External Clients<br/>(Frontend / curl / Postman)"]:::external

Client1 -->|"HTTP/JSON"| TaskC
Client1 -->|"HTTP/JSON"| HealthC

%% Controller -> Service
TaskC -->|"calls"| TaskSvc
TaskSvc -->|"implemented_by"| TaskSvcImpl

%% DTO boundary & validation
TaskC -->|"deserialize_to"| CreateReq
CreateReq -->|"Bean Validation"| ValEx

%% Service mapping + entity lifecycle
TaskSvcImpl -->|"map_request_to_entity"| TaskEnt
TaskSvcImpl -->|"map_entity_to_response"| TaskResp

%% Service -> Repository -> DB
TaskSvcImpl -->|"JPA_calls"| TaskRepo
TaskRepo -->|"persist/query (JPA/Hibernate)"| DB2

%% Response payload
TaskResp -->|"JSON response"| TaskC

%% --- Error flows (dotted) ---
TaskSvcImpl -.->|"throws"| TNF
TNF -.->|"handled_by"| GEH
ValEx -.->|"handled_by"| GEH
GEH -.->|"HTTP 404/400 JSON payload"| TaskC

%% Health controller minimal
HealthC -.->|"errors_handled_by"| GEH

%% =========================
%% Click events (from component mapping)
%% =========================
click App "https://github.com/nolifer-jpg/monochrome-backend/blob/Main/src/main/java/com/monochrome/MonochromeApplication.java"
click HealthC "https://github.com/nolifer-jpg/monochrome-backend/blob/Main/src/main/java/com/monochrome/controller/HealthController.java"
click TaskC "https://github.com/nolifer-jpg/monochrome-backend/blob/Main/src/main/java/com/monochrome/controller/TaskController.java"
click TaskSvc "https://github.com/nolifer-jpg/monochrome-backend/blob/Main/src/main/java/com/monochrome/service/TaskService.java"
click TaskSvcImpl "https://github.com/nolifer-jpg/monochrome-backend/blob/Main/src/main/java/com/monochrome/service/TaskServiceImpl.java"
click TaskRepo "https://github.com/nolifer-jpg/monochrome-backend/blob/Main/src/main/java/com/monochrome/repository/TaskRepository.java"
click TaskEnt "https://github.com/nolifer-jpg/monochrome-backend/blob/Main/src/main/java/com/monochrome/domain/Task.java"
click CreateReq "https://github.com/nolifer-jpg/monochrome-backend/blob/Main/src/main/java/com/monochrome/dto/CreateTaskRequest.java"
click TaskResp "https://github.com/nolifer-jpg/monochrome-backend/blob/Main/src/main/java/com/monochrome/dto/TaskResponse.java"
click GEH "https://github.com/nolifer-jpg/monochrome-backend/blob/Main/src/main/java/com/monochrome/exception/GlobalExceptionHandler.java"
click TNF "https://github.com/nolifer-jpg/monochrome-backend/blob/Main/src/main/java/com/monochrome/exception/TaskNotFoundException.java"
click Cfg "https://github.com/nolifer-jpg/monochrome-backend/blob/Main/src/main/resources/application.properties"
click Build "https://github.com/nolifer-jpg/monochrome-backend/blob/Main/pom.xml"
click Test "https://github.com/nolifer-jpg/monochrome-backend/blob/Main/src/test/java/com/monochrome/MonochromeApplicationTests.java"

%% Build tooling click targets
click Build "https://github.com/nolifer-jpg/monochrome-backend/blob/Main/pom.xml"
click Build "https://github.com/nolifer-jpg/monochrome-backend/blob/Main/pom.xml"
click Build "https://github.com/nolifer-jpg/monochrome-backend/blob/Main/pom.xml"
click Build "https://github.com/nolifer-jpg/monochrome-backend/blob/Main/pom.xml"
click Build "https://github.com/nolifer-jpg/monochrome-backend/blob/Main/pom.xml"
click Build "https://github.com/nolifer-jpg/monochrome-backend/blob/Main/pom.xml"
click Build "https://github.com/nolifer-jpg/monochrome-backend/blob/Main/pom.xml"
click Build "https://github.com/nolifer-jpg/monochrome-backend/blob/Main/pom.xml"
click Build "https://github.com/nolifer-jpg/monochrome-backend/blob/Main/pom.xml"
click Build "https://github.com/nolifer-jpg/monochrome-backend/blob/Main/pom.xml"
click Build "https://github.com/nolifer-jpg/monochrome-backend/blob/Main/pom.xml"
click Build "https://github.com/nolifer-jpg/monochrome-backend/blob/Main/pom.xml"
click Build "https://github.com/nolifer-jpg/monochrome-backend/blob/Main/pom.xml"

%% Wrapper files
click Build "https://github.com/nolifer-jpg/monochrome-backend/tree/Main/mvnw"
click Build "https://github.com/nolifer-jpg/monochrome-backend/blob/Main/mvnw.cmd"
click Build "https://github.com/nolifer-jpg/monochrome-backend/blob/Main/.mvn/wrapper/maven-wrapper.properties"

%% =========================
%% Styles (color is critical)
%% =========================
classDef external fill:#F2F4F7,stroke:#475467,color:#101828,stroke-width:1px
classDef runtime fill:#EEF4FF,stroke:#3B82F6,color:#0B1220,stroke-width:1.5px
classDef controller fill:#DBEAFE,stroke:#2563EB,color:#0B1220,stroke-width:1.5px
classDef service fill:#DCFCE7,stroke:#16A34A,color:#052e16,stroke-width:1.5px
classDef repo fill:#FFEDD5,stroke:#F97316,color:#431407,stroke-width:1.5px
classDef db fill:#FFF7ED,stroke:#C2410C,color:#431407,stroke-width:2px
classDef model fill:#F3F4F6,stroke:#6B7280,color:#111827,stroke-width:1px
classDef error fill:#FEE2E2,stroke:#DC2626,color:#450a0a,stroke-width:1.5px
classDef config fill:#EDE9FE,stroke:#7C3AED,color:#1F2937,stroke-width:1.5px
classDef build fill:#E0F2FE,stroke:#0284C7,color:#0B1220,stroke-width:1.5px
classDef test fill:#ECFCCB,stroke:#65A30D,color:#1A2E05,stroke-width:1.5px
```
