No native build steps are required. If you add local model support via Ollama, ensure Ollama is running as a sidecar process; no native node bindings are involved.

Project setup

1. Copy the source/ directory into your project root, e.g. as packages/backend/src/.

2. Set rootDir and paths in tsconfig.json:

   {
     "compilerOptions": {
       "module": "commonjs",
       "target": "ES2021",
       "experimentalDecorators": true,
       "emitDecoratorMetadata": true,
       "rootDir": "packages/backend/src",
       "outDir": "dist",
       "strict": true
     }
   }
   

3. Set required environment variables (create a .env file):

   PORT=3001
   NODE_ENV=development
   BETTER_AUTH_URL=http://localhost:3001
   DATABASE_URL=sqlite://./manifest.db
   THROTTLE_TTL=60000
   THROTTLE_LIMIT=100
   # Optional:
   WINGMAN_PORT=3002
   FRAME_ANCESTORS=https://your-dashboard.example.com
   

4. Add a main.ts entrypoint (or use the one provided):

   import { bootstrap } from './main';
   bootstrap();
   

5. Register app.module.ts as the root module. All feature modules are already imported there; no additional wiring is needed unless you add your own modules.

6. Build and run:

   npx ts-node -r tsconfig-paths/register packages/backend/src/main.ts
   # or with NestJS CLI:
   nest start
   

Public API

bootstrap

export async function bootstrap(): Promise<void>

The application entrypoint. Creates the NestJS application from AppModule, applies Helmet CSP (with HSTS conditional on HTTPS), enables compression, registers the SpaFallbackFilter, wires BetterAuth middleware, and starts listening. Call this once from your process entrypoint. Override PORT, BETTER_AUTH_URL, and FRAME_ANCESTORS via environment variables to control binding and security headers.

detectSpecificity

export { detectSpecificity } from './specificity-detector';
export type { SpecificityResult } from './specificity-detector';

Analyzes a prompt or message set and returns a SpecificityResult indicating how specific (vs. general) the request is. Use this directly in non-NestJS code (e.g. an Edge function or a Lambda) to decide whether to route to a cheaper general model or a specialized one, without instantiating the full NestJS app.

scanMessages

export { scanMessages } from './scan-messages';

Scans an array of chat messages and returns structured signal data used by the scoring pipeline. Use it upstream of the full scorer when you only need keyword and structural signals, or when you want to inspect intermediate scoring inputs for debugging or custom routing rules.

ScorerInput / ScoringResult / Tier (scoring types)

export type { ScorerInput, ScoringResult, ScorerConfig, DimensionScore, Tier, ScoringResult } from './types';
export type { MomentumInput } from './momentum';

Core types for the scoring engine. ScorerInput carries the messages and conversation context; ScoringResult contains dimension scores, the final Tier ('low' | 'medium' | 'high'), confidence, and reasons. Wire these types into your own routing middleware to annotate requests before forwarding.

Working examples

Scenario - Bootstrap the full backend

Stand up the complete Manifest backend, including routing proxy, analytics, and auth, using the provided bootstrap function.

// entrypoint.ts
import { bootstrap } from './packages/backend/src/main';

bootstrap().catch((err) => {
  console.error('Fatal startup error', err);
  process.exit(1);
});

Set PORT=3001 and BETTER_AUTH_URL=http://localhost:3001 in your environment, then run:

npx ts-node entrypoint.ts

