# Architecture

This service is the accepted target design for replacing the legacy
Overpass-based `osm-country-scraper` with a standalone Geofabrik PBF-based OSM
lead ingestion and reconciliation system.

The detailed design is preserved in the reviewed Phase 1/1.5 documents:

- `noco-compatibility-contract.md`
- `existing-osm-lead-adoption.md`
- `stale-lead-safety-policy.md`
- `replacement-architecture-plan.md`
- `phase-1-findings.md`

## Target Design Summary

- Use regional Geofabrik `.osm.pbf` extracts instead of Overpass.
- Refresh regions monthly.
- Keep the existing NocoDB lead table schema unchanged.
- Use read-only PostgreSQL access for scalable reads of existing Noco rows.
- Use the NocoDB API for all future mutations.
- Store region-scoped source presence, profile/version-scoped eligibility,
  mappings, provenance, reconciliation state, stale evidence, and audit reports
  in a PostgreSQL/PostGIS sidecar.
- Adopt existing OSM leads in place rather than recreating them.
- Separate OSM source presence from business profile eligibility.
- Fail closed for unknown ownership or protected workflow state.
- Defer stale deletion until Phase 2D approval.
- Add MCP only in Phase 2E.

## Implemented Phase 2A.5 Boundary

The current Noco read boundary is intentionally smaller than the final target:

- `NocoReadRepository` exposes only exact schema evidence and bounded keyset pages.
- Fixture and injected PostgreSQL adapters return immutable detached scalar rows.
- The PostgreSQL adapter derives its projection from the fingerprinted schema and
  verifies read-only transaction state before row queries.
- The adoption scanner combines normalized source rows, Noco read evidence, and
  existing active-mapping evidence into deterministic non-executable reports.
- Workflow and non-OSM ownership signals are reported as protection evidence.
- Input, page, fanout, candidate, and report sizes are bounded and fail closed.

No Noco write repository, sidecar write adapter, active-mapping creator,
reconciliation executor, production connection, scheduler, or deployment is
part of Phase 2A.5.

## Planned Module Boundaries

- Geofabrik catalog
- Download validation/cache
- Osmium filtering
- PBF parser
- Category profiles
- Normalization
- Business deduplication
- Noco contract
- Noco read repository
- Noco write repository
- Adoption scanner
- Workflow protection
- Stale policy
- Sidecar store
- Reconciliation engine
- Scheduler
- Audit reporting
- Future MCP interface