Szpitale-graph/AGENTS.md

Szpitale-graph — agent instructions

TL;DR: cd szpitale-graph && ./mvnw -q compile (wrapper, not mvn). Build lives in szpitale-graph/. Neo4j via docker compose up -d from same dir. CLAUDE.md has full TDD rules and PLAN2.md has the execution backlog. This file covers what CLAUDE.md doesn't.

Project location & structure

• Application root: szpitale-graph/ (not the repo root).
• All Maven commands run from szpitale-graph/ using ./mvnw.
• Source: src/main/java/com/developx/szpitale/
• Tests: src/test/java/com/developx/szpitale/ (mirror packages)

Key commands

Task	Command
Compile	./mvnw -q compile
Test single	./mvnw -q test -Dtest=ClassName
All tests	./mvnw -q test
Verify	./mvnw -q verify
Run CLI	java -jar target/szpitale-graph.jar
Neo4j up	docker compose up -d
Neo4j down	docker compose down -v

Architecture (two layers, JSON between them)

ingest (layer 1) ──canonical/*.json──→ load (layer 2 → Neo4j)

• Ingest = source parsing + normalisation + dedup. No Neo4j dependency.
• Load = canonical JSON → UNWIND/MERGE into Neo4j. No network dependency.
• Canonical files: canonical/<voivodeship>.json or canonical/all.json.

Code layout (src/main/java/com/developx/szpitale/)

Package	Purpose
model/	CanonicalDataset, Hospital, Person, Affiliation, Role, Mandate, RawHospitalRecord
model/enums/	LegalForm, RoleType, MandateType, ConfidenceLevel, RoleStatus, AffiliationType, OrganType, SupervisoryBodyType
ingest/	IngestCommand, CanonicalWriter, IngestResults
ingest/source/	MarkdownRegistrySource (parses research-*.md), VoivodeshipSource (interface)
ingest/normalize/	NameNormalizer, PartyNormalizer, Deduplicator
load/	LoadCommand, CanonicalReader, GraphSchema, GraphLoader, GraphValidator
SzpitaleGraphApplication.java	@SpringBootApplication entry point

Data format

Research files: research-<voivodeship>.md (e.g. research-podlaskie.md). Table header:

| Funkcja | Imię i nazwisko | Afiliacja partyjna | Źródło (URL) |

Every cell must have an https://... URL. No URL = BRAK_DANYCH or skip.

Current state: build is broken (T1 blocker)

Deduplicator.java:75 — groups is Map<String, List<Person>> but code puts List<String>. Fix needed before any test can run. See PLAN2.md §11, task T1.

Dependencies

• Spring Boot 3.4.4 (spring-shell, neo4j-starter, web)
• Jackson (databind + jsr310)
• Jsoup 1.18.3 (HTML/Mobile Markdown parsing)
• Commons Text 1.12.0 (Jaro-Winkler fuzzy match)
• Commons CSV 1.12.0 (reports)
• Lombok: declared in pom.xml but has NO <version> — add one if you modify it
• Spring Shell: declared in pom.xml with empty line — needs <version> if you enable it
• Testcontainers Neo4j 1.20.4 + JUnit Jupiter

Test conventions

• Tests mirror main package structure.
• Class-name based: ./mvnw -q test -Dtest=NameNormalizerTest
• Integration tests (*IT) use @Testcontainers + Neo4jContainer.
• Fixture files → src/test/resources/fixtures/

Git / checkpoint protocol

PLAN2.md mandates: one checkpoint commit per task (-m "T<n>: descript [checkpoint]"). The local-agent-progress.json file tracks task states. On conflicts, git log is the source of truth (PLAN2.md §13.5).

Getting a new voivodeship

1. Deep-research → produce research-<voiv>.md in same table format as research-podlaskie.md
2. Place file in old/ or a research/ directory
3. Run ingest --voivodeship <voiv> → generates canonical JSON
4. Run load --voivodeship <voiv> → pushes to Neo4j

No code changes needed to add a new region.