Frontend modules

The front end lives under src/. Each module has a narrow responsibility.

Module	Responsibility
main.ts	Boot: order init, create renderer, load assets, build the brain, start the loop. See Boot sequence.
renderer.ts	Renderer factory: returns a classic WebGLRenderer and the 'webgl2' backend tag.
scene.ts	Scene, camera, OrbitControls, Stats, helpers, stage sizing, status bar, and sceneSettings.
brain.ts	The Brain wrapper around the WASM World. See Brain.
run.ts	The requestAnimationFrame render loop. See Rendering pipeline.
events.ts	Keyboard shortcuts and a debounced resize handler.
gui.ts	The lil-gui settings panel. See UI Guide.
brain-ui.ts	The product UI: mode tabs, stimulus upload, telemetry polling, live AI chat, and the custom searchable 9Router model menu. See EXEPERT Brain Chat.
loaders.ts	Promise-wrapped OBJ and texture loaders.
materials/neuron.ts, materials/axon.ts	The GLSL ShaderMaterials. See Materials.
sim/types.ts	The TelemetrySnapshot contract types. See Telemetry.
diag/logger.ts	The in-app diagnostics logger. See Diagnostics Logger.
analytics/vercel.ts	Browser-only Vercel initializer using @vercel/analytics and @vercel/speed-insights injection entrypoints for pageview and real-user performance metrics.
entry-server.ts	SSR stub for vite build --ssr.
globals.d.ts	Ambient types (window.neuralNet, shader module declarations).
Plan 007 modules
auth/session.ts	Supabase Auth session wrapper: getUser, signInWithPassword, signInWithOAuth, signOut, onAuthChange. All return Result<T>.
auth/gate.ts	Compact 32×32 avatar button in #authSlot in top nav; click toggles a dropdown containing the sign-in form or profile panel. Dismiss on outside click or × button. Mounts/unmounts observability panel based on auth state. Bypassed when Supabase is unconfigured.
data/dal.ts	Data access layer: traces, spans, sessions, evaluators, annotation configs, model prices, user projects. Returns Result<T>, degrades offline.
data/database.types.ts	Hand-authored Supabase type definitions (reconciled with supabase gen types output).
data/result.ts	Result<T, AppError> type + discriminated AppError enum.
data/cost.ts	Pure cost model: price book, regex model matching, span cost backfill, rollup aggregation.
data/project-state.ts	Singleton active-project state with pub/sub: getActiveProject, setActiveProject, onProjectChange.
chat/client.ts	Browser client for EXEPERT Brain Chat: loads model metadata, builds chat requests, parses SSE tokens, logs sanitized diagnostics, and submits feedback to Supabase Edge Functions.
chat/models.ts	Model/provider normalization and local icon mapping for the chat model picker.
chat/diagnostics.ts	Chat-specific diagnostics redaction before events enter the global diagnostics panel.
ingest/import.ts	Trace file import + Supabase persist (cost_usd backfill on import).
map/trace-to-brain.ts	Pure helpers converting trace/span data into brain TelemetrySnapshot signals.
map/live-brain.ts	Realtime live-brain bridge: subscribes to new-span INSERTs via Supabase Realtime, aggregates into 250ms windows (at most 5 stimuli per window), and injects into the brain. onSpan callback tracks running count for UI badge.
map/session-rollup.ts	Session helpers: groupBySession, rollupSession, replaySession (sequential trace replay through the brain), regionActivityForSpans (for compare mode).
sdk/tracer.ts	Thin OpenInference-compatible TS SDK (trace + span builders, flush).
ui/observability.ts	Observability panel: mounts into #observabilitySlot in the activity-page view, with old #obsSlot as fallback; mounts project switcher (stores teardown), summary tile, trace list, and subscribes to project changes for re-render. Exports mountObservabilityPanel / unmountObservabilityPanel.
ui/workbench.ts	Activity-bar view switching. Sets data-workbench-view for dashboard, prompts, observability, and settings; the Observability view shows the Trace Ingestion page outside the Chat area.
ui/views.ts	Trace list, session grouping, waterfall, span detail, error-focus waterfall, compare mode (side-by-side region diff), session detail.
ui/waterfall.ts	Waterfall node builder (depth, offset/width percentages, flat render order).
ui/format.ts	Format helpers: latency, timestamps, status badges.
ui/annotation-form.ts	Vanilla-DOM human annotation form (categorical / continuous / freeform modes) mounted in span detail.
ui/project-switcher.ts	Vanilla-DOM project dropdown (ARIA listbox) reading from listUserProjects.
ui/signin-view.ts	Sign-in card: email/password + GitHub/Google OAuth buttons; collapses to identity chip + sign-out when signed in.
Plan 008 modules
search/client.ts	getTypesense() singleton: returns a SearchClient when all VITE_TYPESENSE_* env vars are present, null + one diag warning when unconfigured. Mirrors getSupabase() pattern.
search/schema.ts	TRACE_SPANS_SCHEMA (12 fields, start_time sort) + DOCS_SCHEMA (6 fields) used for Typesense collection provisioning.
search/indexer.ts	Pure mapping helpers: rowToTraceDoc(), traceToDoc(), flattenAttributes(), stripFrontmatter(), extractHeadings(), markdownToDocs(). Exported for unit-testing without a server.
search/search.ts	multiSearch(query) issuing Typesense multi_search across both collections; debounced; pure buildSearchRequest + normalizeHits helpers; returns Result<SearchResults>.
search/sync.ts	SyncQueue class (5s throttle) + bulkUpsert() REST client. Designed for server-side use (Edge Functions, admin scripts); never used in the browser.
ui/search-box.ts	Vanilla DOM dropdown + keyboard nav (↑/↓/Enter/Esc); groups results into "Traces" + "Docs" sections; highlight snippets; click handlers to openTraceList() or window.location.href; inert placeholder + typewriter animation when Typesense is unconfigured. Lazy-imported from main.ts via requestIdleCallback.
Plan 010 modules
data/dal.ts	Added PromptWithVersion, listPrompts, createPrompt, createPromptVersion, setCurrentVersion, getPrompt, getPromptVersion, listPromptVersions functions for prompt registry CRUD.
data/database.types.ts	Added TemplateType, TemplateFormat enums; PromptRow, PromptVersionRow, PromptInsert, PromptVersionInsert row types; updated EvaluatorRow/EvaluatorInsert with prompt_version_id FK.
ui/prompt-playground.ts	Vanilla DOM playbook for prompt engineering: CHAT/STR editors, MUSTACHE variable inputs, streaming SSE response area, version history sidebar. Lazy-imported via requestIdleCallback.

