Skip to main content
Version: Next

Project layout

.
├── index.html              # modern app entry
├── vanilla.html            # legacy three.js r70 reference entry
├── v1.html                 # legacy renderer in the modern UI shell
├── css/
│   ├── app.css             # app styles + brand tokens
│   └── tokens.css          # Phoenix design tokens (from Plan 003)
├── src/                    # TypeScript front end
│   ├── main.ts             # boot
│   ├── renderer.ts         # WebGLRenderer factory
│   ├── scene.ts            # scene, camera, controls, helpers, status bar
│   ├── brain.ts            # Brain wrapper + ParticlePoolBridge
│   ├── run.ts              # RAF render loop
│   ├── events.ts           # keyboard + resize
│   ├── gui.ts              # lil-gui settings panel
│   ├── brain-ui.ts         # product dashboard (bento layout + observability)
│   ├── loaders.ts          # OBJ + texture loaders
│   ├── entry-server.ts     # SSR stub
│   ├── globals.d.ts        # ambient types
│   ├── materials/          # neuron.ts, axon.ts (GLSL ShaderMaterials)
│   ├── sim/types.ts        # TelemetrySnapshot contract
│   ├── diag/logger.ts      # in-app diagnostics logger
│   ├── analytics/          # Vercel Web Analytics + Speed Insights browser initializer
│   ├── auth/               # Supabase Auth session + gate (Plan 007)
│   ├── data/               # DAL, database types, cost model, project state, Result<T>
│   ├── ingest/             # trace file import + Supabase persist
│   ├── map/                # trace→brain, live-brain Realtime bridge, session rollup
│   ├── search/             # Typesense client, schemas, indexer helpers, search + sync (Plan 008)
│   ├── sdk/                # thin OpenInference TS SDK (tracer.ts)
│   ├── ui/                 # observability views, waterfall, annotation form, project switcher, search-box, prompt-playground
│   └── __tests__/          # Vitest (161 passing tests across 22 default suites; 6 env-gated)
├── rust/
│   ├── brain_sim/          # the WASM simulation crate (World)
│   └── brain_engine/       # standalone scoring crate (not in the browser app)
├── supabase/
│   ├── migrations/         # source of truth: SQL migrations (6 files: init, rls, cost, auth, evaluators, prompt versioning)
│   ├── seed.sql            # dev seed (demo project, model-price manifest, evaluator templates, prompt registry)
│   └── functions/          # Edge Functions (run-eval, otlp-receiver, run-playground)
├── scripts/
│   ├── typesense-index.mjs # Admin indexer: drop/recreate collections + bulk import from Supabase + docs
│   └── build-vanilla-logger.mjs   # bundles the logger to an IIFE
├── typesense/              # Docker Compose for dev Typesense server (Plan 008)
├── .env.test               # Vitest env overrides (VITE_TYPESENSE_* = empty, no secrets)
├── public/
│   ├── vanilla/            # legacy three.js r70 reference assets
│   └── v1/                 # legacy-renderer-in-shell assets
├── Plans/                  # historical design docs
└── docs-site/              # this documentation site

Recent chat additions​

The EXEPERT Brain Chat feature adds these runtime paths:

  • src/chat/client.ts - browser-safe chat client for Supabase Edge Function calls, SSE parsing, and feedback submission.
  • src/chat/models.ts - provider/model normalization, fallback model metadata, and local provider icon mapping for the chat model picker.
  • src/chat/diagnostics.ts - sanitized chat diagnostics helper used by model discovery, streaming requests, and feedback saves.
  • src/brain-ui.ts - chat orchestration, local transcript persistence, anonymous auth provisioning, model selection, streaming UI updates, and feedback controls.
  • public/icons/providers/ - local Claude, Codex/OpenAI, and generic provider SVGs used by the picker and message footer.
  • supabase/functions/run-chat/ - authenticated SSE Edge Function that calls 9Router with server-only secrets, exposes sanitized model discovery, and persists each turn as a session, trace, and LLM span.
  • supabase/functions/chat-feedback/ - authenticated feedback endpoint that writes user_feedback span annotations.
  • supabase/migrations/20260615163726_phoenix_chat_annotations.sql - widens annotation uniqueness with span_annotations.identifier and adds the sessions(project_id, session_key) partial unique index.
  • src/__tests__/chat-client.test.ts - unit coverage for request shaping and SSE parsing.
  • src/__tests__/chat-models.test.ts - unit coverage for provider/model normalization and local icon mapping.
  • src/__tests__/chat-diagnostics.test.ts - unit coverage for diagnostics redaction and bounded payloads.

Recent analytics and layout additions​

  • src/analytics/vercel.ts initializes Vercel Web Analytics and Speed Insights with the vanilla package injection entrypoints. It is browser-only, records standard pageviews plus real-user performance metrics, and emits no custom events in this pass.
  • src/ui/workbench.ts mirrors the active workbench view onto both #workspace and .app-shell so app-level overlays can coordinate with top navigation chrome.
  • css/app.css treats the Settings view as a fixed app overlay above the top nav and hides #navStats while Settings is active, preventing the Stats.js FPS canvas from painting over the panel.

The two Rust crates​

  • rust/brain_sim: the simulation that the browser runs. Compiled to WASM by wasm-pack. This is the World documented in Simulation Core. Crate type ["cdylib", "rlib"]; wasm-opt is disabled.
  • rust/brain_engine: a standalone scoring/heuristics crate with its own unit tests. It is not imported by the browser app; treat it as a separate companion library.

Both are members of the workspace Cargo.toml, which sets a size-optimized release profile (opt-level = "s", lto = true, strip = true, codegen-units = 1).

Deployment-specific files​

  • scripts/vercel-build.sh is the Vercel build entry point. It prepares Rust and wasm-pack, builds the Vite app, builds the Docusaurus docs site, and merges the docs output into dist/.
  • scripts/copy-docs-build.mjs performs the docs merge. It copies docs-site/build entries into dist/ while skipping the docs site's root index.html so the app remains the production homepage.
  • index.html owns the public app shell, favicon declarations, and the top-nav Docs link. The Docs link should stay same-origin (/docs/...) for production.
  • src/ui/observability.ts builds in-app documentation links. When VITE_DOCS_URL is unset, production links use window.location.origin and local app links use http://localhost:3000.
  • src/ui/docs-url.ts centralizes docs URL behavior for both the top-nav Docs button and in-app help links.
  • public/favicon.png, public/favicon-32.png, public/favicon-192.png, and public/apple-touch-icon.png are the app icons served by Vite/Vercel.
  • docs-site/static/img/favicon.png is the matching Docusaurus favicon.

Generated, gitignored artifacts​

These are produced by the build and not committed:

  • rust/brain_sim/pkg/: the wasm-pack output.

  • public/vanilla/diag-logger.js and public/v1/diag-logger.js: the IIFE logger bundles.

  • dist/: the Vite build output.

  • docs-site/build/ is the Docusaurus build output that is copied into dist/ during the Vercel build.

Out of scope​

The repository also contains a bedtime-story/ folder of unrelated short stories and a stale root README.md that describes an older architecture. Neither reflects the current app; this documentation supersedes the README.