diff --git a/README.md b/README.md
new file mode 100644
index 0000000..236cf72
--- /dev/null
+++ b/README.md
@@ -0,0 +1,78 @@
+# szpitale-graph
+
+Graph DB project. Polish hospitals data in Neo4j.
+
+Two-layer architecture. Ingest sources → canonical JSON → load into Neo4j.
+
+## Stack
+
+- Java 21
+- Maven (use `./mvnw` wrapper)
+- Spring Boot 3.4.4 + Spring Shell
+- Neo4j 5
+- JUnit 5 + Testcontainers
+
+## Key commands
+
+From `szpitale-graph/`:
+
+```bash
+./mvnw -q compile       # compile
+./mvnw -q test          # all tests
+./mvnw -q test -Dtest=ClassName  # single test
+./mvnw -q verify        # full verify
+java -jar target/szpitale-graph.jar ingest --voivodeship <voiv>   # layer 1
+java -jar target/szpitale-graph.jar load   --voivodeship <voiv>   # layer 2
+```
+
+Neo4j:
+
+```bash
+docker compose up -d                    # start Neo4j (UI :7474, Bolt :7687)
+docker compose down -v                  # stop + remove volumes
+```
+
+## Architecture
+
+```
+ingest → canonical/*.json → load → Neo4j
+```
+
+**Layer 1 (ingest):** Source parsing, normalization, deduplication. No Neo4j dependency.
+**Layer 2 (load):** Canonical JSON → UNWIND/MERGE into Neo4j. No network dependency.
+
+Canonical output: `canonical/<voivodeship>.json` or `canonical/all.json`.
+
+## Source data
+
+Input markdown files: `research-<voivodeship>.md`. Table format:
+
+```
+| Funkcja | Imię i nazwisko | Afiliacja partyjna | Źródło (URL) |
+```
+
+Every cell must have an `https://...` URL.
+
+## 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`, `VoivodeshipSource` |
+| `ingest/normalize/` | `NameNormalizer`, `PartyNormalizer`, `Deduplicator` |
+| `load/` | `LoadCommand`, `CanonicalReader`, `GraphSchema`, `GraphLoader`, `GraphValidator` |
+| `SzpitaleGraphApplication.java` | `@SpringBootApplication` entry point |
+
+## 16 voivodeships
+
+Supported regions: all Polish voivodeships. Start with `research-<voiv>.md` files, then run `ingest` + `load`.
+
+## Dev
+
+Test-driven development. TDD cycle: red → green → refactor. Tests mirror main package structure.
+
+Integrations tests use Testcontainers with Neo4j container.