Gleipnir/nidus-sync
Gleipnir/nidus-sync
7
0
Fork 0
Code Issues 54 Pull requests 3 Projects Releases Packages Wiki Activity Actions

Skip Trace Integration Design Document #181

Closed
ned wants to merge 1 commit from issue-180-skip-trace-design-doc into main
pull from: issue-180-skip-trace-design-doc
merge into: Gleipnir:main
Conversation 1 Commits 1 Files changed 1 +266
ned commented 2026-07-30 02:16:38 +00:00
Member
Copy link

Summary

High-level design document for integrating Skip Trace API (skipreach.com) into Nidus Reveal.

Key Design Decisions

  1. Parcel-centric — data attaches to parcels, not pools. Matches how Nidus Reveal is organized.
  2. Relational schema — concrete typed columns for phones, emails, addresses (no JSONB). Follows patterns from issue #147.
  3. Per-parcel on-demand only — no batch/bulk. Each lookup costs $0.05.
  4. 30-day cache with manual refresh — data persists permanently, refresh re-queries the API.

Questions for @eliribble

The doc includes an Open Questions section covering:

  • API key storage (per-district vs global)
  • Rate limit granularity
  • Cost passthrough model
  • Schema naming (parcel_skip_trace vs parcel_enrichment)
  • Raw response storage

Status

Design doc only — implementation blocked on Skip Reach waitlist access (Benjamin has joined). Ready for technical review.

Related

Issue: #180

## Summary High-level design document for integrating Skip Trace API (skipreach.com) into Nidus Reveal. ## Key Design Decisions 1. **Parcel-centric** — data attaches to parcels, not pools. Matches how Nidus Reveal is organized. 2. **Relational schema** — concrete typed columns for phones, emails, addresses (no JSONB). Follows patterns from issue #147. 3. **Per-parcel on-demand only** — no batch/bulk. Each lookup costs $0.05. 4. **30-day cache with manual refresh** — data persists permanently, refresh re-queries the API. ## Questions for @eliribble The doc includes an [Open Questions](https://github.com/Gleipnir/nidus-sync/blob/main/doc/nidus-reveal/skip-trace-integration.md#8-open-questions-for-eliribble) section covering: - API key storage (per-district vs global) - Rate limit granularity - Cost passthrough model - Schema naming (parcel_skip_trace vs parcel_enrichment) - Raw response storage ## Status Design doc only — implementation blocked on Skip Reach waitlist access (Benjamin has joined). Ready for technical review. ## Related Issue: #180
Add skip trace integration design document
Some checks failed
/ golint (push) Failing after 13s
Details
/ pnpm-build (push) Successful in 1m13s
Details
0d8613476b 
Create a high-level design doc for integrating Skip Trace API
(skipreach.com) into Nidus Reveal. Key design decisions:

- Parcel-centric data model (not pool-centric), reflecting that
  Nidus Reveal is organized by parcel with pools as one data layer
- Relational schema with concrete typed columns rather than JSONB,
  following the pattern established by issue #147
- On-demand per-parcel lookups only (no batch/bulk), since each
  lookup costs /bin/bash.05 and we need usage guardrails
- Cache with 30-day TTL and manual refresh, data persists permanently
- Open questions section for Eli's review on API key storage,
  rate limiting, cost passthrough, and schema naming

Issue: #180
eliribble force-pushed issue-180-skip-trace-design-doc from 0d8613476b
Some checks failed
/ golint (push) Failing after 13s
Details
/ pnpm-build (push) Successful in 1m13s
Details
to 85bb5da776
Some checks failed
/ golint (push) Failing after 13s
Details
/ pnpm-build (push) Successful in 1m13s
Details
2026-08-29 22:18:22 +00:00 Compare
eliribble commented 2026-09-04 23:50:01 +00:00
Owner
Copy link

decided not to go with skiptrace.

decided not to go with skiptrace.
eliribble closed this pull request 2026-09-04 23:50:01 +00:00
Some checks failed
/ golint (push) Failing after 13s
Details
/ pnpm-build (push) Successful in 1m13s
Details

Pull request closed

Please reopen this pull request to perform a merge.
Sign in to join this conversation.
Reviewers
No reviewers
Labels
Clear labels
  
customer
Customers are aware of, and affected by the issue

  
prod
Issue has manifested in production

  
repro'd
Has been reproduced by engineering

  
retest
Issue is ready for retesting in staging

  
staging
Issue has manifested in staging

No labels
customer
prod
repro'd
retest
staging
Milestone
Clear milestone
No items
No milestone
Projects
Clear projects
No items
No project
Assignees
Clear assignees
No assignees
2 participants
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
Gleipnir/nidus-sync!181
No description provided.