ArchiTools/src/modules/parcel-sync/SKILLS.md

ParcelSync / eTerra GIS — Skills & Context

This file is the single source of truth for any AI assistant working on the ParcelSync module, eTerra integration, or GIS features. Read this FIRST before touching any code in this area.

---

Module Overview

ParcelSync connects to Romania's eTerra / ANCPI national cadastral system to fetch, store, enrich, and export parcel (land + building) data. All GIS data lives in a local PostGIS database via Prisma ORM.

Key paths:

Area	Path
Module root	src/modules/parcel-sync/
Components	src/modules/parcel-sync/components/parcel-sync-module.tsx (~4100 lines, single file)
Services	src/modules/parcel-sync/services/
API routes	src/app/api/eterra/ (20+ route files)
Types	src/modules/parcel-sync/types.ts
DB models	prisma/schema.prisma → GisFeature, GisSyncRun, GisUat
Layer catalog	services/eterra-layers.ts — 23 layers, 4 categories
Static UAT list	public/uat.json (~3000 entries, SIRUTA + name only)

---

Architecture

eTerra API Client (services/eterra-client.ts, ~1000 lines)

• Auth: form-post login → JSESSIONID cookie jar (axios-cookiejar-support)
• Session cache: keyed by credential hash, 9-minute TTL, auto-relogin on 401/redirect
• Two API surfaces:
  • ArcGIS REST (/api/map/rest/{endpoint}/layer/{name}/query) — spatial queries, geometry
  • Application API (/api/immovable/..., /api/immApps/..., /api/adm/nomen/...) — business data
• Pagination: maxRecordCount=1000, fallback page sizes (500, 200)
• Key methods:
  • listLayer() / fetchAllLayer() / fetchAllLayerByWhere() — ArcGIS layer queries
  • countLayer() — feature count
  • getLayerFieldNames() — discover available fields
  • searchImmovableByIdentifier() — parcel search by cadastral number
  • fetchDocumentationData() — CF, owners (partTwoRegs tree)
  • fetchImmovableParcelDetails() — area, intravilan, use categories
  • fetchImmovableListByAdminUnit() — all immovables in a UAT (paginated, Spring Boot Page format)
  • fetchCounties() — all counties from nomenclature (/api/adm/nomen/COUNTY/list)
  • fetchAdminUnitsByCounty(nomenPk) — UATs per county (/api/adm/nomen/ADMINISTRATIVEUNIT/filterByParent/{pk})
  • fetchNomenByPk(pk) — single nomenclature entry

Session Management (services/session-store.ts)

• Global singleton (one shared session for the whole app)
• Stores username + password in memory only
• Tracks active job IDs (blocks disconnect while jobs run)
• getSessionCredentials() — used by all API routes

Health Check (services/eterra-health.ts)

• Pings eterra.ancpi.ro every 3 minutes
• Detects maintenance by keywords in HTML response
• Blocks login attempts when down
• UI shows amber "Mentenanță" state

---

Database Models

GisUat (UAT registry)

siruta     String  @id      — SIRUTA code (NOT eTerra nomenPk!)
name       String           — UAT name (from uat.json)
county     String?          — County name (populated via PATCH /api/eterra/uats)
workspacePk Int?            — eTerra county workspace ID (= county nomenPk)

CRITICAL: eTerra nomenPk ≠ SIRUTA. The nomenclature API uses nomenPk internally, but our DB keys on SIRUTA codes from uat.json. Matching is done by name or by resolving WORKSPACE_ID from ArcGIS layer features.

GisFeature (parcel/building data)

id             String    @id @default(uuid())
layerId        String    — e.g. "TERENURI_ACTIVE", "CLADIRI_ACTIVE"
siruta         String    — UAT this feature belongs to
objectId       Int       — eTerra OBJECTID (negative = no-geometry record)
cadastralRef   String?   — National cadastral reference
areaValue      Float?    — Area in sqm
isActive       Boolean
attributes     Json      — All ArcGIS attributes (WORKSPACE_ID, ADMIN_UNIT_ID, etc.)
geometry       Json?     — EsriGeometry { rings: number[][][] }
geometrySource String?   — "NO_GEOMETRY" for parcels without GIS geometry
enrichment     Json?     — Scraped data: NR_CAD, NR_CF, PROPRIETARI, INTRAVILAN, etc.
enrichedAt     DateTime? — When enrichment was fetched
@@unique([layerId, objectId])

GisSyncRun (sync history)

siruta, layerId, status, totalRemote, totalLocal, newFeatures, removedFeatures, etc.

---

Key Flows

1. UAT Selection & Autocomplete

• On mount: GET /api/eterra/uats → loads all UATs from DB (fast, no eTerra)
• If DB empty: seeds via POST /api/eterra/uats from public/uat.json
• Client-side filter: diacritics-insensitive, matches SIRUTA prefix or name/county substring
• Dropdown shows: name – county + local feature count badge + SIRUTA code
• On select: sets siruta + workspacePk state

2. County Population (PATCH /api/eterra/uats)

• Phase 1: UATs with workspacePk already → instant lookup via fetchCounties() map
• Phase 2: Enumerate all counties → fetchAdminUnitsByCounty() per county → match by code then name
• Auto-triggered on first eTerra connection when >50% UATs lack county
• ~43 API calls total (1 counties + 42 per-county)
• Name matching: NFD normalize, strip diacritics, uppercase

3. Workspace Resolution

• workspacePk = eTerra county identifier (= county nomenPk from nomenclature)
• Resolved lazily: query 1 feature from TERENURI_ACTIVE → read WORKSPACE_ID attribute
• Cached in-memory + persisted to GisUat.workspacePk
• Resolution chain: explicit param → GisUat DB → ArcGIS layer query

