# handshakesbydc/carpark-info-assignment architecture

> Architecture diagram of the GitHub repository handshakesbydc/carpark-info-assignment, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/handshakesbydc/carpark-info-assignment
- Repository: https://github.com/handshakesbydc/carpark-info-assignment

## Overview

##### Project type and purpose
- This is a backend‐only service whose responsibilities are:
a. Daily ingestion of a “delta” CSV file of HDB carpark data.
b. Transactional ETL (batch job with rollback on error).
c. Exposing REST APIs (with Swagger docs) for clients to filter carparks, manage favorites.
- There is no front-end code in the repo; clients (e.g. a future web or mobile UI) will call your APIs.

##### (minimal) file structure
- Top level:
- README.md – spec and tech choices (Spring Boot/Batch, .NET Core, or Node.js)
- hdb-carpark-information-<timestamp>.csv – the daily delta input file
/src
/batch   ← Spring Batch jobs or .NET Core background service or Node cron
/api     ← REST controllers / route handlers
/service ← business logic (filtering, favorites)
/model   ← entity / ORM mappings
/config  ← DB, transaction, Swagger
/test    ← unit/integration tests

##### README for additional insights
- Must code a batch job that wraps processing in a single transaction (full-file rollback on error).
- Must expose filter & “add favorite” APIs, with Swagger/OpenAPI annotations.
- Must design for extensibility (e.g. swap CSV→JSON, change DB, injection of new batch steps).

##### Essential details
- Call out extension points (e.g. replace CSV with JSON feed, swap DB, add authentication).
- Where Swagger UI sits (e.g. a sub‐component of the API module).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Top-level specification
    README["Project Specification & Tech Choices\n(README.md)"]:::internal

    %% Ingestion Layer
    subgraph "Ingestion Layer"
        CSV["External Source: HDB CSV File"]:::externalSource
        Batch["Batch Processing Module\n(Spring Batch / .NET BG / Node cron)"]:::internal
    end

    %% API Layer
    subgraph "API Layer"
        API["REST API Module\n(Spring Boot Web MVC / .NET Web API / Express.js)"]:::internal
        Swagger["Swagger UI / OpenAPI Docs"]:::internal
    end

    %% Database
    DB["Relational Database\n(H2 / SQLite)\n(JPA/Hibernate / EF Core / Sequelize)"]:::db

    %% Clients and Monitoring
    Client["Client / UI Consumer"]:::client
    Monitor["Monitoring / Alerting"]:::monitoring

    %% Data Flows
    README --> Batch
    README --> API

    CSV -->|"Reads raw records"| Batch
    Batch -->|"INSERT/UPDATE; rollback on error"| DB
    Batch -. "rollback on error" .-> CSV

    Client -->|"HTTP GET/POST"| API
    API -->|"queries / writes favorites"| DB
    API -->|"push logs"| Monitor
    API -->|"OpenAPI contract"| Swagger

    %% Click Events
    click CSV "https://github.com/handshakesbydc/carpark-info-assignment/blob/master/hdb-carpark-information-20220824010400.csv"
    click README "https://github.com/handshakesbydc/carpark-info-assignment/blob/master/README.md"

    %% Styles
    classDef externalSource fill:#FFEB99,stroke:#333,stroke-width:1
    classDef internal fill:#D0E6FF,stroke:#333,stroke-width:1
    classDef db fill:#DFFFD6,stroke:#333,stroke-width:1,stroke-dasharray: 5 5
    classDef client fill:#FFE0B2,stroke:#333,stroke-width:1
    classDef monitoring fill:#FFE0B2,stroke:#333,stroke-width:1
```
