The
apps/kalika/area: the deployable surface of Kalika, a computational mathematics/physics research-notebook workbench — a web client, a CLI, an auth-and-fan-out BFF, and three backing microservices (compute, notebooks, agents) that together turn symbolic/numeric computation, reactive notebooks, and multi-agent research into a runnable product.
What this area is#
Kalika is a notebook workbench for computational mathematics and physics. The
apps/kalika/ directory holds its runnable applications — the things you
build, serve, and ship — as opposed to the @kalika/* libraries (notebooks,
research-agents, tensor-networks, sdk, training-data, citations, core,
knowledge-graph, typesetting) that the apps compose. There are six Nx projects
here, all tagged scope:kalika, type:app: one browser app (@kalika/web),
one command-line app (@kalika/cli), one backend-for-frontend (@kalika/bff),
and three domain microservices (@kalika/svc-compute, @kalika/svc-notebooks,
@kalika/svc-agents).
The three services are independent Fastify processes, each owning one slice of
the product and each with its own default port: compute on 3331, agents on
3332, notebooks on 3333 (see the KALIKA_*_PORT defaults in each
src/index.ts). They do not call each other directly. Instead the BFF
(@kalika/bff, port 3330) is the single front door: it authenticates the
caller, then fans requests out to the three services over HTTP via typed clients
in apps/kalika/bff/src/clients.ts, and multiplexes their push events back to
the browser over a single WebSocket (apps/kalika/bff/src/realtime.ts). The web
app talks only to the BFF; the CLI bypasses the network entirely and drives the
compute logic in-process through @kalika/sdk.
The split is by capability. svc-compute is the math kernel: a symbolic CAS
(simplify/differentiate/integrate/solve/series/limit), a recursive-descent
numeric expression evaluator, matrix and tensor (einsum) operations, a
priority job queue with in-memory and Redis/BullMQ backends, streaming
computation, and an embedded browser-WASM arithmetic kernel with REST fallback.
svc-notebooks is the document engine: it composes the reactive CAS notebook
runtime from @kalika/notebooks (dependency-graph reactive execution,
collaboration sessions, templates, multi-format export, on-disk file sync).
svc-agents is the research-orchestration plane: a lifecycle manager around the
MultiAgentOrchestrator from @kalika/research-agents, with per-owner
token/compute budget accounting and cost estimation. @kalika/web is the React
- Monaco + KaTeX workbench (the 12K-line
App.tsxplus ~21 feature modules);@kalika/cliis the headless entry point for computation, notebook runs, and training-data corpus ingestion.
How it fits the wider system#
Kalika is largely a self-contained product cluster rather than a deep
participant in the cross-domain Oshun event bus. The dependency flow inside the
area is strict and one-directional: @kalika/web → @kalika/bff →
{svc-compute, svc-notebooks, svc-agents} over HTTP/WS; @kalika/cli →
@kalika/sdk/@kalika/notebooks/@kalika/training-data in-process. The one
cross-cutting Oshun dependency is @oshun/auth, which the BFF uses for JWT
verification, role hierarchy (hasMinimumRole), and permission resolution
(getPermissions) in apps/kalika/bff/src/auth.ts. Everything else the apps
import is a @kalika/* workspace library or a third-party package (fastify,
@fastify/websocket, bullmq, react, three, monaco-editor, katex).
The boundary contract between the BFF and the services is HTTP JSON with a small
header protocol — the BFF stamps x-kalika-user-id, x-kalika-session-id,
x-request-id, and x-kalika-scopes onto every upstream call
(HttpJsonClient.headers in clients.ts), so the services receive an
already-authenticated identity and never re-run auth themselves. Consumers of
this area are therefore: end users via the web/CLI front ends; and operators who
deploy the four server processes behind the BFF.
Entity catalog (6)#
The 6 tracked Nx projects in kalika, each a code-linked entity node — package, type, source path, declared targets, and its internal dependency graph (depends-on / used-by, resolved from the package manifests, §6/§8), read from the project graph. Grouped by architectural layer; walk the dependency links to travel the system. 6 of these carry an authored deep-dive (what / why / how it fits); the rest are generated scaffolds awaiting one.
unclassified (6)#
The backend-for-frontend and single front door for the Kalika workbench
(apps/kalika/bff/src). buildKalikaBffApp in app.ts wires a Fastify server
that authenticates every request (createKalikaAuthHook in auth.ts, accepting
both dev tokens and @oshun/auth HS256 JWTs), then exposes the unified
/api/v1/* surface — session/preferences, an aggregated /workbench payload
that Promise.all-fans-out to all three services, and full proxy routes for
compute, notebooks, agents, and research tasks. It owns the realtime layer
(KalikaRealtimeHub in realtime.ts): a per-user WebSocket hub with channel
subscriptions (compute, notebook:*, agent:*) that re-publishes upstream
events. Upstream calls go through typed clients in clients.ts over HTTP, with
UpstreamServiceError mapping 5xx to a 502. Sessions/preferences are held in an
InMemoryKalikaSessionStore (session.ts). Fully implemented, not a scaffold.
The headless command-line entry point (apps/kalika/cli/src). runCli in
commands.ts parses argv and dispatches to two families: in-process computation
via @kalika/sdk (eval, simplify, solve, plus integrate /
differentiate / series / limit parsed out of function-call syntax like
integrate(sin(x)^2, x)), and a large training-data subcommand delegated
wholesale to runTrainingDataCommand from @kalika/training-data (ingesting
proof-pile/formal-proof/arXiv-LaTeX/structured-DB corpora, synthetic generation,
math-classifier and quality-model training, dedup, domain balancing). It also
runs notebooks headlessly (kalika notebook run file.kalika-nb), deserializing
via @kalika/notebooks and executing each code/CAS cell through the SDK. The
CLI is the only app that does compute without touching the network. Fully
implemented.
The research-orchestration microservice (apps/kalika/svc-agents/src, default
port 3332). buildAgentServiceApp (app.ts) exposes agent lifecycle and
research-task REST routes; the real logic lives in
ResearchAgentLifecycleService (agent-service.ts), which manages a pool of
MultiAgentOrchestrator instances from @kalika/research-agents and runs them
under AbortController budgets with pause/resume/terminate transitions. Its
distinguishing feature is genuine budget accounting: buildCostEstimate
computes per-task token and compute-ms estimates from request size and task
count (literature/computation/exploration/proof phases), enforces per-owner
remaining budget before a run (reserveBudget throws on violation), prices runs
with Anthropic Claude input/output per-million-token rates
(estimateClaudeTextCostUsd), and reconciles reserved vs. measured usage in
recordUsage. State is held in an injectable AgentRepository
(InMemoryAgentRepository by default). Fully implemented.
The computation kernel microservice (apps/kalika/svc-compute/src, default port
3331). ComputeEngine (engine.ts) is a real, self-contained CAS + numerics
implementation: a hand-written recursive-descent NumericParser for arithmetic
with functions/constants, symbolic simplify/differentiate/integrate over
additive terms, linear-equation solving with a linearity check, Taylor series
for exp/sin/cos, limit evaluation (direct + known forms +
finite-difference), Gaussian-elimination determinant/inverse, and tensor
einsum via @kalika/tensor-networks. queue.ts adds a priority job queue
with two backends — InMemoryComputeQueueService (sequence+priority scheduler,
SHA-256 result cache, abort/timeout) and RedisComputeQueueService (BullMQ
Queue/Worker mirroring the in-memory executor) — and two physics task kinds:
IBP integral reduction and a seeded 2-D Ising lattice Monte Carlo with
Metropolis updates. browser.ts ships an embedded WASM arithmetic kernel
(add/sub/mul/div, real bytes + SHA-256) with a server-REST fallback;
streaming.ts drives WebSocket streaming compute. Fully implemented.
The notebook-document microservice (apps/kalika/svc-notebooks/src, default
port 3333). NotebookService (notebook-service.ts) composes the reactive
CAS notebook runtime from @kalika/notebooks — dependency-graph construction
(buildNotebookDependencyGraph), reactive and incremental execution planning
(planReactiveExecution / planIncrementalReactiveExecution), per-cell symbol
analysis and change detection, a CAS kernel context, and collaboration sessions
with locks/edits (applyNotebookCollaborationEdit, releaseNotebookCellLock).
It adds three local concerns on top: domain templates (templates.ts —
runnable starter notebooks like getting-started-quantum-mechanics and
computing-feynman-diagrams), multi-format export (exports.ts —
json/html/latex/pdf/ipynb/plain), and two-way file sync to disk
(file-sync.ts — fs.watch-based binding of a notebook to a
.kalika/.kalika-nb file with debounce/poll and external-change callbacks).
Fully implemented.
Kalika notebook workbench web application
The browser workbench (apps/kalika/web), a Vite-built React app whose entry is
src/main.tsx mounting App.tsx. This is the largest entity in the area: a
~12K-line App.tsx plus ~21 feature modules under src/, each with a colocated
.spec.ts. The UI is built on Monaco (@monaco-editor/react), KaTeX/MathJax
for typesetting, three for 3-D, and OpenDyslexic fonts, and it composes the
@kalika/notebooks, @kalika/citations, @kalika/core,
@kalika/knowledge-graph, and @kalika/typesetting libraries. The feature
modules implement real workbench capabilities — spatial-canvas.ts (pan/zoom
spatial layout geometry), ThreeDExplorer.tsx/three-d-explorer.ts,
ai-suggestions.ts, citation-sidebar.ts, knowledge-graph-browser.ts,
proof-exploration.ts, realtime-collaboration.ts, research-assistant.ts,
math-input.ts/accessible-math.ts, and several end-to-end *-workflow.ts
orchestrators (compute-write/verify, paper-generation, literature-informed,
explore-conjecture, theory-observable). It also carries Playwright e2e specs
including an accessibility-compliance suite (e2e/, ACCESSIBILITY_AUDIT.md).
Fully implemented.