DataAcuity — Technical Data Flow

From user action → anonymised insight → business product → revenue → back to user

Classification: Internal technical specification Links: AppInfo/DataAcuity/DataAcuity_Full_Proposition.md — business context Links: AppInfo/DataAcuity/DataAcuity_External_Pitch.md — public-safe version Links: docs/WOLVERINE_HEALING_PIPELINE.md — Wolverine architecture reference Memory: .claude-memory/banking-compliance-rules.md, .claude-memory/aether-global-compliance.md Status: Architecture defined. Event schemas and API specs to be implemented.

Overview: Five Layers

┌─────────────────────────────────────────────────────────┐
│  LAYER 1: Event Emission                                │
│  User performs consented action in any TGN app         │
│  → Structured event emitted (PII stripped at source)   │
└────────────────────┬────────────────────────────────────┘
                     │ Wolverine event bus (WolverineAPI:5014)
┌────────────────────▼────────────────────────────────────┐
│  LAYER 2: Privacy Gate + Ingestion                      │
│  Strip identifiers → pseudonymous cohort ID             │
│  k-anonymity check → differential privacy noise         │
│  Jurisdiction stamp → consent-version stamp             │
└────────────────────┬────────────────────────────────────┘
                     │
┌────────────────────▼────────────────────────────────────┐
│  LAYER 3: Aggregation + Cohort Builder                  │
│  Group into demographic cohorts                         │
│  Suppress cohorts < 1,000 users                         │
│  Build time-series and cross-app journey signals        │
└────────────────────┬────────────────────────────────────┘
                     │
┌────────────────────▼────────────────────────────────────┐
│  LAYER 4: Product Surfaces                              │
│  B: Industry Reports (SQL → PDF/dashboard)              │
│  C: Pro API (REST endpoints)                            │
│  D: Wolverine SaaS (event infra as product)             │
└────────────────────┬────────────────────────────────────┘
                     │ Revenue received from buyers
┌────────────────────▼────────────────────────────────────┐
│  LAYER 5: Revenue Reverse Flow                          │
│  1% gross → social pledge                               │
│  5% net revenue → Qi Pool → back to contributing users  │
│  35% net profit → community arms → member cashback      │
└─────────────────────────────────────────────────────────┘

Layer 1: Event Emission — Per App Schema

Design rules for all events

• PII stripped at source. No phone number, no name, no email in any event.
• Location precision: Province + zone only. Never street address or GPS coordinate.
• Amounts: Banded (e.g., R0–R100, R101–R500, R501–R2000, R2000+). Never exact.
• Timing: Rounded to day (no hour-level precision for most events; exception: Panik SOS where time-of-day band is the signal, not the exact time).
• Consent flag: Every event carries consentVersion and consentScope — events without valid consent are dropped at the privacy gate.
• Mesh flag: source: "internet" | "aether" — flags whether the event came from a mesh relay (geographic intelligence for offline zone mapping).

SDPKT — WalletEvent

{
  "eventType": "WalletEvent",
  "timestamp": "2026-04-18",
  "cohortId": "<pseudonymous-rotating-id>",
  "karmaT ier": "Sprout",
  "eventSubtype": "purchase | transfer | topup | withdrawal",
  "categoryCode": "airtime | electricity | grocery | transport | retail | entertainment | other",
  "amountBand": "R0-R100 | R101-R500 | R501-R2000 | R2000+",
  "merchantType": "formal | informal | peer | utility",
  "locationZone": "GP-JHB-SOUTH | WC-CPT-NORTH | KZN-DBN-CENTRAL | ...",
  "source": "internet | aether",
  "consentVersion": "1.2",
  "consentScope": "financial-behaviour"
}

Business value: Consumer spend patterns by category, zone, economic tier, and time.

The Job Center — LabourEvent

{
  "eventType": "LabourEvent",
  "timestamp": "2026-04-18",
  "cohortId": "<pseudonymous-rotating-id>",
  "karmaT ier": "Seedling",
  "eventSubtype": "search | view | apply | outcome-success | outcome-fail",
  "roleCategory": "learnership | internship | scholarship | bursary | entry-level | skilled | management",
  "sector": "retail | construction | healthcare | tech | education | hospitality | other",
  "locationZone": "GP-JHB-SOUTH",
  "salaryBand": "R0-R5000 | R5001-R15000 | R15001-R40000 | R40000+",
  "source": "internet | aether",
  "consentVersion": "1.2",
  "consentScope": "labour-market"
}

