Skip to content

PointSav Documentation

The engineering library for the PointSav platform — operating systems and services for regulated businesses that own their data, their AI, and their record-keeping outright. Where the monorepo holds the code, this wiki holds the reasoning: architecture, services, security, and the governance commitments that bind future development.

PointSav Digital Systems

Revision as of · 7d712980

Historical revision — this record as it stood on 5 September 2026, not the current version. View the current record →

Location intelligence: data collection

The location-intelligence pipeline classifies retail and infrastructure locations into two archetypes — Vertical Warehouse (VWH) and Parking Structures (PKS) — by matching OpenStreetMap records against a maintained chain taxonomy. This runbook covers extending that taxonomy to a new chain, country, or infrastructure category, and re-running the ingest and clustering steps that follow.

Working directory for all commands: app-orchestration-gis/ (inside the GIS monorepo clone).

Prerequisites

  • Overpass API access (queries run through the pipeline's OSM ingest script; no API key required)
  • Python 3.11+ with pipeline dependencies installed
  • The active deployment's data directory path configured

Purpose

Add a new chain, country, or infrastructure category to the location-intelligence taxonomy, ingest its OpenStreetMap records, and re-run the clustering build so the new data is reflected in the VWH/PKS archetype outputs.

Procedure

  1. Verify the pipeline is clean by importing the taxonomy and config modules and confirming both load without error.

  2. Add a new chain to the taxonomy. Each chain is declared in its own YAML record: a chain identifier, country and region, a category (mapped to a NAICS code), the retailer's canonical legal name and parent company, a public identifier used to match OpenStreetMap records (typically a Wikidata QID via the brand:wikidata OSM tag), and an approximate store count used only as a sanity check on ingest results — never as a tier-qualification input. A chain that spans multiple countries is flagged as such rather than duplicated per country.

  3. Register the chain's category in the taxonomy module, if it introduces a category not already present. Each category carries a label, a NAICS code, and a note on which archetype signal it contributes (VWH or PKS) — none of these categories gate archetype-tier logic on their own; tier assignment is a separate downstream step.

  4. Run the OSM ingest for the new chain(s). The ingest script queries Overpass for the chain's tagged locations and writes the results to the pipeline's business-data directory. If a chain returns zero records, check whether Wikidata tag coverage is sparse in OSM for that chain and add a name-based fallback query to its YAML record.

  5. For a new infrastructure category (for example, commercial airports or intercity rail stations, as opposed to a retail chain), write a dedicated ingest script following the existing infrastructure-ingest pattern: an Overpass query scoped to the relevant aeroway/railway tags, filtered to exclude out-of-scope subtypes (private airstrips and military fields for airports; subway, light rail, and tram for railway stations), with per-country operator or IATA-code enrichment applied where the source tagging supports it.

  6. Re-run the clustering build once all new chain and infrastructure ingests are in place, using the pipeline's DBSCAN cluster-build scripts for each archetype. Copy the outputs to the active deployment's data directory and confirm the new cluster counts are at or above the prior production baseline — a drop below the baseline indicates an ingest or taxonomy regression, not an expected result of adding data.

Expected outcome

The new chain, country, or infrastructure category appears in the archetype's OSM ingest output with a plausible record count for its real-world scale, and the subsequent clustering build produces cluster counts at or above the pipeline's prior production baseline.

Verification

Count the records in each newly ingested chain's output file and compare against the chain's real-world scale as a sanity check, not an exact target. Confirm the clustering build's output feature counts for VWH and PKS are at or above their last known production baseline before treating the run as complete.

Rollback

A new chain YAML or taxonomy-category entry can be removed and the ingest re-run without side effects — the ingest step is idempotent per chain. The clustering build can be re-run at any time from its existing inputs; it does not need to be reverted, only re-run once the taxonomy correction is in place.

Next steps

See also

  • Urban Fringe — the VWH archetype model and chain taxonomy
  • Commuter — the PKS archetype model and chain taxonomy
  • Location intelligence archetypes (projects.woodfinegroup.com/site-selection) — PRO/VWH/PKS overview and map integration
  • Connect to the OSM data pipeline — generic single-chain ingest for new retail categories
Important Information

Corporate structure. PointSav Digital Systems ("PointSav") is currently a trade name of Woodfine Capital Projects Inc. ("Woodfine"), planned to become a wholly-owned Woodfine subsidiary upon incorporation. PointSav does not itself offer, sell, or solicit any security. Any securities offering associated with Woodfine's real-property direct-hold solutions is made exclusively by Woodfine, and only by means of the applicable Private Placement Memorandum.

No investment advice. This wiki's content is provided for engineering, operational, research, and development purposes. Nothing on this wiki constitutes investment advice or a solicitation to invest in any Woodfine partnership or direct-hold solution.

Intellectual property. The PointSav name, trade name, wordmark, and marks, together with all current and future PointSav- and Totebox-branded products, services, and offerings — and the software, source code, documentation, design system, and all related materials — are proprietary to Woodfine and its affiliates, except for components identified as open source. No rights are granted except as expressly set out in a written license or agreement. The full trademark notice appears in the footer of every page on this site.

Open source components. Portions of the platform are made available under permissive open-source licenses identified in the accompanying repository. Use of those components is governed by their respective license terms.

No warranty; informational use. Content on this wiki is provided for general informational purposes only and does not constitute a representation, warranty, or commitment with respect to product functionality, availability, pricing, or roadmap. Some articles describe planned or intended features, capabilities, and milestones — language such as "planned," "intended," "targeted," "may," and "expected" marks this forward-looking content, which is subject to change and does not constitute a commitment regarding future performance.

Confidentiality. Where an article describes an operational or deployment detail that is not intended for public disclosure, that article is not published on this wiki. Content here is general-purpose engineering documentation, not customer-specific configuration.

Jurisdiction. Woodfine Capital Projects Inc. is organized in British Columbia, Canada. References to the Sovereign Data Foundation on this wiki describe a planned or intended initiative only, not a current equity holder or active governance body.

Changes to this notice. PointSav may update this notice from time to time; the version posted on this page governs.

Not a filing system. This wiki is not a securities filing system, an electronic disclosure repository, or a substitute for SEDAR+ or any other regulatory filing system. Formal securities filings are made through the applicable regulatory filing system, not through this wiki.

Full disclaimer. This notice supplements, and does not replace, the full Disclaimers article. In the event of any conflict, the full Disclaimers article governs.

Read the full disclaimer →