scene.ts

Owns everything about the stage that is not the brain itself: the Scene, the perspective camera, OrbitControls, the Stats overlay, the grid/axis helpers, an optional floor platform, and the on-canvas status bar (updateBrainStatusBar). It also holds sceneSettings, the mutable object the GUI and keyboard handlers write to:

• pause: toggled by Space.
• enableGridHelper / enableAxisHelper: toggled by A / S.
• bgColor: background color (default 0x0d0d0f), applied each frame because autoClear is off.
• enableFloorPlatform: optional floor.

events.ts

Registers two listeners:

src/events.ts

window.addEventListener('keydown', (event) => {
  switch (event.key) {
    case ' ': sceneSettings.pause = !sceneSettings.pause; break
    case 'a': case 'A': sceneSettings.enableGridHelper = !sceneSettings.enableGridHelper; break
    case 's': case 'S': sceneSettings.enableAxisHelper = !sceneSettings.enableAxisHelper; break
  }
})

Resize is debounced by 250 ms; onWindowResize updates the camera aspect, the renderer size, and the pixel ratio from the current stage size.

loaders.ts

loadAllAssets() loads the two runtime assets in parallel and returns the extracted vertices plus the texture:

src/loaders.ts

const [brainGeom, electricTexture] = await Promise.all([
  loadObj(objLoader, 'models/brain_vertex_low.obj'),
  loadTexture(textureLoader, 'sprites/electric.png')
])
return { vertices: extractVertices(brainGeom), electricTexture }

extractVertices reads the OBJ's position attribute into an array of Vector3. Those vertices are what the WASM World turns into neurons.

entry-server.ts

A small SSR entry used only by pnpm build:ssr. It returns a static HTML shell that hydrates on the client; it is not part of the default build.