Business value: Labour market demand signals, skills gaps by province, learnership uptake rates.

txtMe! — MessagingMetadataEvent

{
  "eventType": "MessagingMetadataEvent",
  "timestamp": "2026-04-18",
  "cohortId": "<pseudonymous-rotating-id>",
  "eventSubtype": "individual | group | channel | community",
  "groupSizeBand": "1 | 2-10 | 11-50 | 50+",
  "messagingFrequencyBand": "daily | weekly | occasional",
  "primaryLanguageCode": "zu | xh | af | en | fr | pt | ...",
  "source": "internet | aether",
  "consentVersion": "1.2",
  "consentScope": "communication-patterns"
}

IMPORTANT: No message content. No recipient identifiers. Metadata only. Business value: Language usage patterns, community size dynamics, Aether vs internet ratio (network quality signal).

TagMe — TagEvent

{
  "eventType": "TagEvent",
  "timestamp": "2026-04-18",
  "cohortId": "<pseudonymous-rotating-id>",
  "tagCategory": "food | transport | accommodation | entertainment | safety | retail | event | service | infrastructure | other",
  "sentimentScore": "positive | neutral | negative",
  "locationZone": "GP-JHB-SOUTH",
  "locationType": "fixed | mobile | temporary",
  "online": true,
  "source": "internet | aether",
  "verifiedPresence": true,
  "consentVersion": "1.2",
  "consentScope": "location-social-graph"
}

Business value: Physical-world footfall by category and zone, sentiment by place-type, offline activity mapping, real-world social graph signals.

Special value of source: "aether": Tags submitted via mesh when no internet = presence confirmed in an offline zone. This is unique to TGN — no other provider can capture this.

SleptOn — ContentEvent

{
  "eventType": "ContentEvent",
  "timestamp": "2026-04-18",
  "cohortId": "<pseudonymous-rotating-id>",
  "eventSubtype": "publish | purchase | view | review",
  "contentCategory": "course | music | art | video | writing | template | photography | other",
  "priceBand": "free | R1-R50 | R51-R200 | R201-R500 | R500+",
  "creatorLocale": "zu-ZA | en-ZA | fr | pt | ...",
  "buyerLocale": "zu-ZA | en-ZA | fr | pt | ...",
  "locationZone": "GP-JHB-SOUTH",
  "source": "internet | aether",
  "consentVersion": "1.2",
  "consentScope": "content-economy"
}

Business value: Informal creative economy signals, content category demand by language/locale, price sensitivity by economic tier.

KiffStore — CommerceEvent

{
  "eventType": "CommerceEvent",
  "timestamp": "2026-04-18",
  "cohortId": "<pseudonymous-rotating-id>",
  "eventSubtype": "browse | wishlist | purchase | return",
  "productCategory": "food | clothing | electronics | homeware | beauty | sport | other",
  "priceBand": "R0-R100 | R101-R500 | R501-R2000 | R2000+",
  "sellerType": "local-small | local-medium | formal-retail",
  "localSeller": true,
  "locationZone": "GP-JHB-SOUTH",
  "source": "internet | aether",
  "consentVersion": "1.2",
  "consentScope": "commerce-behaviour"
}

Business value: Consumer preference by category, local vs formal retail preference, price sensitivity by zone and economic tier.

Panik — SafetyEvent

{
  "eventType": "SafetyEvent",
  "timestamp": "2026-04-18",
  "cohortId": "<pseudonymous-rotating-id>",
  "alertType": "sos | check-in | silent | area-warning",
  "timeOfDayBand": "00-06 | 06-12 | 12-18 | 18-24",
  "dayType": "weekday | weekend | public-holiday",
  "locationZone": "GP-JHB-SOUTH",
  "responseReceived": true,
  "resolvedWithin": "5min | 5-30min | 30min+ | unresolved",
  "source": "internet | aether",
  "consentVersion": "1.2",
  "consentScope": "safety-patterns"
}

MAXIMUM SENSITIVITY. Cohort minimum for Panik data: 5,000 (not 1,000). Location precision reduced to metro-area only (not zone). No time-of-day in individual zone reports — only in metro-aggregated form.

Business value: Safety hotspot identification by area and time-band (for urban planners, NGOs, government — NOT for insurance risk scoring without explicit consent).

TrustSeal — VerificationEvent

