Hinata Wiki

Appearance

Where Everything Lives — Hinata Data + API Architecture (post Setup C) ​

  period: project
  owner: Jimmy Neutron + Trunks
  status: current-state snapshot
  created: 2026-05-27

Public API Schema (LOCKED) ​

api.michael-engineer.dev/{commander}/<path>     ← only public hostname

Currently active:

api.michael-engineer.dev/events?limit=…
api.michael-engineer.dev/bulma/health
api.michael-engineer.dev/bulma/q/<sub>?…
api.michael-engineer.dev/bulma/write/<sub>     (POST)
api.michael-engineer.dev/weather/current
api.michael-engineer.dev/weather/forecast
api.michael-engineer.dev/weather/week

Topology — Single VPS Gateway (Setup C) ​

Public:  api.michael-engineer.dev → CF DNS → cloudflared tunnel on jimmy-vps
Internal dispatch (one /etc/cloudflared/config.yml on jimmy-vps):
  /events*    → http://localhost:8080                (jimmy-vps local FastAPI)
  /bulma/*    → http://nnamdis-macbook-pro:8081      (Mac via Tailscale)
  /weather/*  → http://nnamdis-macbook-pro:8082      (Mac via Tailscale)

No Cloudflare Worker handles routing. No per-service subdomains exist. One tunnel, one config, one source-of-truth audit zone.

Data Substrates ​

A — Z2 Data Plane + Mac Local Files ​

Bulma banking data lives on Z2: /mnt/data/hinata/data/bulma (host), bind-mounted at /root/data/bulma (CT109 bulma-finance, 192.168.1.214). Mac runs NO banking pollers — Mac is reauth surface only (reauth artifacts at Sandpit/hinata-sandpit/data/bulma/; old Sandpit/hinata/data/bulma/ is dead).

Mac local files (~/Sandpit/hinata/data/):

  PathWhat it holdsProducerReached by

    `zoro/sessions.jsonl`Strong/Hevy/Apple Health Workoutsparse-strong-export.pyzoro tab (TBD)
    `weather/latest.json`Most-recent forecast payloadweather-poller.pyweather-api.py

B — Studio Snapshot Cache (applications/hinata-studio/public/data/) ​

Static JSON refreshed every 10 min by com.hinata.refresh-tasks.

  FileSourceRead by

    `tasks.json`tasks.csvLiveOpenLoops, MaturityTimeline, TaskContextMenu
    `bulma-monzo.json`Monzo jsonl + categoriserBulma tab
    `sessionBurn.json`Claude JSONL session filesTokenBurnChart
    `weather-snapshot.json`weather-poller.pyWeatherPanel (fallback only)

C — Itachi Vault (credential storage) ​

federation/colonel_saitama-foundation_itachi-digital-security_context.md — tokens, API keys, per-service credentials (credential files in the-government/information_reference/).

D — jimmy-vps Postgres (database hinata) ​

  TableWhatEndpoint

    `public.events`Activity stream (all Hinata producers emit)api.michael-engineer.dev/events
    `public.football_*`Football researcher dataapi.michael-engineer.dev/football/* (future)
    `public.musicmastery_*`MusicMastery session eventsapi.michael-engineer.dev/musicmastery/* (future)

E — Cloudflare D1 (database hinata-studio) ​

Dashboard lane definitions, session / flashcard logs (legacy), ELO / mastery state. Read by Studio Worker.

Adding a New Commander API ​

  1. Build ~/Sandpit/hinata/scripts/{commander}-api.py (stdlib http.server, bind 0.0.0.0:[port])

  2. LaunchAgent ~/Library/LaunchAgents/com.hinata.{commander}-api.plist

  3. SSH to jimmy-vps, add one ingress block to /etc/cloudflared/config.yml

  4. sudo systemctl restart cloudflared on jimmy-vps

  5. Test: curl https://api.michael-engineer.dev/{commander}/health

No Cloudflare changes. No new DNS records. No new Workers.

◆ hinata · projects/data-architecture.html · phase-18 flatten