# dcsergio/tombojava architecture

> Architecture diagram of the GitHub repository dcsergio/tombojava, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/dcsergio/tombojava
- Repository: https://github.com/dcsergio/tombojava

## Overview

Tombojava is a Spring Boot tombola-card generator. The main workflow starts in the web UI: submit generation parameters, track an asynchronous job, download its PDF, or verify a generated series against drawn numbers; the UI also provides a clickable 90-number board. Generation builds valid candidate grids, repairs and checks conflicts, then returns accepted series for PDF rendering. The README documents the CLI as an optional alternative. Edges reflect the excerpts, SOURCE INDEX references, and README; UI and CLI links are documented rather than inferred from unsampled implementation.

Main entry points: [`src/main/java/it/sdc/tombojava/job/GenerationJobService.java`](https://github.com/dcsergio/tombojava/blob/main/src/main/java/it/sdc/tombojava/job/GenerationJobService.java) (Generation jobs), [`src/main/java/it/sdc/tombojava/tombola/ParallelSeriesEngine.java`](https://github.com/dcsergio/tombojava/blob/main/src/main/java/it/sdc/tombojava/tombola/ParallelSeriesEngine.java) (Parallel arbiter), [`src/main/java/it/sdc/tombojava/web/GenerationJobController.java`](https://github.com/dcsergio/tombojava/blob/main/src/main/java/it/sdc/tombojava/web/GenerationJobController.java) (Job API), [`src/main/java/it/sdc/tombojava/tombola/TombolaSeries.java`](https://github.com/dcsergio/tombojava/blob/main/src/main/java/it/sdc/tombojava/tombola/TombolaSeries.java) (Generated series)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web interface"]
  node_ui["Tombola UI<br/>[index.html]"]
  node_polling["Job polling<br/>[job-polling.js]"]
  node_webapi["Job API"]
  node_home["Home route"]
end

subgraph group_jobs["Job processing"]
  node_jobservice["Generation jobs"]
  node_jobstatus["Job state and status"]
end

subgraph group_generation["Series generation"]
  node_request["Generation request"]
  node_generator["Series generator"]
  node_engine["Parallel arbiter"]
  node_repairer["Conflict repair"]
  node_triples["Triple index<br/>[TripleIndex.java]"]
  node_grid["Series grid<br/>[SeriesGrid.java]"]
  node_conflict["Compatibility conflict"]
  node_result["Generation result"]
end

subgraph group_outputs["Cards and output"]
  node_series["Generated series<br/>[TombolaSeries.java]"]
  node_card["Tombola cards<br/>[TombolaCard.java]"]
  node_pdf["PDF writer"]
  node_verifyreport["Verification report writer"]
  node_cli["CLI runner"]
end

node_browser(("Browser user"))
node_pdfdownload["PDF download"]

node_browser -->|"uses"| node_ui
node_ui -->|"calls API"| node_webapi
node_polling -->|"polls status"| node_webapi
node_browser -->|"tracks job"| node_polling
node_browser -->|"submits verification"| node_webapi
node_webapi -->|"starts and queries"| node_jobservice
node_webapi -->|"returns status"| node_jobstatus
node_webapi -->|"reads for verification"| node_series
node_jobservice -->|"generates batch"| node_generator
node_jobservice -->|"creates request"| node_request
node_jobservice -->|"writes PDF"| node_pdf
node_jobservice -->|"uses result"| node_result
node_jobservice -->|"updates status"| node_jobstatus
node_jobservice -->|"retains series"| node_series
node_jobservice -->|"serves completed file"| node_pdfdownload
node_generator -->|"runs batch"| node_engine
node_engine -->|"repairs candidates"| node_repairer
node_engine -->|"checks triples"| node_triples
node_engine -->|"processes grids"| node_grid
node_engine -->|"uses limits"| node_request
node_engine -->|"returns result"| node_result
node_engine -->|"records conflicts"| node_conflict
node_engine -->|"accepts series"| node_series
node_repairer -->|"repairs grid"| node_grid
node_repairer -->|"checks triples"| node_triples
node_grid -->|"builds series"| node_series
node_grid -->|"builds cards"| node_card
node_pdf -->|"renders series"| node_series
node_pdf -->|"renders cards"| node_card
node_browser -.->|"runs optionally"| node_cli
node_cli -->|"generates series"| node_generator
node_cli -->|"writes PDF"| node_pdf
node_cli -->|"writes report"| node_verifyreport

click node_ui "https://github.com/dcsergio/tombojava/blob/main/src/main/resources/templates/index.html"
click node_polling "https://github.com/dcsergio/tombojava/blob/main/src/main/resources/static/js/job-polling.js"
click node_webapi "https://github.com/dcsergio/tombojava/blob/main/src/main/java/it/sdc/tombojava/web/GenerationJobController.java"
click node_home "https://github.com/dcsergio/tombojava/blob/main/src/main/java/it/sdc/tombojava/web/HomeController.java"
click node_jobservice "https://github.com/dcsergio/tombojava/blob/main/src/main/java/it/sdc/tombojava/job/GenerationJobService.java"
click node_jobstatus "https://github.com/dcsergio/tombojava/blob/main/src/main/java/it/sdc/tombojava/job/GenerationJobStatus.java"
click node_request "https://github.com/dcsergio/tombojava/blob/main/src/main/java/it/sdc/tombojava/tombola/GenerationRequest.java"
click node_generator "https://github.com/dcsergio/tombojava/blob/main/src/main/java/it/sdc/tombojava/tombola/TombolaSeriesGenerator.java"
click node_engine "https://github.com/dcsergio/tombojava/blob/main/src/main/java/it/sdc/tombojava/tombola/ParallelSeriesEngine.java"
click node_repairer "https://github.com/dcsergio/tombojava/blob/main/src/main/java/it/sdc/tombojava/tombola/SeriesRepairer.java"
click node_triples "https://github.com/dcsergio/tombojava/blob/main/src/main/java/it/sdc/tombojava/tombola/TripleIndex.java"
click node_grid "https://github.com/dcsergio/tombojava/blob/main/src/main/java/it/sdc/tombojava/tombola/SeriesGrid.java"
click node_conflict "https://github.com/dcsergio/tombojava/blob/main/src/main/java/it/sdc/tombojava/tombola/CompatibilityConflict.java"
click node_result "https://github.com/dcsergio/tombojava/blob/main/src/main/java/it/sdc/tombojava/tombola/GenerationResult.java"
click node_series "https://github.com/dcsergio/tombojava/blob/main/src/main/java/it/sdc/tombojava/tombola/TombolaSeries.java"
click node_card "https://github.com/dcsergio/tombojava/blob/main/src/main/java/it/sdc/tombojava/tombola/TombolaCard.java"
click node_pdf "https://github.com/dcsergio/tombojava/blob/main/src/main/java/it/sdc/tombojava/tombola/TombolaPdfWriter.java"
click node_verifyreport "https://github.com/dcsergio/tombojava/blob/main/src/main/java/it/sdc/tombojava/tombola/TombolaVerificationReportWriter.java"
click node_cli "https://github.com/dcsergio/tombojava/blob/main/src/main/java/it/sdc/tombojava/cli/TombojavaCliRunner.java"

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_ui,node_polling,node_webapi,node_home,node_browser toneBlue
class node_jobservice,node_jobstatus toneAmber
class node_request,node_generator,node_engine,node_repairer,node_triples,node_grid,node_conflict,node_result toneMint
class node_series,node_card,node_pdf,node_verifyreport,node_cli toneRose
class node_pdfdownload toneIndigo
```

## Components

### Web interface

- [Tombola UI](https://github.com/dcsergio/tombojava/blob/main/src/main/resources/templates/index.html): `src/main/resources/templates/index.html`
- [Job polling](https://github.com/dcsergio/tombojava/blob/main/src/main/resources/static/js/job-polling.js): `src/main/resources/static/js/job-polling.js`
- [Job API](https://github.com/dcsergio/tombojava/blob/main/src/main/java/it/sdc/tombojava/web/GenerationJobController.java): `src/main/java/it/sdc/tombojava/web/GenerationJobController.java`
- [Home route](https://github.com/dcsergio/tombojava/blob/main/src/main/java/it/sdc/tombojava/web/HomeController.java): `src/main/java/it/sdc/tombojava/web/HomeController.java`

### Job processing

- [Generation jobs](https://github.com/dcsergio/tombojava/blob/main/src/main/java/it/sdc/tombojava/job/GenerationJobService.java): `src/main/java/it/sdc/tombojava/job/GenerationJobService.java`
- [Job state and status](https://github.com/dcsergio/tombojava/blob/main/src/main/java/it/sdc/tombojava/job/GenerationJobStatus.java): `src/main/java/it/sdc/tombojava/job/GenerationJobStatus.java`

### Series generation

- [Generation request](https://github.com/dcsergio/tombojava/blob/main/src/main/java/it/sdc/tombojava/tombola/GenerationRequest.java): `src/main/java/it/sdc/tombojava/tombola/GenerationRequest.java`
- [Series generator](https://github.com/dcsergio/tombojava/blob/main/src/main/java/it/sdc/tombojava/tombola/TombolaSeriesGenerator.java): `src/main/java/it/sdc/tombojava/tombola/TombolaSeriesGenerator.java`
- [Parallel arbiter](https://github.com/dcsergio/tombojava/blob/main/src/main/java/it/sdc/tombojava/tombola/ParallelSeriesEngine.java): `src/main/java/it/sdc/tombojava/tombola/ParallelSeriesEngine.java`
- [Conflict repair](https://github.com/dcsergio/tombojava/blob/main/src/main/java/it/sdc/tombojava/tombola/SeriesRepairer.java): `src/main/java/it/sdc/tombojava/tombola/SeriesRepairer.java`
- [Triple index](https://github.com/dcsergio/tombojava/blob/main/src/main/java/it/sdc/tombojava/tombola/TripleIndex.java): `src/main/java/it/sdc/tombojava/tombola/TripleIndex.java`
- [Series grid](https://github.com/dcsergio/tombojava/blob/main/src/main/java/it/sdc/tombojava/tombola/SeriesGrid.java): `src/main/java/it/sdc/tombojava/tombola/SeriesGrid.java`
- [Compatibility conflict](https://github.com/dcsergio/tombojava/blob/main/src/main/java/it/sdc/tombojava/tombola/CompatibilityConflict.java): `src/main/java/it/sdc/tombojava/tombola/CompatibilityConflict.java`
- [Generation result](https://github.com/dcsergio/tombojava/blob/main/src/main/java/it/sdc/tombojava/tombola/GenerationResult.java): `src/main/java/it/sdc/tombojava/tombola/GenerationResult.java`

### Cards and output

- [Generated series](https://github.com/dcsergio/tombojava/blob/main/src/main/java/it/sdc/tombojava/tombola/TombolaSeries.java): `src/main/java/it/sdc/tombojava/tombola/TombolaSeries.java`
- [Tombola cards](https://github.com/dcsergio/tombojava/blob/main/src/main/java/it/sdc/tombojava/tombola/TombolaCard.java): `src/main/java/it/sdc/tombojava/tombola/TombolaCard.java`
- [PDF writer](https://github.com/dcsergio/tombojava/blob/main/src/main/java/it/sdc/tombojava/tombola/TombolaPdfWriter.java): `src/main/java/it/sdc/tombojava/tombola/TombolaPdfWriter.java`
- [Verification report writer](https://github.com/dcsergio/tombojava/blob/main/src/main/java/it/sdc/tombojava/tombola/TombolaVerificationReportWriter.java): `src/main/java/it/sdc/tombojava/tombola/TombolaVerificationReportWriter.java`
- [CLI runner](https://github.com/dcsergio/tombojava/blob/main/src/main/java/it/sdc/tombojava/cli/TombojavaCliRunner.java): `src/main/java/it/sdc/tombojava/cli/TombojavaCliRunner.java`

### Other components

- **Browser user**
- **PDF download**

## Connections

- Browser user → Tombola UI: uses (evidence: `README.md`)
- Tombola UI → Job API: calls API (evidence: `README.md`)
- Job polling → Job API: polls status (evidence: `README.md`)
- Browser user → Job polling: tracks job (evidence: `README.md`)
- Browser user → Job API: submits verification (evidence: `README.md`)
- Job API → Generation jobs: starts and queries (evidence: `src/main/java/it/sdc/tombojava/web/GenerationJobController.java`)
- Job API → Job state and status: returns status (evidence: `src/main/java/it/sdc/tombojava/web/GenerationJobController.java`)
- Job API → Generated series: reads for verification (evidence: `src/main/java/it/sdc/tombojava/web/GenerationJobController.java`)
- Generation jobs → Series generator: generates batch (evidence: `src/main/java/it/sdc/tombojava/job/GenerationJobService.java`)
- Generation jobs → Generation request: creates request (evidence: `src/main/java/it/sdc/tombojava/job/GenerationJobService.java`)
- Generation jobs → PDF writer: writes PDF (evidence: `src/main/java/it/sdc/tombojava/job/GenerationJobService.java`)
- Generation jobs → Generation result: uses result (evidence: `src/main/java/it/sdc/tombojava/job/GenerationJobService.java`)
- Generation jobs → Job state and status: updates status (evidence: `src/main/java/it/sdc/tombojava/job/GenerationJobService.java`)
- Generation jobs → Generated series: retains series (evidence: `src/main/java/it/sdc/tombojava/job/GenerationJobService.java`)
- Generation jobs → PDF download: serves completed file (evidence: `src/main/java/it/sdc/tombojava/job/GenerationJobService.java`)
- Series generator → Parallel arbiter: runs batch (evidence: `src/main/java/it/sdc/tombojava/tombola/TombolaSeriesGenerator.java`)
- Parallel arbiter → Conflict repair: repairs candidates (evidence: `src/main/java/it/sdc/tombojava/tombola/ParallelSeriesEngine.java`)
- Parallel arbiter → Triple index: checks triples (evidence: `src/main/java/it/sdc/tombojava/tombola/ParallelSeriesEngine.java`)
- Parallel arbiter → Series grid: processes grids (evidence: `src/main/java/it/sdc/tombojava/tombola/ParallelSeriesEngine.java`)
- Parallel arbiter → Generation request: uses limits (evidence: `src/main/java/it/sdc/tombojava/tombola/ParallelSeriesEngine.java`)
- Parallel arbiter → Generation result: returns result (evidence: `src/main/java/it/sdc/tombojava/tombola/ParallelSeriesEngine.java`)
- Parallel arbiter → Compatibility conflict: records conflicts (evidence: `src/main/java/it/sdc/tombojava/tombola/ParallelSeriesEngine.java`)
- Parallel arbiter → Generated series: accepts series (evidence: `src/main/java/it/sdc/tombojava/tombola/ParallelSeriesEngine.java`)
- Conflict repair → Series grid: repairs grid (evidence: `src/main/java/it/sdc/tombojava/tombola/SeriesRepairer.java`)
- Conflict repair → Triple index: checks triples (evidence: `src/main/java/it/sdc/tombojava/tombola/SeriesRepairer.java`)
- Series grid → Generated series: builds series (evidence: `src/main/java/it/sdc/tombojava/tombola/SeriesGrid.java`)
- Series grid → Tombola cards: builds cards (evidence: `src/main/java/it/sdc/tombojava/tombola/SeriesGrid.java`)
- PDF writer → Generated series: renders series (evidence: `src/main/java/it/sdc/tombojava/tombola/TombolaPdfWriter.java`)
- PDF writer → Tombola cards: renders cards (evidence: `src/main/java/it/sdc/tombojava/tombola/TombolaPdfWriter.java`)
- Browser user → CLI runner: runs optionally (evidence: `README.md`)
- CLI runner → Series generator: generates series (evidence: `src/main/java/it/sdc/tombojava/cli/TombojavaCliRunner.java`)
- CLI runner → PDF writer: writes PDF (evidence: `src/main/java/it/sdc/tombojava/cli/TombojavaCliRunner.java`)
- CLI runner → Verification report writer: writes report (evidence: `src/main/java/it/sdc/tombojava/cli/TombojavaCliRunner.java`)
