# mm-saiful6854/batch-processor architecture

> Architecture diagram of the GitHub repository mm-saiful6854/batch-processor, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mm-saiful6854/batch-processor
- Repository: https://github.com/mm-saiful6854/batch-processor

## Overview

1. **Repository purpose**
   - This is a small Spring Boot application whose core purpose is to run a Spring Batch job that imports people from a CSV file into an H2 in-memory database.

2. **Runtime boundary**
   - The app is a single JVM process launched via `BatchProcessorApplication`.
   - On startup, Spring Boot initializes the application context, the batch infrastructure, and the in-memory datasource, then automatically launches the batch job.

3. **Input side**
   - The batch job reads a fixed CSV resource at `src/main/resources/data/persons.csv`.
   - The CSV is the main external data source and defines the fields that flow through the pipeline: name, address, gender, nid, and number of family members.

4. **Batch processing pipeline**
   - The job follows the classic Spring Batch read-process-write pattern.
   - `BatchConfiguration` wires the step, chunk size, reader, processor, and writer together.
   - Processing is chunk-oriented, meaning records are grouped and committed in batches rather than one-by-one.

5. **Transformation layer**
   - `PersonItemProcessor` is the business transformation boundary.
   - Based on the README, it normalizes data before persistence, including uppercasing names and performing validation-like handling.
   - This is the place where source-format data is converted into database-ready records.

6. **Output side**
   - The writer persists `Person` entities into the `person` table using Spring Data JPA through `PersonRepository`.
   - H2 is used as the runtime datastore, so the database is ephemeral and recreated on each run.

7. **Domain model**
   - `Person` is the single domain/entity object that bridges CSV rows and database rows.
   - The model defines the shape of the persisted data and likely maps directly to the `person` table schema.

8. **Batch infrastructure and metadata**
   - Spring Batch maintains job/step execution state in its metadata tables (`BATCH_JOB_INSTANCE`, `BATCH_JOB_EXECUTION`, `BATCH_STEP_EXECUTION`, etc.).
   - This metadata is separate from the business table and is what enables monitoring, restartability, and execution tracking.

9. **Execution and observability**
   - `JobCompletionNotificationListener` is the completion hook that logs job status and likely queries the written records for verification.
   - Logging is set to DEBUG for Spring Batch, which makes the job lifecycle and chunk processing visible during execution.

10. **Configuration boundaries**
   - `application.properties` controls auto-run behavior, datasource setup, H2 console access, and JPA schema creation/drop.
   - `pom.xml` supplies the key platform dependencies: Spring Boot, Spring Batch, Spring Data JPA, and H2.
   - `run.sh` and the Maven wrapper provide the local execution path.

11. **Tests**
   - There is a basic Spring Boot test class under `src/test`, indicating the repo currently focuses on application startup/integration verification rather than extensive unit coverage.

12. **Architecture summary for a diagram**
   - The cleanest diagram is: CSV file → Spring Batch reader → processor → JPA writer → H2 `person` table, with Spring Batch metadata tables alongside it and startup/configuration feeding the whole flow from the Spring Boot application entry point.

