{"id":51141267,"url":"https://github.com/markmhendrickson/neotoma-inspector","last_synced_at":"2026-06-25T23:30:22.462Z","repository":{"id":353330187,"uuid":"1204032467","full_name":"markmhendrickson/neotoma-inspector","owner":"markmhendrickson","description":"Operator UI for Neotoma: browse entities, sources, relationships, schemas, and agent attribution over the HTTP API.","archived":false,"fork":false,"pushed_at":"2026-05-19T16:13:56.000Z","size":725,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-19T18:45:30.979Z","etag":null,"topics":["admin-ui","data-inspector","graph-visualization","neotoma","operator-ui","react","vite"],"latest_commit_sha":null,"homepage":"https://neotoma.io","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/markmhendrickson.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-07T16:16:08.000Z","updated_at":"2026-05-19T16:13:58.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/markmhendrickson/neotoma-inspector","commit_stats":null,"previous_names":["markmhendrickson/neotoma-inspector"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/markmhendrickson/neotoma-inspector","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/markmhendrickson%2Fneotoma-inspector","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/markmhendrickson%2Fneotoma-inspector/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/markmhendrickson%2Fneotoma-inspector/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/markmhendrickson%2Fneotoma-inspector/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/markmhendrickson","download_url":"https://codeload.github.com/markmhendrickson/neotoma-inspector/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/markmhendrickson%2Fneotoma-inspector/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34796761,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-25T02:00:05.521Z","response_time":101,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["admin-ui","data-inspector","graph-visualization","neotoma","operator-ui","react","vite"],"created_at":"2026-06-25T23:30:19.924Z","updated_at":"2026-06-25T23:30:22.451Z","avatar_url":"https://github.com/markmhendrickson.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Neotoma Inspector\n\nA React SPA for inspecting and managing all data stored in a Neotoma instance. Provides full-coverage UI for every Neotoma REST API endpoint: browsing entities, observations, sources, relationships, schemas, timeline events, and interpretations, with an interactive graph explorer and top-level dashboard analytics.\n\n## Architecture: Bundled into the Neotoma server\n\nThe Inspector is always bundled into the Neotoma server build and served at `/`\non the same origin by default. There is no separate deployment, no GitHub\nPages, no external URL to configure. `npm run dev` in the parent repo and the\nInspector is live at `localhost:3080/`.\n\nThe build that ships in the npm tarball lives at\n`\u003cneotoma-package\u003e/dist/inspector` (and `/app/inspector` inside the Docker\nimage). `VITE_PUBLIC_BASE_PATH=/` is set at build time; `VITE_NEOTOMA_API_URL`\nis intentionally left unset so the Inspector uses relative same-origin URLs at\nruntime. Set `NEOTOMA_INSPECTOR_BASE_PATH=/inspector` only when a deployment\nneeds the legacy subpath mount.\n\n## Quick Start\n\n```bash\n# Install dependencies\nnpm install\n\n# Start inspector + matching Neotoma dev API\nnpm run dev\n\n# Start inspector + matching Neotoma prod API\nnpm run dev -- --env prod\n\n# Build for production\nnpm run build\n```\n\nVite defaults to **`base: /`** when `VITE_PUBLIC_BASE_PATH` is unset, so the dev\nserver is at **`http://localhost:5175/`** (port **5175** avoids clashing with\nthe repo root marketing Vite dev server, which often runs on\n**5173**/**5174**). Override the dev port with **`VITE_INSPECTOR_DEV_PORT`** or\n**`INSPECTOR_DEV_PORT`**. Set `VITE_PUBLIC_BASE_PATH=/inspector/` only when\ntesting the legacy subpath mount.\n\n## Configuration\n\n`npm run dev` launches a Neotoma API automatically via the CLI and injects the matching default API URL:\n\n- `npm run dev` -\u003e `dev` environment -\u003e `http://localhost:3080`\n- `npm run dev -- --env prod` -\u003e `prod` environment -\u003e `http://localhost:3180`\n\nDuring local development, the SPA talks to the API through the Vite proxy at `/api`, which avoids browser CORS issues while still targeting the matching Neotoma environment above.\n\nYou can still override the API URL via environment variable or the Settings page:\n\n```bash\n# .env or .env.local\nVITE_NEOTOMA_ENV=dev\nVITE_NEOTOMA_API_URL=http://localhost:3080\n```\n\nSaved API URLs and auth tokens are scoped per environment (`dev` / `prod`), so switching preserves separate connection settings.\n\n## Sandbox mode \u0026 session handoff\n\nOn the hosted sandbox (`sandbox.neotoma.io`), the Inspector is served at `/` on\nthe same origin as the API. Ephemeral sessions are created via the landing page\npack picker and handed off to the Inspector via a one-time code in the hash\nfragment:\n\n1. **Sandbox handoff (default for visitors).** Users start at\n   `sandbox.neotoma.io/`, pick a fixture pack (generic, empty, or a use case),\n   and stay on `/#session=\u003cone_time_code\u003e`.\n\n   `src/lib/sandbox_session.ts` (`consumeSandboxSessionHandoff`) runs on boot, POSTs `/sandbox/session/redeem` (same-origin), stores the returned bearer via `setApiUrl` / `setAuthToken`, scrubs the hash, and reloads. The `SandboxBanner` then shows the active pack id + expiry countdown + Reset / End-session controls.\n\n2. **Manual bearer (power users).** Paste an API base URL and bearer on **Settings**. While a redeemed sandbox session is active, these fields collapse under \"Show advanced connection settings.\"\n\n3. **Local dev proxy.** `npm run dev` still launches a local Neotoma and proxies `/api`; no handoff needed.\n\n### Sandbox UI flag\n\n`VITE_NEOTOMA_SANDBOX_UI=1` (or any live redeemed session) enables:\n\n- A persistent `SandboxBanner` with pack + expiry countdown, AAuth tier, and Reset / End-session buttons when a session is active; the public weekly-reset notice + terms / abuse links otherwise.\n- Destructive admin surfaces are hidden to match the server-side destructive-op gate.\n\nSee [docs/subsystems/sandbox_deployment.md](../docs/subsystems/sandbox_deployment.md) for the full sandbox architecture.\n\n## Pages\n\n- **Dashboard** (`/`) — Top-level stats, entity type breakdown chart, recent timeline activity, health status\n- **Entities** (`/entities`) — Filterable/sortable entity list with search, type filtering, pagination\n- **Entity Detail** (`/entities/:id`) — Snapshot, observations, relationships, graph neighborhood, field provenance; Edit tab for multi-field batch corrections\n- **Observations** (`/observations`) — Browse and create observations with JSON field viewer\n- **Sources** (`/sources`) — Browse sources, upload files, structured store; download via signed URLs\n- **Relationships** (`/relationships`) — Browse, create, delete/restore relationships with snapshot provenance\n- **Graph Explorer** (`/graph`) — 1-hop neighborhood visualization with React Flow (default tree layout, optional radial)\n- **Schemas** (`/schemas`) — Registry browser, field/reducer detail, register/update forms, candidate analysis\n- **Timeline** (`/timeline`) — Chronological event stream with date/type filters\n- **Interpretations** (`/interpretations`) — AI interpretation run history\n- **Settings** (`/settings`) — API connection, server info, user details, snapshot health\n\n## Tech Stack\n\n- React 18 + TypeScript\n- Vite 6\n- Tailwind CSS + shadcn/ui (Radix)\n- TanStack Query v5 + TanStack Table\n- React Router v7\n- Recharts (dashboard charts)\n- @xyflow/react (graph visualization)\n- lucide-react (icons)\n\n## API Coverage\n\nCovers all endpoints from the Neotoma OpenAPI spec.\n\n## Integration\n\nThis app is a git submodule of the main Neotoma repo:\n\n```bash\ngit submodule add \u003crepo-url\u003e inspector\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarkmhendrickson%2Fneotoma-inspector","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmarkmhendrickson%2Fneotoma-inspector","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarkmhendrickson%2Fneotoma-inspector/lists"}