Traceway

Observability for LLM apps: traces, spans, tokens, cost, datasets, review queues, and analytics.

README Navigation

• Quick Start
• Running
• Contributing
• Architecture
• Traceway API (Encore)
• Ingestor Daemon (Rust)
• Full System Architecture

Quick Start

1) Install prerequisites

• Node.js 20+
• npm
• Encore CLI (required for the new API): https://encore.dev/docs/ts/install

Quick check:

encore version
node -v

2) Clone and configure

git clone https://github.com/andrewn6/llm-fs.git
cd llm-fs
cp backend/app/.env.example backend/app/.env
cp ui/.env.example ui/.env

3) Run backend API (Encore)

cd backend/app
encore run

4) Run UI (new terminal)

cd ui
npm install
npm run dev

Local endpoints:

• API: http://localhost:4000
• Encore dashboard: http://localhost:9400
• UI: http://localhost:5173

Smoke test:

curl http://localhost:4000/health

Running

Product stack (recommended)

# Terminal 1
cd backend/app && encore run

# Terminal 2
cd ui && npm run dev

Optional: Rust ingestor/infra daemon

cargo run -p traceway --features cloud -- --cloud

Use this when working on ingest/infra paths (not required for normal UI + API product development).

Contributing

• Start with CONTRIBUTING.md
• Backend service docs: backend/app/README.md
• UI docs: ui/README.md

Architecture

Traceway now runs with an Encore-first product API.

• backend/app (Encore.ts): browser-facing API, auth, org/project domains, traces/spans/files, datasets/queue/evals, analytics, billing.
• ui (SvelteKit): primary web app.
• Rust components: ingest + infra responsibilities.
• Postgres: source of truth.
• Turbopuffer: secondary search index (best-effort mirror).

Traceway API (Encore)

Location: backend/app

Core responsibilities:

• Auth and session flows
• Trace/span CRUD and live updates (SSE)
• File-version and dataset/review workflows
• Analytics and dashboard queries
• Provider connection and billing endpoints

Dev workflow:

cd backend/app
encore run

Generate OpenAPI + UI types (from repo root):

encore gen client --lang openapi --output "openapi.json"
npx openapi-typescript "openapi.json" -o "ui/src/lib/api-types.ts"

Ingestor Daemon (Rust)

The Rust side is moving toward focused ingest/infra duties:

• OTLP and ingestion-related runtime paths
• local daemon lifecycle/config utilities
• infrastructure-specific processing

It is optional for most product UI/API changes.

Full System Architecture

Your App / SDKs
      |
      v
Traceway API (Encore, backend/app)  <---->  UI (SvelteKit, ui/)
      |
      +----> Postgres (primary source of truth)
      |
      +----> Turbopuffer (secondary search index)
      |
      +----> Optional Rust ingest/infra services

SDKs

• Python: sdk/python/
• TypeScript: sdk/typescript/

License

MIT