# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Overview

Ruian2UirConverter is a PHP library that converts RUIAN XML data to UIR-compatible format. RUIAN (Registr územní identifikace, adres a nemovitostí) is Czech Republic's registry of territorial identification, addresses and real estate. UIR was previous version of that system, which was replaced by RUIAN, but internal systems still rely on UIR format.

This app is normally used to download and convert ruian xml to sql files which are imported into database and later used as database for geomapi service which provides JSON API for address search and suggestions.

## Common Development Commands

### Code Quality
```bash
# Run PHP CS Fixer (code style) for whole project 
composer cs
# or
vendor/bin/php-cs-fixer fix

# Run PHPStan (static analysis) for whole project
composer stan
# or
vendor/bin/phpstan analyse

# Run both code style and static analysis for whole project (run after completing a feature)
composer pre-commit
```

### Application Commands
All commands are run through the `console` script:

```bash
# Convert RUIAN XML to UIR format (output format is based on parameters provided)
php console convert [path_to_file_or_directory]

# Explore XML structure (output fields and values of the first record in the xml file)
php console explore [path_to_file_or_directory]

# Get list of files to download from RUIAN (text file, one url per line)
php console get-file-list full > links.txt
php console get-file-list diff --from-date=2023-01-01

# Get and convert codebooks (for values such as heating source and such)
php console get-codebooks [optional_path_to_file]

# Convert coordinates from S-JTSK to GPS
php console convert-coords [coordinates]
```

### Testing
`vendor/bin/phpunit`

## Architecture

### Core Components

**Symfony Console Application**: Entry point through `console` script with Symfony DI container

**Converter System**: 
- Each RUIAN entity type has its own converter (Address, Building, Municipality, etc.)
- Converters implement `ConverterInterface` and are auto-tagged as `ruian_converter`
- Located in `src/Converter/` with entity-specific converters

**Command Structure**:
- `src/Command/` - Symfony console commands
- `src/Command/Helper/` - Shared command utilities (FileDownloader, FileResolver)

**Data Processing Pipeline**:
1. **Input**: RUIAN XML files (compressed .gz format)
2. **Conversion**: XML → Internal representation → UIR format
3. **Output**: SQL statements, plain text, or multiple files

### Key Architectural Patterns

**Dependency Injection**: Uses Symfony DI with YAML configuration (`config/services.yml`)

**Strategy Pattern**: Multiple formatters (PlainText, Sql) and writers (MultipleFiles, PrintOut)

**Coordinate Transformation**: Converts from Krovak projection (EPSG:5514) to WGS84 (EPSG:4326) using Proj4PHP

**Service Tags**: Auto-registration of converters and commands using Symfony service tags

### Data Models

**RUIAN Entity Types** (mapped in `services.yml`):
- AD: Address (Adresní místo) - GPS coordinates, house number, postal code, building/street references
- KU: CadastralArea (Katastrální území) - cadastral territory with GPS boundaries
- MC: CityPart (Městská část) - city district with administrative boundaries
- KR: County (Kraj) - region/county level administrative division
- OB: Municipality (Obec) - municipality/town with administrative data
- CO: MunicipalityPart (Část obce) - part of municipality/village
- SO: Building (Stavební objekt) - building with construction details, utilities connections
- PA: Plot (Parcela) - land parcel with area and land use type
- MP: PragueDistrict (Městský obvod Praha) - Prague-specific administrative district
- OK: Region (Okres) - district level administrative division  
- UL: Street (Ulice) - street or public space within municipality

**Entity Relationships**: Each entity has hierarchical relationships (e.g., Address → Building → Plot → CadastralArea → Municipality → Region → County). See detailed relationship mapping in [doc/RUIAN.md](doc/RUIAN.md).

### File Structure

- `src/Converter/` - Entity converters and field processors
- `src/Converter/Field/` - Coordinate and geometry field handlers
- `src/Converter/Result/` - Result objects (AddRecord, RemoveRecord, etc.)
- `src/Writer/` - Output writers
- `src/Formatter/` - Output formatters
- `config/services.yml` - Symfony DI configuration with RUIAN URLs and mappings
- Database schema files: `datovy_model.sql`, `uir-compat.sql`, `rmix-compat.sql`, `stat.sql`

## Data Processing

**URL Patterns**: Configured in `services.yml` for fetching RUIAN data:
- Full dataset URLs
- Incremental/diff URLs with date parameters
- Municipality-specific URLs
- Codebook URLs

**Coordinate System**: Transforms coordinates from Czech national grid (S-JTSK/Krovak East North) to WGS84

## Testing

- Framework: PHPUnit 12.3.x.
- Run tests: `composer test` or `vendor/bin/phpunit --colors=always`.
- Coverage metadata: every test must declare covered code via attributes (e.g., `#[CoversClass(...)]`); enforced by PHPUnit config.
- Temporary files: tests write outputs under `var/test/` in the project tree; they create the directory if missing and clean up files they generate.

### What is covered now
- Formatters: `PlainText`, `Sql` (ADD/DEL paths, geometry handling, escaping).
- Writers: `MultipleFiles` (append behavior, filename), `PrintOut` (stdout line).
- Geometry/Conversion: `Point`, `GeometryField` WKT; `PointCoordinatesConverter` round‑trip tolerance test.

### Converter tests
- Planned once minimal real XML snippets are available; see `.codex/testing.md` for extraction tips using `xmllint`/`xmlstarlet`.

## RUIAN Data Structure

**Official Documentation**: http://www.cuzk.gov.cz/vfr (Czech only)
**Local Documentation**: [doc/RUIAN.md](doc/RUIAN.md) - Detailed entity descriptions and relationships
**XML Structure Examples**: [doc/structure.txt](doc/structure.txt) - Sample XML structures for each entity type
**Codebooks**: [doc/RUIAN-codebooks.yml](doc/RUIAN-codebooks.yml) - Value lists for enumerated fields

**Key RUIAN Concepts**:
- **Hierarchical Structure**: Entities follow Czech administrative division hierarchy
- **Temporal Data**: All entities have validity periods (`PlatiOd` - valid from)
- **GPS Coordinates**: Most entities include definičný bod (definition point) in S-JTSK projection
- **Codebooks**: Enumerated values for construction types, utilities, land use, etc.

**Building Properties** (key for address systems):
- Construction type, utilities connections (water, gas, sewage, heating)
- Number of floors, apartments, elevator presence
- GPS coordinates and parcela references

**Data Traceability**: Each entity can trace relationships to parent administrative divisions (Address can find its County through multiple paths)

## Development guidelines

### Test creation
- Each test much have a code coverage target using `Covers` phpunit annotation.
- Tests should be testdox output format friendly.

### General
- Code comments should be in Czech, cody itself in English.
- Use modern PHP features where possible.