{
  "eventType": "VerificationEvent",
  "timestamp": "2026-04-18",
  "cohortId": "<pseudonymous-rotating-id>",
  "documentType": "affidavit | id-copy | contract | certification | other",
  "verificationOutcome": "success | failed | pending",
  "locationZone": "GP-JHB-SOUTH",
  "source": "internet | aether",
  "consentVersion": "1.2",
  "consentScope": "document-verification"
}

Business value: Where legal/document infrastructure is failing (high failed-verification rates = infrastructure gap). Demand for specific document types by region.

ShhMoney — FinancialPlanningEvent

{
  "eventType": "FinancialPlanningEvent",
  "timestamp": "2026-04-18",
  "cohortId": "<pseudonymous-rotating-id>",
  "eventSubtype": "savings-goal-set | deposit | withdrawal | investment-opened | investment-closed",
  "goalType": "emergency | education | housing | business | general",
  "depositFrequencyBand": "daily | weekly | monthly | irregular",
  "amountBand": "R0-R500 | R501-R2000 | R2001-R10000 | R10000+",
  "karmaT ier": "Sapling",
  "source": "internet | aether",
  "consentVersion": "1.2",
  "consentScope": "financial-planning"
}

Business value: Savings behaviour trajectory by economic tier, financial goal priorities by demographic.

Takemehome.co.za — MobilityEvent

{
  "eventType": "MobilityEvent",
  "timestamp": "2026-04-18",
  "cohortId": "<pseudonymous-rotating-id>",
  "eventSubtype": "search | book | complete | cancel",
  "originZone": "GP-JHB-SOUTH",
  "destinationZone": "GP-JHB-NORTH",
  "routeType": "urban | peri-urban | rural | inter-city",
  "departureBand": "00-06 | 06-12 | 12-18 | 18-24",
  "distanceBand": "0-10km | 11-50km | 51-200km | 200km+",
  "priceBand": "R0-R50 | R51-R150 | R151-R500 | R500+",
  "source": "internet | aether",
  "consentVersion": "1.2",
  "consentScope": "mobility-patterns"
}

Business value: Transport demand by route, time, and economic tier. Infrastructure gap identification (high cancel rates = poor service supply).

Bruh! — EcosystemEngagementEvent

{
  "eventType": "EcosystemEngagementEvent",
  "timestamp": "2026-04-18",
  "cohortId": "<pseudonymous-rotating-id>",
  "appsUsedInSession": ["SDPKT", "JobCenter", "txtMe"],
  "sessionDurationBand": "0-5min | 5-30min | 30min+",
  "sequencePattern": "wallet-first | jobs-first | messaging-first | ai-first",
  "karmaT ier": "Tree",
  "primaryLanguage": "zu",
  "source": "internet | aether",
  "consentVersion": "1.2",
  "consentScope": "ecosystem-engagement"
}

Business value: Cross-app journey patterns, which apps are used together, economic life-stage signals from app combination (wallet + jobs = early-stage; wallet + savings + investment = advanced-stage).

Layer 2: Privacy Gate + Ingestion

Processing steps (in order)

1. Receive event from Wolverine event bus
2. Validate consent: consentVersion >= current minimum, consentScope matches event type
   → IF invalid: DROP event, log consent-drop metric (no data, no Qi)
3. Strip all direct identifiers (cohortId was generated at app layer — already pseudonymous)
4. Validate location precision: reject anything more granular than zone
5. Apply temporal rounding: round timestamp to day
6. Apply differential privacy noise to continuous signals (amounts, frequencies)
   → Add calibrated Laplace noise (ε=1.0 by default — adjust per sensitivity tier)
7. Stamp jurisdiction: derive from locationZone + user registration locale
   → Determines which community arm receives distribution (SA / NL / JP)
8. Write to DataAcuity ingestion queue (separate from operational databases)
9. Emit QiEarnedEvent back to IncentivesAPI:5162 — user earns Qi for the consented event

Cohort ID rotation

Cohort IDs are pseudonymous — not user IDs. They rotate on a 90-day cycle to prevent longitudinal re-identification. Consequence: cross-90-day journey tracking uses cohort-level aggregates, not individual tracking.

Layer 3: Aggregation + Cohort Builder

Cohort dimensions

Users are grouped into cohorts by combinations of:

Suppression rule

Any cohort query returning fewer than 1,000 contributing users → result suppressed. Response: { "suppressed": true, "reason": "cohort_too_small", "minimumRequired": 1000 }

This prevents re-identification even for rare demographic combinations.

Panik data: minimum 5,000 (higher threshold due to safety sensitivity).