Main entry points: [`src/main/java/com/example/batch_processor/config/BatchConfiguration.java`](https://github.com/mm-saiful6854/batch-processor/blob/main/src/main/java/com/example/batch_processor/config/BatchConfiguration.java) (Batch Config), [`src/main/java/com/example/batch_processor/BatchProcessorApplication.java`](https://github.com/mm-saiful6854/batch-processor/blob/main/src/main/java/com/example/batch_processor/BatchProcessorApplication.java) (Batch App), [`src/main/java/com/example/batch_processor/repository/PersonRepository.java`](https://github.com/mm-saiful6854/batch-processor/blob/main/src/main/java/com/example/batch_processor/repository/PersonRepository.java) (Person Repo), [`run.sh`](https://github.com/mm-saiful6854/batch-processor/blob/main/run.sh) (Run Script)

## Diagram (Mermaid)

```mermaid
flowchart TD

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

subgraph group_batch["Batch Flow"]
  node_batchconfig["Batch Config<br/>batch wiring"]
  node_reader["CSV Reader<br/>flat-file reader"]
  node_processor["Person Processor<br/>transformer"]
  node_writer["JPA Writer<br/>item writer"]
  node_listener["Job Listener<br/>completion hook"]
end

subgraph group_storage["Storage"]
  node_person["Person<br/>domain entity<br/>[Person.java]"]
  node_repository["Person Repo<br/>jpa repository"]
  node_csv["persons.csv<br/>input data<br/>[persons.csv]"]
  node_persondb[("person table<br/>business table")]
  node_batchmeta[("Batch metadata<br/>metadata tables")]
  node_h2[("H2 DB<br/>in-memory database")]
end

subgraph group_config["Config"]
  node_props["App Props<br/>runtime config"]
  node_pom["Maven Build<br/>build config<br/>[pom.xml]"]
  node_run["Run Script<br/>launcher<br/>[run.sh]"]
  node_mvnw["Maven Wrapper<br/>build tool"]
end

node_app -->|"loads"| node_batchconfig
node_app -->|"reads"| node_props
node_app -->|"connects to"| node_h2
node_batchconfig -->|"creates"| node_reader
node_batchconfig -->|"creates"| node_processor
node_batchconfig -->|"creates"| node_writer
node_batchconfig -->|"attaches"| node_listener
node_reader -->|"reads"| node_csv
node_reader -->|"maps to"| node_person
node_processor -->|"transforms"| node_person
node_writer -->|"uses"| node_repository
node_repository -->|"writes"| node_persondb
node_persondb -->|"hosted by"| node_h2
node_batchmeta -->|"stored in"| node_h2
node_listener -.->|"verifies"| node_repository
node_pom -.->|"builds"| node_app
node_run -.->|"invokes"| node_mvnw
node_run -->|"starts"| node_app

click node_app "https://github.com/mm-saiful6854/batch-processor/blob/main/src/main/java/com/example/batch_processor/BatchProcessorApplication.java"
click node_batchconfig "https://github.com/mm-saiful6854/batch-processor/blob/main/src/main/java/com/example/batch_processor/config/BatchConfiguration.java"
click node_reader "https://github.com/mm-saiful6854/batch-processor/blob/main/src/main/java/com/example/batch_processor/config/BatchConfiguration.java"
click node_processor "https://github.com/mm-saiful6854/batch-processor/blob/main/src/main/java/com/example/batch_processor/config/PersonItemProcessor.java"
click node_writer "https://github.com/mm-saiful6854/batch-processor/blob/main/src/main/java/com/example/batch_processor/config/BatchConfiguration.java"
click node_listener "https://github.com/mm-saiful6854/batch-processor/blob/main/src/main/java/com/example/batch_processor/config/JobCompletionNotificationListener.java"
click node_person "https://github.com/mm-saiful6854/batch-processor/blob/main/src/main/java/com/example/batch_processor/model/Person.java"
click node_repository "https://github.com/mm-saiful6854/batch-processor/blob/main/src/main/java/com/example/batch_processor/repository/PersonRepository.java"
click node_csv "https://github.com/mm-saiful6854/batch-processor/blob/main/src/main/resources/data/persons.csv"
click node_props "https://github.com/mm-saiful6854/batch-processor/blob/main/src/main/resources/application.properties"
click node_pom "https://github.com/mm-saiful6854/batch-processor/blob/main/pom.xml"
click node_run "https://github.com/mm-saiful6854/batch-processor/blob/main/run.sh"
click node_mvnw "https://github.com/mm-saiful6854/batch-processor/tree/main/mvnw"

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_batchconfig,node_reader,node_processor,node_writer,node_listener toneAmber
class node_person,node_repository,node_csv,node_persondb,node_batchmeta,node_h2 toneMint
class node_props,node_pom,node_run,node_mvnw toneRose
```

## Components

### Runtime

Application entrypoint and execution flow

- [Batch App](https://github.com/mm-saiful6854/batch-processor/blob/main/src/main/java/com/example/batch_processor/BatchProcessorApplication.java): spring boot app · Single JVM entrypoint that starts the batch job · `src/main/java/com/example/batch_processor/BatchProcessorApplication.java`

### Batch Flow

Spring Batch job and processing stages

- [Batch Config](https://github.com/mm-saiful6854/batch-processor/blob/main/src/main/java/com/example/batch_processor/config/BatchConfiguration.java): batch wiring · Defines job, step, chunk size, reader, processor, and writer · `src/main/java/com/example/batch_processor/config/BatchConfiguration.java`
- [CSV Reader](https://github.com/mm-saiful6854/batch-processor/blob/main/src/main/java/com/example/batch_processor/config/BatchConfiguration.java): flat-file reader · Reads person records from the CSV resource · `src/main/java/com/example/batch_processor/config/BatchConfiguration.java`
- [Person Processor](https://github.com/mm-saiful6854/batch-processor/blob/main/src/main/java/com/example/batch_processor/config/PersonItemProcessor.java): transformer · Normalizes and validates incoming person data · `src/main/java/com/example/batch_processor/config/PersonItemProcessor.java`
- [JPA Writer](https://github.com/mm-saiful6854/batch-processor/blob/main/src/main/java/com/example/batch_processor/config/BatchConfiguration.java): item writer · Persists processed people through Spring Data JPA · `src/main/java/com/example/batch_processor/config/BatchConfiguration.java`
- [Job Listener](https://github.com/mm-saiful6854/batch-processor/blob/main/src/main/java/com/example/batch_processor/config/JobCompletionNotificationListener.java): completion hook · Logs job completion and verifies execution results · `src/main/java/com/example/batch_processor/config/JobCompletionNotificationListener.java`

### Storage

Input resource and databases

- [Person](https://github.com/mm-saiful6854/batch-processor/blob/main/src/main/java/com/example/batch_processor/model/Person.java): domain entity · Entity bridging CSV rows and database rows · `src/main/java/com/example/batch_processor/model/Person.java`
- [Person Repo](https://github.com/mm-saiful6854/batch-processor/blob/main/src/main/java/com/example/batch_processor/repository/PersonRepository.java): jpa repository · Repository used by the writer to persist entities · `src/main/java/com/example/batch_processor/repository/PersonRepository.java`
- [persons.csv](https://github.com/mm-saiful6854/batch-processor/blob/main/src/main/resources/data/persons.csv): input data · Fixed CSV source containing person records · `src/main/resources/data/persons.csv`
- **person table**: business table · H2 table storing imported Person rows
- **Batch metadata**: metadata tables · Spring Batch execution tables for tracking and restartability
- **H2 DB**: in-memory database · Ephemeral runtime datastore and metadata store

### Config

Build, startup, and runtime settings

- [App Props](https://github.com/mm-saiful6854/batch-processor/blob/main/src/main/resources/application.properties): runtime config · Controls datasource, JPA, console, and auto-run settings · `src/main/resources/application.properties`
- [Maven Build](https://github.com/mm-saiful6854/batch-processor/blob/main/pom.xml): build config · Declares Spring Boot, Batch, JPA, and H2 dependencies · `pom.xml`
- [Run Script](https://github.com/mm-saiful6854/batch-processor/blob/main/run.sh): launcher · Local execution entrypoint for the application · `run.sh`
- [Maven Wrapper](https://github.com/mm-saiful6854/batch-processor/tree/main/mvnw): build tool · Wrapper used to run Maven consistently · `mvnw`

## Connections

- Batch App → Batch Config: loads · Spring Boot initializes batch wiring
- Batch App → App Props: reads · Startup behavior and datasource settings come from application properties
- Batch App → H2 DB: connects to · Application uses the in-memory database at runtime
- Batch Config → CSV Reader: creates · Configures the CSV reader
- Batch Config → Person Processor: creates · Registers the transformation step
- Batch Config → JPA Writer: creates · Configures the persistence writer
- Batch Config → Job Listener: attaches · Wires completion monitoring into the job
- CSV Reader → persons.csv: reads · Consumes the fixed CSV input file
- CSV Reader → Person: maps to · Converts CSV rows into Person objects
- Person Processor → Person: transforms · Normalizes source records before persistence
- JPA Writer → Person Repo: uses · Persists through Spring Data JPA
- Person Repo → person table: writes · Stores Person entities in the business table
- person table → H2 DB: hosted by · Business data lives in the in-memory H2 database
- Batch metadata → H2 DB: stored in · Batch execution metadata is maintained separately in H2
- Job Listener → Person Repo: verifies · Listener can query persisted records after completion
- Maven Build → Batch App: builds · Build supplies the runtime application
- Run Script → Maven Wrapper: invokes · Local runner typically uses the Maven wrapper
- Run Script → Batch App: starts · Launches the Spring Boot batch process