peri fuse - Moses Yebei

The Problem

LLM developers lack an integrated, low‑overhead observability stack that can run locally without external services. Existing solutions often need ClickHouse, Redis, or S3, making local debugging and edge deployment difficult.

What This Does

Peri‑Fuse is a self‑contained LLM observability server that stores traces, spans, generations, and scores in an embedded Turso database. It exposes a Langfuse‑compatible REST API, an OpenTelemetry OTLP ingestion endpoint, and a Vite‑powered dashboard. The codebase is split into packages/cli, packages/gateway, packages/langfuse‑mcp, and packages/server. The CLI (packages/cli/src/index.ts) manages the lifecycle of the gateway (packages/gateway/src/app.ts) and the web dashboard (packages/server). The gateway routes LLM calls, applies rate‑limit and budget‑limit hooks, and forwards them to providers defined in packages/gateway/src/provider/*.

How It Is Wired

Execution starts in packages/cli/src/index.ts where the start command launches the gateway. The gateway’s entry point is packages/gateway/src/app.ts, which registers middleware (middleware/auth.ts, middleware/request‑limits.ts) and mounts routers (router/index.ts). The admin router (admin-router.ts) exposes endpoints for audit, budgets, and credentials. The proxy router (proxy-router.ts) forwards /chat, /messages, and /models to provider adapters (provider/openai.ts, provider/anthropic.ts). These adapters call the external LLM APIs and return responses that are logged by hooks/peri‑fuse‑logger.ts. All database interactions happen through packages/gateway/src/db.ts, which uses the Prisma schema (prisma/schema.prisma) and Drizzle migrations located under drizzle/. The minimal call chain for a chat request is: client → gateway/app.ts → router/proxy/chat.ts → provider/openai.ts → external API → provider/openai.ts → gateway/app.ts → db.ts. Only 2–3 hops touch the filesystem (database writes) or network (LLM calls). The gateway’s hooks provide the widest blast radius: changing rate‑limiter.ts affects every request, while budget‑reset.ts touches only budget tables.

How To Use It

Setup

git clone https://github.com/moses-y/peri-fuse
cd peri-fuse
pnpm install

Configuration Copy .env.example to .env and set LITE_SERVER_PORT if you need a custom port. For remote Turso storage, supply TURSO_URL and TURSO_TOKEN.

Running locally

pnpm dev

The API is available at http://localhost:23432, and the dashboard at http://localhost:5173. Alternatively, build the production assets and run as a background service:

pnpm build
pnpm svc:start
pnpm svc:status
pnpm svc:logs
pnpm svc:stop

Docker

docker compose up -d
curl http://localhost:23332/api/public/health

The image uses the same Bun runtime and keeps the ./data volume for persistence.

Real‑World Use

A data‑science team can proxy all OpenAI calls through Peri‑Fuse to enforce a daily spend budget. By configuring packages/gateway/src/spend/calculator.ts with a 10 USD limit and adding a project key, every request is checked against the budget. If exceeded, the provider adapter throws a 429 and the gateway returns a friendly error. The team can then query the audit logs (/admin/audit) to see which prompts consumed the budget.

Code Health & Issues

Low – Secret‑shaped paths in packages/gateway/test/admin-provider-secrets.test.ts (potential accidental commit of sensitive data).
Low – The repo contains 173 test files, but integration tests rely on a running Turso instance; CI may fail if the service is unavailable.
Moderate – No explicit linting configuration; the repo uses biome.json, but no GitHub Actions step invokes it.
Low – The README specifies Bun 1.4.2 as a requirement, but the Dockerfile uses Debian with Node 22; there is no automated check for Bun availability.

The Bottom Line

Peri‑Fuse delivers a compact, fully local LLM observability stack that fits small teams and edge deployments. Its clear package split and minimal external dependencies make it easy to modify. The main trade‑off is the reliance on Bun for runtime, which may limit adoption in environments that cannot install Bun. Overall, it is a practical choice for developers who need instant tracing, budgeting, and a Langfuse‑compatible API without running heavyweight infrastructure.

What the analyser found

Deployment readiness

6/7

Container image
CI pipeline
Lockfile committed
Test suite
README
License
No committed secrets

Composition

1,386 files

TypeScript722
SQL432
TSX96
Markdown59
JSON21
YAML5

ReactDockerTransformersLangChain

Module dependencies

The 10 most depended-upon modules of 848, from static import analysis. Red outline marks a module in an import cycle.

graph LR n0_packages_shared_src_db_local["local"] n1_packages_server_src_auth["auth"] n2_server_src___tests___helpers["helpers"] n3_packages_shared_src_db["db"] n4_ges_shared_src_server_logger["logger"] n5_ed_src_server_adapters_index["index"] n6_s_shared_src_db_schema_index["index"] n7_es_server_src_response_cache["response-cache"] n8_packages_gateway_src_db["db"] n9_ckages_gateway_src_db_schema["schema"] n8_packages_gateway_src_db --> n9_ckages_gateway_src_db_schema n2_server_src___tests___helpers --> n1_packages_server_src_auth n7_es_server_src_response_cache --> n1_packages_server_src_auth

Dependencies

9 of 22 declared dependencies are a major version behind. Resolved 21 of 22 against the registry.

Package	Declared	Latest	Behind
`@types/node`	^24.3.0	26.2.0	2 major
`typescript`	^5.9.2	7.0.2	2 major
`concurrently`	^9.1.0	10.0.5	1 major
`commander`	^14.0.1	15.0.0	1 major
`dotenv`	^16.4.5	17.4.2	1 major
`@hono/node-server`	^1.19.14	2.1.1	1 major
`@paralleldrive/cuid2`	^2.2.2	3.3.0	1 major
`bcryptjs`	^2.4.3	3.0.3	1 major

Findings

LowSecret-shaped paths present; the code-health audit confirms or clears them packages/gateway/test/admin-provider-secrets.test.ts

What would stop me shipping this

Ranked by severity × confidence × production reach. Reach is the honest discriminator across a collection that is mostly other people's code: the same finding matters more in something that ships.

high2

medium5

low2

Pin third-party GitHub Actions to a commit SHAhigh6 occurrences

.github/workflows

docker/setup-qemu-action@v3, docker/setup-buildx-action@v3, docker/login-action@v3, docker/metadata-action@v5

A tag can be moved, so the action running with your token and secrets is whatever its owner last pushed; this is how tj-actions/changed-files leaked secrets from thousands of repos.

Fix: Replace each @vN with the 40-character commit SHA, keep # vN as a comment, and let Dependabot bump the SHAs.

Make CI invoke the test suite it hashigh161 occurrences

.github/workflows

161 test files, no test command in any workflow

A green check that never executed an assertion is worse than no check, because reviewers trust it.

Fix: Add a test step to the existing workflow rather than a new workflow.

Enable Dependabot or Renovatemedium

7 manifest(s), no update bot configured

Without a bot a published advisory sits unpatched until someone audits by hand, which across 1,322 repositories means never.

Fix: Commit .github/dependabot.yml covering the repo ecosystems plus github-actions.

Pin the container base image by digestmedium3 occurrences

Dockerfile

node:22-bookworm-slim, oven/bun:1.4.2-debian, node:22-bookworm-slim

An untagged or mutable base means today's build and last month's contain different libc and a different CVE set, with no record of which shipped.

Fix: Use image:tag@sha256:<digest> and enable Dependabot's docker ecosystem.

Gate pull requests on a dependency vulnerability scanmedium

.github/workflows

no dependency scan in CI

This is the one gate that would catch a known-vulnerable package before it reaches a build, and no repository in the sample had it.

Fix: Add dependency-review-action on pull_request, or osv-scanner on push and a schedule.

Set persist-credentials: false on checkoutmedium

.github/workflows/npm-publish.yml

checkout keeps the token, then dependencies are installed

The token stays in .git/config for every later step, so a malicious postinstall script reads a pushable credential without one ever being passed to it.

Fix: Add with: persist-credentials: false, and pass an explicit token only to the step that pushes.

Add a non-root USER to the imagemedium

Dockerfile

CMD or ENTRYPOINT with no USER directive

A process running as root in the container is root against every mounted volume, and it turns any container escape or writable-mount mistake from a contained problem into a host one.

Fix: Create an unprivileged user, chown what it needs, and end the Dockerfile with USER.

Set timeout-minutes on the workflow jobslow2 occurrences

.github/workflows/docker-ghcr.yml

2 workflow(s) declare no job timeout

A wedged step runs to the six-hour platform default, which on a two-hourly schedule means three runs overlap behind it.

Fix: Add timeout-minutes with a realistic bound to each job.

Add the repository convention files this project lackslow3 occurrences

missing .editorconfig, .gitattributes, a formatter config

Without them one contributor's editor writes tabs into a Python file, a shell script commits with CRLF and fails in the container, and a notebook diff is unreviewable.

Fix: Add .editorconfig, .gitattributes with text=auto eol=lf, and a formatter config.

Checked deterministically against the repository tree and a bounded set of its files: committed credentials, unpinned actions and base images, missing lockfiles and update bots, workflows that discard failures, published advisories against the declared dependencies, runtime configuration, licensing and notebook reproducibility. No language model is involved in this section.