The server starts on port 3001, serves the SPA from FRONTEND_DIST if set, and exposes /api/* and /v1/* routes.

Scenario - Run the complexity scorer standalone

Use the scoring engine outside NestJS to score a single user message and decide routing tier before sending to an LLM provider.

import { detectSpecificity, SpecificityResult } from './packages/backend/src/scoring';
import { scanMessages } from './packages/backend/src/scoring';

const messages = [
  { role: 'user', content: 'Write a recursive Fibonacci function in TypeScript with memoization and explain the time complexity.' }
];

const specificity: SpecificityResult = detectSpecificity(messages);
console.log('Specificity:', specificity);

const signals = scanMessages(messages);
console.log('Scan signals:', signals);

// Route to a capable model only when specificity or complexity is high
if (specificity.score > 0.6) {
  console.log('Route to high-tier model');
} else {
  console.log('Route to low-tier model');
}

Scenario - Attach the API key guard to an existing Express/NestJS controller

Reuse the ApiKeyGuard to protect a custom endpoint you add alongside the existing routes.

// my-custom.controller.ts
import { Controller, Get, UseGuards } from '@nestjs/common';
import { ApiKeyGuard } from './packages/backend/src/common/guards/api-key.guard';

@Controller('api/my-endpoint')
@UseGuards(ApiKeyGuard)
export class MyCustomController {
  @Get()
  getData() {
    return { status: 'ok' };
  }
}

Register MyCustomController in a feature module imported by AppModule. The guard reads the x-api-key header and validates it against stored ApiKey entities.

File walkthrough

• main.ts - Bootstraps NestJS, configures Helmet CSP (HSTS, frame-src, upgrade-insecure-requests), compression, BetterAuth middleware, and the SPA fallback filter.
• app.module.ts - Root @Module that assembles all feature modules, registers global cache, throttler, TypeORM, and static file serving.
• analytics/ - Feature module exposing REST endpoints for agent analytics, cost breakdowns, token usage, savings, and message details; backed by TypeORM query services.
• auth/ - Wraps BetterAuth (better-auth package) into a NestJS module; provides SessionGuard and @CurrentUser() decorator.
• common/ - Barrel of cross-cutting concerns: ApiKeyGuard, cache interceptors, SPA fallback filter, HTTP error logger middleware, DTOs (create-agent, range-query, savings-query), and shared constants.
• config/ - Exports appConfig factory consumed by ConfigModule.forRoot.
• database/ - DatabaseModule configuring TypeORM with environment-driven connection settings.
• entities/ - TypeORM entities such as ApiKey.
• free-models/ - Identifies models that are free-tier or locally hosted and exposes them via its module.
• github/ - Polls GitHub releases for version-check notifications.
• health/ - Standard /health liveness and readiness endpoint.
• model-discovery/ - Discovers available models from each configured provider at runtime.
• model-prices/ - Fetches and caches per-token prices for cost accounting.
• notifications/ - Sends alerts when spend or error thresholds are crossed.
• otlp/ - Accepts OTLP HTTP trace data from instrumented clients and stores spans.
• public-stats/ - Serves aggregated, anonymized statistics for the public dashboard.
• routing/ - Core proxy: selects model based on scorer output and custom headers, forwards the OpenAI-compatible request, handles retries and fallback.
• scoring/ - Pure TypeScript complexity/specificity scorer: keyword trie, structural dimensions, sigmoid confidence, momentum, tier assignment.
• setup/ - First-run wizard that walks the user through provider configuration.
• sse/ - Server-Sent Events module for streaming router status updates to the dashboard.
• telemetry/ - Configures OpenTelemetry SDK and exports traces to a collector.

Common pitfalls and fixes

• emitDecoratorMetadata not set: NestJS DI silently breaks; add "emitDecoratorMetadata": true to tsconfig.json.
• BETTER_AUTH_URL missing: Auth middleware throws at startup; always set this env var even in development.
• SPA fallback intercepts API 404s: The SpaFallbackFilter only catches non-/api and non-/v1 paths; ensure all your custom routes start with /api/ or /v1/.
• HSTS enabled on HTTP: HSTS is gated on BETTER_AUTH_URL starting with https://; using an HTTP URL in production will leave HSTS disabled—use a TLS-terminating reverse proxy.
• upgrade-insecure-requests breaks LAN deploys: The bootstrap explicitly sets this to null; do not re-enable it via Helmet options on HTTP-only LAN deployments.
• TypeORM entity scan misses new entities: DatabaseModule must explicitly list or glob entities; add any new entity to the module's entities array or its glob pattern.
• Cache TTL unit mismatch: DASHBOARD_CACHE_TTL_MS is in milliseconds; @nestjs/cache-manager v2+ expects milliseconds, but v1 expects seconds—pin cache-manager to the version matching your @nestjs/cache-manager version.

Vibe-coding prompt template

I have dropped the Manifest AI Router Backend source into `packages/backend/src/`.
I also have `USAGE.md` in the same directory.

Please help me integrate this into my existing Node.js/TypeScript project step by step:

1. Read `USAGE.md` for the full setup instructions, required dependencies, and environment variables.
2. Read `packages/backend/src/main.ts` to understand the bootstrap flow.
3. Read `packages/backend/src/app.module.ts` to understand which NestJS modules are wired.
4. Read `packages/backend/src/scoring/index.ts` to understand the public scoring API.

Then:
- Install all required npm dependencies listed in USAGE.md.
- Update my `tsconfig.json` to enable `experimentalDecorators` and `emitDecoratorMetadata`.
- Create or update my `.env` file with the required environment variables.
- Wire the `bootstrap()` function from `main.ts` as my process entrypoint.
- Show me how to call `detectSpecificity` and `scanMessages` from the scoring module in a standalone script.
- If I need to add a custom protected endpoint, show me how to use `ApiKeyGuard` from `common/guards/api-key.guard.ts`.

Point out any conflicts with my existing code and suggest how to resolve them.
The upstream project is the Manifest AI Router (manifest-cms backend domain).

License and credit

The upstream project is licensed under the terms stated in source/LICENSE (see the repository at github.com/mnfst/manifest). The README states the license badge links to LICENSE in the repository root. Review that file before redistributing. The legacy manifest npm package is deprecated; the current distribution is the Docker image manifestdotbuild/manifest.

This product’s unique contribution is clean room implementation of valuable code block into AVCP compatible standard.

The full install guide and integration prompts unlock after purchase.