DataAcuity — Documentation Index
This folder contains the design and operational documentation for everything that runs on .106 — the DataAcuity Maps server, the GeoGlobal geocoding + routing service, the Business Intelligence data pipeline, and the rest of the BI/ops stack that supports The Geek Network apps.
For the apps' own docs (TagMe, Takemehome, Bruh!, etc.) see
AppInfo/<AppName>/instead.
Where to start
| If you are… | Read these in this order |
|---|---|
| A developer integrating an app with maps/POI/routing | GeoGlobal_README.md → GeoGlobal_Integration_Guide.md |
| A backend developer calling the API directly | GeoGlobal_README.md → GeoGlobal_API_Reference.md |
| A data engineer / dbt author | DataAcuity_Architecture_Overview.md → DataAcuity_BI_Pipeline.md → GeoGlobal_Data_Schema.md |
| A BI/analytics author building dashboards | DataAcuity_BI_Pipeline.md (§8 schemas) → GeoGlobal_Data_Schema.md |
| An ops / SRE engineer | DataAcuity_Architecture_Overview.md → DataAcuity_Security_Posture.md → GeoGlobal_Deployment.md |
| A compliance / legal reviewer | DataAcuity_BI_Pipeline.md (§6 anonymisation, §11 monitoring) → DataAcuity_Security_Posture.md |
| A product/exec needing the pitch | DataAcuity_External_Pitch.md → DataAcuity_Full_Proposition.md |
| A B! / Butler AI skill builder | GeoGlobal_API_Reference.md (MCP Tools section) → GeoGlobal_Integration_Guide.md (§2.7) |
Full file index
Cross-cutting (read first)
| File | Purpose |
|---|---|
| DataAcuity_README.md | This file — folder index, audience map, glossary |
| DataAcuity_Architecture_Overview.md | System-level diagram, component map, network topology |
| DataAcuity_Security_Posture.md | Current security state, gaps, hardening plan |
GeoGlobal service (geocoding, POI, routing)
| File | Purpose |
|---|---|
| GeoGlobal_README.md | Service overview |
| GeoGlobal_API_Reference.md | Every REST endpoint and MCP tool with request/response schemas |
| GeoGlobal_Integration_Guide.md | Copy-paste C#/Blazor patterns for TagMe + Takemehome |
| GeoGlobal_Data_Schema.md | geo_db tables (geonames + interesting_locations) for direct-DB consumers |
| GeoGlobal_Deployment.md | Container topology, env vars, runbook, rebuild procedure |
BI Pipeline (data warehouse + anonymisation + enrichment)
| File | Purpose |
|---|---|
| DataAcuity_BI_Pipeline.md | End-to-end design — extract, anonymise, enrich, mart, push-back |
| DataAcuity_BI_Implementation.md | Phase-by-phase execution runbook with acceptance tests, monitoring queries, deploy procedures |
| DataAcuity_BI_Anonymisation_Standard.md | The hash/token/generalise/suppress rules — single source compliance reviews against |
| DataAcuity_BI_Compliance_Map.md | POPIA / GDPR / FICA / CCPA / PCI-DSS clause-by-clause mapping to specific pipeline controls |
| DataAcuity_BI_DPIA_Template.md | GDPR Art. 35 Data Protection Impact Assessment template — ready for reviewer fill-in before Phase 2 ships |
DataAcuity product (pre-existing docs)
| File | Purpose |
|---|---|
| DataAcuity_Product_Spec.md | Product spec |
| DataAcuity_Full_Proposition.md | Full value proposition |
| DataAcuity_External_Pitch.md | External-facing pitch deck content |
| DataAcuity_Internal_Analytics.md | Internal analytics requirements |
| DataAcuity_Data_Flow.md | Original data flow narrative |
| Circle_Products_Integration.md | How TGN's Circle products integrate with DataAcuity |
Glossary
For readers who don't live in the data stack daily:
| Term | Meaning |
|---|---|
| DataAcuity | The product line that owns .106 — maps, geo intelligence, data warehouse, BI |
| GeoGlobal | The geocoding / POI / routing service we built (one of DataAcuity's products) |
| MCP | Model Context Protocol — Anthropic's standard for AI agents (like B!) to call external tools |
| Valhalla | The open-source routing engine we use for turn-by-turn directions |
| PostGIS | PostgreSQL extension for geographic queries |
| dbt | Data build tool — turns SQL into a versioned, tested, documented transformation pipeline |
| Superset | Apache Superset — open-source BI dashboards |
| Mart (data mart) | Business-ready denormalised table in the warehouse, ready for analytics consumption |
| Fact / Dim | Data warehouse lingo — fct_* tables are events, dim_* tables are entities/lookups |
| Staging | Warehouse layer where raw extracted data is lightly cleaned before transformation |
| Intermediate | Warehouse layer where PII is removed (the compliance gate in our pipeline) |
| K-anonymity | Privacy guarantee: every group in the data has at least K members, so no individual is uniquely identifiable |
| PII | Personally Identifiable Information |
| POPIA | Protection of Personal Information Act — South Africa's GDPR-equivalent |
| FICA | Financial Intelligence Centre Act — SA financial crime / KYC regulation |
| FDW | Foreign Data Wrapper — Postgres feature for one DB to query tables in another |
| CDC | Change Data Capture — incremental streaming of DB changes |
| OSM / PBF | OpenStreetMap data / Protocol Buffer Format (compact binary OSM file) |
| PgBouncer | Connection pooler in front of Postgres |
| n8n / Automatisch | Open-source workflow automation tools (Zapier-alternatives) |
| Keycloak | Open-source identity / SSO provider |
| Traefik | Modern reverse proxy with automatic TLS via Let's Encrypt |
Status legend
When docs reference "status", they use:
| Status | Meaning |
|---|---|
| 🟢 LIVE | In production, serving traffic |
| 🟡 BUILDING | Code/data exists but not yet hardened or wired |
| 🔵 DESIGNED | Spec written, not yet built |
| 🔴 GAP | Identified gap, not yet specced |
| ⚠️ ISSUE | Known problem, see linked tracker |
Document conventions
- All docs are markdown, kebab-case headings, GitHub flavour
- Code blocks always tagged with language
- File paths use forward slashes (cross-platform)
- Commands assume
bashon.106unless prefixed otherwise - Cross-references use the full filename (
GeoGlobal_API_Reference.md) not relative paths
Contributing
If you change anything on .106 — a container, a port, a credential, a schema — update the relevant doc in the same PR. The Trust but verify rule applies: the doc has authority only if it's actually current.