# 4bharathk/congestion-tax-calculator architecture

> Architecture diagram of the GitHub repository 4bharathk/congestion-tax-calculator, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-02-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/4bharathk/congestion-tax-calculator
- Repository: https://github.com/4bharathk/congestion-tax-calculator

## Overview

##### Project type + purpose (from README + tree)
This is a **single-service Spring Boot (3.5) REST API** that calculates **congestion tax fees** for a given vehicle type and a list of toll-entry timestamps.

- **API boundary (HTTP)**
- **request/response model**
- **service + domain logic**
- **validation + exception handling**
- **configuration and rules (2013-only, exemptions, holidays, daily cap, etc.)**
- **test coverage**

##### Architecture inferred from file structure
The code is organized in typical Spring layering:

- **Bootstrap**
- `CongestionTaxCalculatorApplication.java` (Spring Boot entrypoint)

- **Configuration**
- `config/AppConfig.java` (likely bean wiring, constants, rule configuration, etc.)
- `resources/application.properties` (runtime configuration)

- **Web/API layer**
- `controller/CongestionTaxController.java` (REST endpoint `/v1/congestiontax`)
- `controller/GlobalExceptionHandler.java` (central error mapping to HTTP responses)

- **Service layer (core orchestrator)**
- `services/TaxCalculatorService.java` (tax calculation orchestration; applies rules)

- **Domain / API models**
- `models/VehicleTaxRequest.java` (input payload: vehicleType + tollEntries)
- `models/TaxFeeReponse.java`, `models/TaxDetails.java` (output)
- `models/ErrorResponse.java` (error payload)

- **Domain utilities / rule primitives**
- `utils/TaxCalUtils.java` (helpers: parsing, date rules, holiday checks, etc.)
- `utils/TaxSlot.java` (time-slot fee mapping or fee bracket representation)

- **Tests**

##### Main components to include (separate into as many components as possible)

**Clients / External**
##### API Client (curl/Postman/consumer system)

**Application / Runtime container**
##### Spring Boot App (JVM process)
- Embedded Web Server (Tomcat/Netty—Spring Boot default)
- Spring MVC Dispatcher (request routing)

**Web layer**
##### `GlobalExceptionHandler` → `ErrorResponse`

**Service + rules**
##### `TaxCalculatorService` (main calculation coordinator)
- Vehicle exemption rule (e.g., Tractor exempt, etc.)
- “Only year 2013” rule
- Holiday exemption rule (with “except day before holiday” nuance)
- Daily max cap rule
- Duplicate timestamps / normalization (implied by sample inputs)
- Single charge rule (mark as TODO/partial)

**Utility / domain primitives**
##### `TaxSlot` (time-range → fee mapping)

**Configuration**
10. `AppConfig` + `application.properties` (fee table? caps? holidays? timezone? parsing formats?)

**Outputs**
##### `TaxFeeReponse` / `TaxDetails` returned to client

**Quality gates (optional but good)**

##### Controller → Validation
- If invalid: **Controller/Framework → GlobalExceptionHandler → ErrorResponse → Client**
##### Controller → returns response JSON → Client

- `TaxCalculatorService / TaxCalUtils / TaxSlot` **← AppConfig / application.properties** (depending on how it’s wired)

##### Architectural patterns to highlight

- **Layered architecture**: Controller → Service → Utilities/Domain
- **Centralized exception handling** (`@ControllerAdvice` pattern)
- **Rules engine (implicit)**: not a formal rules engine library, but a rule pipeline inside service/utils
- **Configuration-driven behavior** (if fees/caps/holidays are configurable)

- Java 21
- Spring Boot 3.5
- Spring MVC (REST)
- Maven build (`pom.xml`)
- JUnit tests (and Spring Test, if used)

Use the real names to be maximally accurate:

- `CongestionTaxCalculatorApplication` (entrypoint)
- `CongestionTaxController`
- `GlobalExceptionHandler`
- `TaxCalculatorService`
- `TaxCalUtils`
- `TaxSlot`
- `VehicleTaxRequest`
- `TaxFeeReponse`
- `TaxDetails`
- `ErrorResponse`
- `AppConfig`
- `application.properties`
- Tests:
- `CongestionTaxControllerTest`
- `TaxCalculatorServiceTest`

