ArchiTools/docs/plans/002-architools-thin-client-review.md

Plan 002 — ArchiTools thin-client migration: review feedback from eterra.live side

Date: 2026-05-17 Reviewer: Claude session in /home/orchestrator/Code/eterra-live (Marius) Context: Reviews the "Faza 0..7" plan proposed by the architools claude that routes architools enrichment through eterra.live.

---

TL;DR — change of direction

The original plan made eterra.live the gateway for architools/planhub enrichment via POST /api/internal/enrich. This is the wrong boundary. The correct gateway is api.gis.ac (the gis-api service on shop), which is already designed for cross-app consumption (JWT + RLS + scope filtering, Hono on 10.10.10.84:3100, fronted by Traefik).

eterra.live is a single-instance Next.js end-user product. Putting architools' geoportal behind it makes eterra.live a SPOF — any deploy/restart breaks architools cadastre. The right model treats both architools AND eterra.live as peer consumers of api.gis.ac.

eterra.live already migrated to api.gis.ac for CfExtract (Sprint 2 Day 3-4, 2026-04-20). Same migration pattern applies to architools, just bigger surface area.

---

What's already in place (don't reinvent)

api.gis.ac exists in production:

• Repo: gitadmin/gis-api, local clone ~/Code/gis-api
• Stack: Next.js 16.1 + Hono 4 + Prisma 6.19 + Zod 4 + jose 6
• Auth: HS256 JWT today (GIS_API_DEV_JWT_SECRET) — migrating to Authentik OIDC before architools cutover (decision locked 2026-05-17)
• Claims: { sub, org_ids[], is_beletage_group, enrichment_scope: "none"|"basic"|"full", email? } — tenant claim being added
• RLS: withUserContext() sets app.user_id / org_ids / is_beletage_group / enrichment_scope per Postgres tx
• Live endpoints (under /api/v1/):
  • GET /me — claims echo
  • GET /parcela/:id — full GisFeature read
  • GET /search?q=&limit= — UAT + cadastralRef text search
  • GET/POST/PATCH /enrichment/cf* — CfExtract CRUD with RLS
  • GET /enrichment/catalog/:nrCadastral — catalog metadata
  • GET/POST /enrichment/cf/:id/pdf — MinIO PDF stream
• RLS test suite: 6 scenarios, asserts BOTH HTTP and direct-SQL paths (CI: .gitea/workflows/rls-test.yml)

What it does NOT have yet (gaps to close before architools cutover):

1. Authentik OIDC (HS256 still in use)
2. Live-fetch proxy endpoints to orchestrator (parcel/tech, parcel/units, building/tech, building/condo-owners, imm-apps)
3. Scope-based field filtering on /parcela/:id (currently leaks enrichment.PROPRIETARI regardless of scope)
4. tenant claim in JWT
5. CORS allowlist for cross-origin app calls
6. Per-tenant rate limiting
7. Audit log table (gis_meta.api_audit)

These will be added in a dedicated gis-api session before architools starts consuming. Full spec is in gis-api project memory (~/.claude/projects/-home-orchestrator-Code-gis-api/memory/):

• project_architools_planhub_plan.md — endpoints to add, in priority order
• feedback_jwt_authentik_decision.md — Authentik OIDC spec (scope mapping from LDAP groups)
• reference_orchestrator_endpoints.md — exact contracts for the 5 LAN endpoints to proxy
• reference_cross_app_architecture.md — the diagram + consumer responsibility matrix

---