Time-series signals

For Industry Reports, cohort signals are stored as time-series (TimescaleDB hypertables). This enables:

• Quarter-on-quarter trend analysis
• Before/after event analysis (e.g., economic impact of a policy change)
• Seasonal patterns (spend before month-end vs after payday)

Layer 4: Product Surface Outputs

B — Industry Report Query Pattern

-- Example: Township consumer spend by category, Q1 2026, Gauteng
SELECT
    locationZone,
    categoryCode,
    amountBand,
    karmaT ier,
    COUNT(*) AS eventCount,
    DATE_TRUNC('month', timestamp) AS period
FROM wallet_events
WHERE
    locationZone LIKE 'GP-%'
    AND timestamp BETWEEN '2026-01-01' AND '2026-03-31'
    AND consentScope = 'financial-behaviour'
GROUP BY locationZone, categoryCode, amountBand, karmaT ier, period
HAVING COUNT(*) >= 1000  -- suppression rule enforced in query
ORDER BY period, locationZone, eventCount DESC;

Output → formatted into report template (PDF + interactive dashboard).

C — Pro API Endpoint Patterns

GET /v1/cohorts/spend?zone=GP-JHB-SOUTH&category=grocery&period=2026-Q1
GET /v1/cohorts/labour?province=GP&sector=tech&roleCategory=learnership
GET /v1/cohorts/mobility?originZone=GP-JHB-SOUTH&destinationZone=GP-JHB-NORTH
GET /v1/cohorts/sentiment?tagCategory=food&zone=GP-JHB-SOUTH&period=2026-Q1
GET /v1/infrastructure/offline-zones?province=GP&threshold=0.4
GET /v1/cohorts/journey?sequence=wallet-first&karmaT ier=Sprout

All responses include:

{
  "query": { ... },
  "period": "2026-Q1",
  "cohortSize": 12450,
  "suppressed": false,
  "consentCoverage": 0.94,
  "jurisdictions": ["ZA"],
  "data": [ ... ]
}

consentCoverage tells the buyer what % of events in this cohort had valid consent — a quality signal unique to DataAcuity (no other provider publishes this).

D — Wolverine SaaS

Separate product. Not derived from user data. The Wolverine event pipeline itself, sold as infrastructure. See docs/WOLVERINE_HEALING_PIPELINE.md for the technical architecture.

Layer 5: Revenue Reverse Flow

Qi attribution

When a DataAcuity invoice is paid, the QiPool receives 5% of net revenue.

The attribution model:

Total Qi distributed = 5% of net revenue / total contributing events in the reporting period

Per-user Qi = (user's contributing event count / total events) × Total Qi distributed

Example: R45,000 net revenue from a report. Qi pool = R2,250. Report covered 500,000 contributing events. User contributed 47 events. User's Qi = (47/500,000) × R2,250 = R0.21 = 21 Qi

Qi is distributed via IncentivesAPI:5162 → credited to user's SDPKT wallet.

Community trust distribution

35% of net profit is distributed annually to community arms:

• Allocation by jurisdiction: based on where the contributing events originated
• SA events → Bengu Community Trust SA (Rand denominated)
• NL-routed events → Bhengu Stichting NL (EUR denominated)
• JP-routed events → Bhengu San Zaidan JP (JPY denominated)

Community arms distribute to members annually. The mechanism: members of the ecosystem (registered TGN users with active accounts) receive distributions proportional to their engagement depth and Karma tier.

Social pledge

1% of gross revenue is pre-committed before any other distribution. Managed by the community arms jointly. Directed to: schools, clinics, community infrastructure, disaster relief. Amount is fixed at gross revenue level — cannot be reduced by operating losses.

Open Implementation Tasks

• Implement event emission in each app (add to each app's service layer)
• Create DataAcuity ingestion service (new API: DataAcuityAPI — port TBD)
• Build privacy gate (consent validation + differential privacy noise library)
• Create cohort builder (TimescaleDB hypertables for time-series)
• Build Pro API (ASP.NET Core minimal API, JWT-authenticated for paying clients)
• Connect QiEarnedEvent → IncentivesAPI:5162 for Qi attribution
• Build Industry Report query templates (SQL → PDF/dashboard pipeline)
• Create AppInfo/DataAcuity/DataAcuity_API_Spec.md (OpenAPI 3.1 spec for Pro API)
• Create AppInfo/DataAcuity/event-schemas/ folder (one JSON Schema file per app)