4. Layer Sync (services/sync-service.ts)

• Background job: fetch all features from an ArcGIS layer for a SIRUTA
• Uses UAT boundary geometry (from LIMITE_UAT) as spatial filter for dynamic layers
• Stores features in GisFeature with full geometry
• Progress tracking via progress-store.ts (2s polling)

5. Enrichment Pipeline (services/enrich-service.ts)

• Per-feature: hits eTerra /api/immovable/list to extract detailed data
• Stored in GisFeature.enrichment JSONB:
  • NR_CAD, NR_CF, NR_CF_VECHI, NR_TOPO
  • PROPRIETARI, PROPRIETARI_VECHI (semicolon-separated)
  • SUPRAFATA, INTRAVILAN, CATEGORIE_FOLOSINTA
  • HAS_BUILDING, BUILD_LEGAL
  • ADRESA, SOLICITANT

6. Parcel Search (POST /api/eterra/search)

• Input: SIRUTA + cadastral number(s)
• Resolves workspace, then calls:
  1. searchImmovableByIdentifier() — find immovable
  2. fetchDocumentationData() — CF, owners (active/cancelled via nodeStatus tree)
  3. fetchImmovableParcelDetails() — area, intravilan, use categories
  4. fetchImmAppsByImmovable() → fetchParcelFolosinte() — application data
• Returns ParcelDetail[] with full property info

7. No-Geometry Sync (services/no-geom-sync.ts)

• Finds eTerra immovables that have NO GIS geometry (no polygon in TERENURI_ACTIVE)
• Cross-references immovable list against remote ArcGIS features
• Stores as GisFeature with geometry=null, objectId=-immovablePk
• Quality gate: must be active + hasLandbook + has identification/area

8. Export

• GeoPackage (services/gpkg-export.ts): EPSG:3844 → EPSG:4326 reprojection
• Export bundle (/api/eterra/export-bundle): ZIP with CSV + GPKG
• Local export (/api/eterra/export-local): from local DB

---

API Routes Reference

Route	Method	Purpose
/api/eterra/uats	GET	All UATs from DB (with local feature counts)
/api/eterra/uats	POST	Seed DB from uat.json
/api/eterra/uats	PATCH	Populate county from eTerra nomenclature
/api/eterra/login	POST	Connect to eTerra
/api/eterra/session	GET/DELETE	Session status / disconnect
/api/eterra/health	GET	eTerra platform health
/api/eterra/search	POST	Search parcels by cadastral number
/api/eterra/search-owner	POST	Search by owner name
/api/eterra/layers	GET	Available layers + field names
/api/eterra/count	POST	Count features in layer
/api/eterra/sync	POST	Start layer sync job
/api/eterra/sync-background	POST	Background sync
/api/eterra/sync-status	GET	Sync job progress
/api/eterra/progress	GET	Generic job progress
/api/eterra/features	GET	Query local features
/api/eterra/db-summary	GET	Aggregate stats all UATs
/api/eterra/uat-dashboard	GET	Per-UAT analytics
/api/eterra/export-bundle	POST	Export ZIP (CSV + GPKG)
/api/eterra/export-layer-gpkg	POST	Export single layer GPKG
/api/eterra/export-local	POST	Export from local DB
/api/eterra/no-geom-scan	POST	Scan for no-geometry parcels
/api/eterra/no-geom-debug	POST	Debug no-geom data
/api/eterra/setup-postgis	POST	Initialize PostGIS extensions

---

Critical Gotchas

1. nomenPk ≠ SIRUTA: eTerra's internal nomenclature PKs are NOT SIRUTA codes. Never assume they're the same.
2. workspacePk = county nomenPk: The WORKSPACE_ID from ArcGIS layers equals the county's nomenclature PK from fetchCounties().
3. Session TTL: eTerra sessions expire after ~10 minutes. Client has 9-minute cache TTL + auto-relogin.
4. Maintenance windows: eTerra goes down regularly. Health check detects this and blocks operations.
5. ArcGIS maxRecordCount=1000: Always paginate with resultOffset/resultRecordCount. Page size fallbacks: 1000 → 500 → 200.
6. Admin field auto-discovery: Different layers use different field names for SIRUTA (ADMIN_UNIT_ID, SIRUTA, UAT_ID, etc.). Always use findAdminField() / buildWhere().
7. LIMITE_UAT endpoint is "all": Unlike other layers (endpoint "aut"), LIMITE_UAT uses the "all" endpoint — no workspace context needed.
8. No-geometry parcels use negative objectId: objectId = -immovablePk to avoid collision with real ArcGIS OBJECTIDs.
9. Spring Boot Page responses: Some eTerra APIs return {content: [...], totalPages: N} instead of flat arrays. Always use unwrapArray() helper.
10. Geometry format: EsriGeometry { rings: number[][][] } in EPSG:3844 (Stereo70). Reproject to EPSG:4326 for GeoPackage export.
11. Owner tree parsing: Documentation API returns owners as a tree (C→A→I→P nodes). Check nodeStatus === -1 up the parent chain to detect radiated/cancelled owners.
12. Local UatEntry type: The component defines its own UatEntry type at the top of parcel-sync-module.tsx — this shadows the one in types.ts. Keep both in sync.

---

Test UAT

Feleacu — SIRUTA 57582, ~30k immovables, ~8k GIS features. Used as the primary test UAT.

---

Last Updated

2026-03-22 — Added county population via nomenclature API, local feature count in UAT dropdown.