Make a real request path
read like architecture.

Quick start

Install the runtime pinned in .nvmrc, install the locked dependency graph, and start the collector plus Vite UI together.

git clone https://github.com/OthmaneBlial/Runtime-Atlas.git
cd Runtime-Atlas
nvm install && nvm use
npm ci && npm run dev

Open the loopback URL printed by Vite — normally http://127.0.0.1:5173, or the next available port. The API and collector run at 127.0.0.1:4319.

Local demo

The demo topology appears before traffic arrives. Run one of three deterministic scenarios from the workspace, then select trace history, scrub replay, inspect a node, export, or clear the retained evidence.

EXPAND ↗

Instrument with the Node.js SDK

The workspace package @runtime-atlas/sdk emits trace and span lifecycle events while keeping observed application requests independent from collector availability. It is currently a local workspace artifact, not a claimed public registry release.

Build and link the workspace package

npm run build:sdk

Wrap application work

import { createAtlas } from "@runtime-atlas/sdk";

const atlas = createAtlas({
  serviceName: "orders-api",
  collectorUrl: "http://127.0.0.1:4319",
  maxQueueSize: 2_000,
  requestTimeoutMs: 3_000,
  onError: (error) =>
    applicationLogger.warn({ error }, "atlas collector unavailable"),
});

const ordersDb = atlas.database(
  { id: "db.orders", label: "Orders DB", meta: { engine: "PostgreSQL" } },
  async () => saveOrder(),
);

const createOrder = atlas.route(
  { id: "route.orders", label: "POST /orders" },
  async () => ordersDb(),
);

Use request middleware safely

Connect/Express applications can use atlas.httpMiddleware(). Normalize user-specific path segments before telemetry leaves the process; the SDK removes query strings and URL fragments but cannot know which remaining segments identify a user.

app.use(
  atlas.httpMiddleware({
    path: (request) =>
      (request.originalUrl ?? request.url ?? "/").replace(
        /\/\d+(?=\/|$)/g,
        "/:id",
      ),
    ignore: (request) => request.url === "/health",
  }),
);

Download the complete TypeScript example ↓ Browse SDK source ↗

Connect OpenTelemetry

Configure an OTLP/HTTP exporter to send JSON to the exact traces endpoint. Uncompressed and gzip-compressed OTLP JSON are supported. Binary protobuf and gRPC are intentionally not accepted.

Test the bundled payload

curl --request POST http://127.0.0.1:4319/v1/traces \
  --header 'content-type: application/json' \
  --data-binary @examples/otlp-trace.json

Span reconciliation order

1. 01
   Explicit node IDruntime.atlas.node_id
2. 02
   Code provenancecode.function.name · code.file.path · code.line.number
3. 03
   HTTP evidencehttp.request.method · http.route
4. 04
   Bounded inferencedatabase · messaging · service · code allowlist

Download the standards-shaped OTLP payload ↓

Point the analyzer at TypeScript

Configure one or more comma-separated source globs. The analyzer uses ts-morph without executing the target application.

ATLAS_SOURCE_GLOB='../orders-api/src/**/*.ts' \
ATLAS_PROJECT_NAME='orders-api' \
ATLAS_ENVIRONMENT='development' \
npm start

Calls may live inside application factories. IDs, labels, metadata, and source locations must remain literal enough to prove. Dynamic descriptors or wrappers that hide these call shapes may appear only as visibly runtime-only nodes.

Architecture

The Express application owns analysis, validation, ingestion, retained trace state, SSE, and the production UI. The process boundary owns configuration, structured logs, sockets, and graceful shutdown.

Ordered runtime model

Each event receives an increasing collector sequence. The UI uses that sequence rather than service clocks to follow the newest evidence and compute replay state.

Read the source architecture note ↗

HTTP surface

Every response receives a request ID and restrictive browser security headers.

Configuration

The server reads environment variables directly and does not auto-load .env files. Invalid configuration fails before the listener starts.

Privacy and security boundaries

Trace evidence stays in process memory. Restarting the server clears it; authorized users may also clear it through the UI when that capability is enabled.

Source inspection

/api/source returns a small context window only when the exact file and line belong to an analyzed node. It defaults on for loopback and off for non-loopback bindings.

Shared network rule

Privacy model ↗ Security policy ↗

Production and container deployment

Compiled Node.js process

nvm use
npm ci
npm run build
NODE_ENV=production npm start

Open http://127.0.0.1:4319. GET /health proves liveness; GET /ready also analyzes the configured source and verifies the built UI.

Hardened local container

docker compose up --build

The image runs as the unprivileged node user. Compose binds the exposed port to loopback, uses a read-only filesystem, and enables demo-only source and clear controls.

Shared network checklist

• Terminate TLS and require user authentication at a reverse proxy.
• Generate an ATLAS_INGEST_TOKEN of at least 16 characters.
• Keep source inspection and trace clearing disabled unless explicitly needed.
• Trust a proxy hop only when the deployment actually uses that trusted topology.
• Tune body, span, concurrency, rate, event, trace, and SSE limits for available memory.
• Use one process per instance; in-memory trace state is not coordinated across replicas.

On SIGINT or SIGTERM, the server closes SSE clients, stops accepting new connections, waits for active sockets, then enforces the configured shutdown deadline. Rollback requires no persistent schema migration.

Validation

The repository exposes one complete local gate:

npm run check

Browser tests fail on unexpected console errors, page exceptions, failed requests, HTTP errors, accessibility violations, or mobile horizontal overflow. The production smoke enforces 100 KiB JavaScript and 20 KiB CSS gzip entry-asset budgets.

npm test
npm run test:e2e
npm run typecheck
npm run lint
npm run build
npm run smoke
npm audit --omit=dev --audit-level=high
docker build --tag runtime-atlas:local .

Troubleshooting

Compatibility, limits, and support

Use GitHub Issues for reproducible bugs and focused feature requests. Security reports belong in the repository’s private vulnerability process, not a public issue.