##### Final “don’t overthink it” checklist (what makes it “best”)
- You show both **success** and **failure** flows (invalid date, empty list, invalid vehicle type casing).
- You explicitly represent **rule constraints** from README (2013-only, holidays, cap, exemptions, TODO rule).
- You do **not** invent databases, queues, caches, or UIs that aren’t in the repo.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% =========================
    %% External / Clients
    %% =========================
    Client["API Client\n(curl / Postman / consumer system)"]:::external

    %% =========================
    %% Container / Runtime
    %% =========================
    subgraph "C4: Container — Congestion Tax Calculator API"
        direction TB

        Java["Java 21\n(JVM Process)"]:::runtime

        subgraph "Spring Boot 3.5 Runtime"
            direction TB

            App["CongestionTaxCalculatorApplication\n(Spring Boot Entrypoint)"]:::runtime
            WebServer["Embedded Web Server\n(Tomcat/Servlet)"]:::runtime
            Dispatcher["Spring MVC DispatcherServlet\n(Request Routing)"]:::runtime
        end

        subgraph "Web / API Layer"
            direction TB

            Controller["CongestionTaxController\nEndpoint: GET /v1/congestiontax"]:::component
            Validation["Validation\n(Bean Validation + Controller checks)"]:::component
            ExceptionHandler["GlobalExceptionHandler\n(@ControllerAdvice)"]:::error
        end

        subgraph "Service Layer"
            direction TB

            Service["TaxCalculatorService\n(Calculation Orchestrator)"]:::service

            subgraph "Tax Calculation Pipeline (rules)"
                direction TB
                Normalize["Normalize & Sort Timestamps\n(deduplicate/normalize)"]:::rule
                Rule2013["Rule: Only Year 2013"]:::rule
                VehicleExempt["Rule: Vehicle Exemptions\n(e.g., Tractor, etc.)"]:::rule
                HolidayExempt["Rule: Holidays/Weekends\n(+ day-before nuance)"]:::rule
                SlotFee["Compute Fee per Time Slot"]:::rule
                DailyCap["Rule: Daily Max Cap"]:::rule
                SingleCharge["Rule: Single-Charge (TODO/partial)"]:::todo
            end
        end

        subgraph "Domain Utilities / Primitives"
            direction TB
            Utils["TaxCalUtils\n(Parsing, date rules, holiday checks)"]:::component
            Slot["TaxSlot\n(Time-range → fee mapping)"]:::component
        end

        subgraph "Domain / API Models (DTOs)"
            direction TB
            Req["VehicleTaxRequest\n(vehicleType, tollEntries[])"]:::dto
            Resp["TaxFeeReponse\n(totalFee)"]:::dto
            Details["TaxDetails\n(breakdown)"]:::dto
            Err["ErrorResponse\n(message, details)"]:::dto
        end

        subgraph "Configuration"
            direction TB
            Config["AppConfig\n(Beans / constants / rules config)"]:::config
            Props["application.properties\n(Runtime properties)"]:::config
        end

        subgraph "Quality Gates (Tests)"
            direction TB
            TestCtrl["CongestionTaxControllerTest\n(Controller slice tests)"]:::test
            TestSvc["TaxCalculatorServiceTest\n(Service/unit tests)"]:::test
            TestCtx["CongestionTaxCalculatorApplicationTests\n(Context/smoke test)"]:::test
            Maven["Maven Build\n(pom.xml)"]:::build
        end

        NoDeps["No DB / No External Systems\n(single-service monolith)"]:::note
    end

    %% =========================
    %% Runtime request/response flow
    %% =========================
    Client -->|"HTTP GET /v1/congestiontax\n(JSON body)"| WebServer
    WebServer -->|"dispatch"| Dispatcher
    Dispatcher -->|"route"| Controller

    Controller -->|"bind JSON → DTO"| Req
    Controller -->|"validate"| Validation

    Validation -->|"valid"| Service
    Validation -->|"invalid/parse error"| ExceptionHandler
    ExceptionHandler -->|"handleException() → ErrorResponse"| Err
    Err -->|"HTTP 4xx/5xx (JSON)"| Client

    Service -->|"calculateTax(request)"| Normalize
    Normalize --> Rule2013
    Rule2013 --> VehicleExempt
    VehicleExempt --> HolidayExempt
    HolidayExempt --> SlotFee
    SlotFee --> DailyCap
    DailyCap --> SingleCharge

    Service -->|"uses helpers"| Utils
    SlotFee -->|"mapTimeToFee()"| Slot

    Service -->|"constructs"| Details
    Service -->|"constructs"| Resp
    Controller -->|"returns"| Resp
    Resp -->|"HTTP 200 (JSON)"| Client

    %% =========================
    %% Config usage (dashed)
    %% =========================
    Config -.->|"wires/params"| Service
    Config -.->|"wires/params"| Utils
    Config -.->|"wires/params"| Slot
    Props -.->|"runtime config"| Config

    %% =========================
    %% Tests & build dependencies (dashed)
    %% =========================
    Maven -.->|"builds/tests"| TestCtrl
    Maven -.->|"builds/tests"| TestSvc
    Maven -.->|"builds/tests"| TestCtx

    TestCtrl -.->|"verifies endpoint + errors"| Controller
    TestCtrl -.->|"verifies exception mapping"| ExceptionHandler
    TestSvc -.->|"verifies rules pipeline"| Service
    TestCtx -.->|"verifies Spring context"| App

    %% =========================
    %% Bootstrap connections
    %% =========================
    App -->|"starts"| WebServer
    App -->|"registers"| Dispatcher
    App -->|"loads"| Config
    App -->|"loads"| Props

    %% =========================
    %% Click events (component mappings)
    %% =========================
    click App "https://github.com/4bharathk/congestion-tax-calculator/blob/main/src/main/java/com/volvocars/congestion_tax_calculator/CongestionTaxCalculatorApplication.java"
    click Config "https://github.com/4bharathk/congestion-tax-calculator/blob/main/src/main/java/com/volvocars/congestion_tax_calculator/config/AppConfig.java"
    click Props "https://github.com/4bharathk/congestion-tax-calculator/blob/main/src/main/resources/application.properties"
    click Controller "https://github.com/4bharathk/congestion-tax-calculator/blob/main/src/main/java/com/volvocars/congestion_tax_calculator/controller/CongestionTaxController.java"
    click ExceptionHandler "https://github.com/4bharathk/congestion-tax-calculator/blob/main/src/main/java/com/volvocars/congestion_tax_calculator/controller/GlobalExceptionHandler.java"
    click Service "https://github.com/4bharathk/congestion-tax-calculator/blob/main/src/main/java/com/volvocars/congestion_tax_calculator/services/TaxCalculatorService.java"
    click Utils "https://github.com/4bharathk/congestion-tax-calculator/blob/main/src/main/java/com/volvocars/congestion_tax_calculator/utils/TaxCalUtils.java"
    click Slot "https://github.com/4bharathk/congestion-tax-calculator/blob/main/src/main/java/com/volvocars/congestion_tax_calculator/utils/TaxSlot.java"
    click Req "https://github.com/4bharathk/congestion-tax-calculator/blob/main/src/main/java/com/volvocars/congestion_tax_calculator/models/VehicleTaxRequest.java"
    click Resp "https://github.com/4bharathk/congestion-tax-calculator/blob/main/src/main/java/com/volvocars/congestion_tax_calculator/models/TaxFeeReponse.java"
    click Details "https://github.com/4bharathk/congestion-tax-calculator/blob/main/src/main/java/com/volvocars/congestion_tax_calculator/models/TaxDetails.java"
    click Err "https://github.com/4bharathk/congestion-tax-calculator/blob/main/src/main/java/com/volvocars/congestion_tax_calculator/models/ErrorResponse.java"
    click TestCtrl "https://github.com/4bharathk/congestion-tax-calculator/blob/main/src/test/java/com/volvocars/congestion_tax_calculator/CongestionTaxControllerTest.java"
    click TestSvc "https://github.com/4bharathk/congestion-tax-calculator/blob/main/src/test/java/com/volvocars/congestion_tax_calculator/TaxCalculatorServiceTest.java"
    click TestCtx "https://github.com/4bharathk/congestion-tax-calculator/blob/main/src/test/java/com/volvocars/congestion_tax_calculator/CongestionTaxCalculatorApplicationTests.java"
    click Maven "https://github.com/4bharathk/congestion-tax-calculator/blob/main/pom.xml"

    %% =========================
    %% Styles
    %% =========================
    classDef external fill:#E9F2FF,stroke:#2B6CB0,stroke-width:2px,color:#0B2E4A
    classDef runtime fill:#DBEAFE,stroke:#1D4ED8,stroke-width:2px,color:#0A1F44
    classDef component fill:#BFDBFE,stroke:#1E40AF,stroke-width:2px,color:#0A1F44
    classDef service fill:#93C5FD,stroke:#1E3A8A,stroke-width:2px,color:#0A1F44
    classDef rule fill:#C7D2FE,stroke:#4338CA,stroke-width:2px,color:#1E1B4B
    classDef todo fill:#FEE2E2,stroke:#B91C1C,stroke-width:2px,color:#7F1D1D
    classDef dto fill:#DCFCE7,stroke:#16A34A,stroke-width:2px,color:#052E16
    classDef config fill:#FEF3C7,stroke:#D97706,stroke-width:2px,color:#451A03
    classDef error fill:#FECACA,stroke:#DC2626,stroke-width:2px,color:#450A0A
    classDef test fill:#E5E7EB,stroke:#374151,stroke-width:2px,color:#111827
    classDef build fill:#F3F4F6,stroke:#4B5563,stroke-width:2px,color:#111827
    classDef note fill:#FFF7ED,stroke:#9A3412,stroke-width:2px,color:#431407
```