Revised plan (replaces architools claude's Faza 0..7)

Faza A — Wait for gis-api gaps to close (managed in gis-api repo, ~3 days)

Driven from ~/Code/gis-api in a separate session. NOT architools' work to do, but architools depends on it. Deliverables:

1. PR1 (gis-api): Authentik OIDC support alongside HS256 (src/lib/auth.ts issuer-based dual path). Add tenant claim. Eterra.live keeps working on HS256 during the overlap. Provisioning needed in Authentik:
   • New OAuth2 application + provider with slug gis-api
   • Property mappings for enrichment_scope derived from LDAP groups:
     • beletage-staff → enrichment_scope=full, is_beletage_group=true
     • planhub-pro → full
     • planhub-free / no match → basic
     • missing claim → REJECT
   • tenant claim from aud (application slug)
2. PR2 (gis-api): 5 proxy endpoints + scope filter on /parcela/:id + CORS allowlist:

   POST /api/v1/parcel/tech              → orchestrator POST /api/v1/parcel/tech
   POST /api/v1/parcel/units/fetch       → orchestrator POST /api/v1/parcel-units/fetch
   POST /api/v1/parcel/imm-apps          → orchestrator POST /api/v1/imm-apps
   POST /api/v1/building/tech            → orchestrator POST /api/v1/building/tech
   POST /api/v1/building/condo-owners    → orchestrator POST /api/v1/building/condo-owners
   

   All require enrichment_scope >= basic. Rewrite correlationId server-side to ${tenant}:${user_sub[:8]}:${requestId}.
3. PR3 (gis-api): Per-tenant rate limit + gis_meta.api_audit migration.

When PR1+PR2 are green and deployed, signal back to this plan and proceed with Faza B.

Faza B — ArchiTools secrets + Authentik client (½ day)

• In Authentik: create OAuth2 client for architools (slug architools-app). Configure redirect URI for its NextAuth flow.
• Infisical adds (prod env, path /):
  • AUTHENTIK_CLIENT_ID / AUTHENTIK_CLIENT_SECRET / AUTHENTIK_ISSUER / AUTHENTIK_JWKS_URL for architools
  • GIS_API_URL=https://api.gis.ac
  • NEXT_PUBLIC_MARTIN_URL=https://tiles.gis.ac
  • NEXT_PUBLIC_PMTILES_URL=https://pmtiles.gis.ac/overview.pmtiles
• NextAuth on architools: add Authentik OIDC provider. Store access_token in session. ⚠️ DO NOT mint HS256 JWTs server-side anymore — pass the Authentik access_token directly as Bearer to gis-api.

Faza C — Rip-out (1 day, ONE PR, feature-flagged)

NEXT_PUBLIC_USE_GIS_AC=1 flag controls cutover. With flag on:

• Geoportal map sources flip to pmtiles.gis.ac + tiles.gis.ac
• All src/app/api/eterra/* and src/app/api/ancpi/* route handlers replaced by thin wrappers that forward to api.gis.ac with the user's access_token
• All src/modules/parcel-sync/** and parcel-sync UI removed
• src/config/{modules,navigation,flags}.ts cleanup

With flag off: old behavior retained. Do not drop Prisma tables (GisFeature, GisUat, GisSyncRun, GisSyncRule, CfExtract) in this PR. Keep them as dead columns for 2-3 days post-cutover so rollback stays cheap. Drop in a follow-up PR after validation in prod.

Stop martin container on satra ONLY after flag-on is verified working in prod. The PMTiles webhook on satra:9876 — does not exist; the architools claude's plan had this wrong. The actual PMTiles trigger is the orchestrator cron at 03:00 EEST + admin button in eterra.live, hitting gis-tippecanoe-builder on shop at port 9876.

Faza D — Thin client (1-2 days)

• src/lib/gis-api-client.ts — fetch wrapper with the Authentik access_token from session
  • gisApi.parcela.get(id) → GET /api/v1/parcela/:id
  • gisApi.search(q, limit) → GET /api/v1/search
  • gisApi.parcel.tech({siruta, cadastralRef, force}) → POST /api/v1/parcel/tech
  • gisApi.parcel.unitsFetch(...) → POST /api/v1/parcel/units/fetch
  • gisApi.parcel.immApps(...) → POST /api/v1/parcel/imm-apps
  • gisApi.building.tech(...) → POST /api/v1/building/tech
  • gisApi.building.condoOwners(...) → POST /api/v1/building/condo-owners
  • gisApi.enrichment.cf.list/get/create/patch/uploadPdf/getPdf/getCatalog (mirror eterra.live's existing usage)
• NO separate scope-mapper.ts — gis-api resolves scope from Authentik claims itself.
• NO separate gis-api-token.ts — Authentik access_token is the JWT, NextAuth session already has it.

Faza E — Geoportal rewrite (2 days)

• map-viewer.tsx: sources pmtiles://pmtiles.gis.ac/overview.pmtiles + Martin tiles.gis.ac/{view}/{z}/{x}/{y}. Drop satra Martin entirely.
• search-bar.tsx → gisApi.search().
• feature-info-panel.tsx → gisApi.parcela.get() + (on missing enrichment) gisApi.parcel.tech() + gisApi.parcel.unitsFetch() for buildings.
• basemap-switcher.tsx: same config as eterra.live (liberty/dark/satellite/orto/topo50). Source files are public CSS/tile URLs; literal copy is OK.
• Decision for boundary-check, cf-status, export, pad, piz: if architools keeps them, rewrite as thin proxies to api.gis.ac equivalents (which may need new endpoints — defer that scoping until each is actually needed).

Faza F — ePay / CF ordering (½ day)

• Architools UI for "Comandă extras CF" calls gisApi.enrichment.cf.create({nrCadastral, type, ...}) directly.
• Status + download list: gisApi.enrichment.cf.list({...}) and getPdf(id).
• The tenant=architools claim in the access_token tells gis-api which billing account to attribute the order to (future-work for billing routing, but the field is in place from Faza A).
• Delete src/app/api/ancpi/* entirely.

Faza G — Test E2E + deploy (½ day)

• /geoportal in architools renders tiles from gis.ac, click parcel → enrichment via api.gis.ac → live-fetch fallback triggers orchestrator.
• Verify zero references to architools_postgres.GisFeature remain in code AND that no DB query goes to the deprecated tables.
• Type-check + lint + build clean.
• Commit + push + Portainer redeploy.
• 24h grace period: old stack (Martin satra, deprecated parcel-sync code) kept around. After validation, follow-up PR drops Prisma tables + stops martin satra container.

Faza H — Planhub (separate PR, post-architools)

• Same pattern. Different scope mapping: planhub-free → basic, planhub-pro → full.
• Already covered by gis-api's tenant claim from Faza A.

---

Specific corrections to the original plan

1. POST /api/internal/enrich on eterra.live — REMOVE. Use api.gis.ac directly.
2. Bearer $ARCHITOOLS_INTERNAL_TOKEN static token — REMOVE. Use Authentik OIDC access_token.
3. GIS_API_JWT_SECRET (shared) in Infisical — REMOVE. With Authentik OIDC, gis-api fetches JWKS from https://auth.beletage.ro/application/o/gis-api/jwks/ — no shared secrets between apps.
4. scope-mapper.ts in architools — REMOVE. Scope is in the JWT claims; architools doesn't compute it.
5. PMTiles webhook satra:9876 — does not exist. The builder is gis-tippecanoe-builder on shop:9876, fired by orchestrator cron + eterra.live admin button.
6. Single-PR rip-out — replace with feature-flagged migration (NEXT_PUBLIC_USE_GIS_AC=1), 2-3 day overlap, drop dead code in a separate follow-up PR after prod validation.
7. eterralive-coordinator terminology — drop. The pool is "owned" by gis-sync-orchestrator (LAN-only on shop:3101). gis-api is the auth/scope/audit gateway in front of it.

---

Open questions

1. Authentik OIDC client provisioning — needs to be done first; until then, no architools migration. Marius or a sys-admin session needs to set up the OAuth2 provider in Authentik UI.
2. Audit table schema — does gis_meta already have an api_audit table? Probably no. Migration needed in same PR as proxy endpoints.
3. Rate-limit defaults — what's the cap per tenant? 100 req/min seems safe; configurable per tenant via Infisical JSON env. Confirm with Marius.
4. Architools' archi.* schema writes — currently architools writes Canvas, Job, RegistryAudit, RgiSearchTemplate directly via its own Prisma. Migration here is OPTIONAL for the cadastre work; could be done in a later sprint. Don't bundle it.

---

Reference docs

• gis-api project memory: ~/.claude/projects/-home-orchestrator-Code-gis-api/memory/MEMORY.md
• Plan 001 v2 master: ~/Code/ArchiTools/docs/plans/001-v2-central-gis-db-multi-app.md
• Tile data sources / cache / gis.ac rule: ~/Code/busc-infra/references/TILE-DATA-SOURCES.md
• Orchestrator workers + schema: ~/Code/busc-infra/references/SPRINT3.md
• GIS stack infrastructure: ~/Code/busc-infra/references/GIS-STACK.md
• Authentik configuration: ~/Code/busc-infra/references/AUTHENTIK.md
• Sprint 2 (gis-api delivery): ~/Code/busc-infra/references/SPRINT2.md