Configuration Files for OmniRoute: A Complete Guide to Runtime Settings and Project Structure

OmniRoute stores its runtime settings, feature toggles, internationalization data, and quality-gate baselines in JSON files under the config/ directory, with additional configuration files in the project root that are loaded at startup and exposed through the Settings skill API.

The open-source OmniRoute repository (diegosouzapw/OmniRoute) relies on a structured configuration system to define runtime behavior without modifying source code. These configuration files for OmniRoute govern everything from request payload validation to language localization and bundle size limits, making them essential for administrators customizing the proxy/router to their environment.

Core Configuration Files in the config/ Directory

The config/ folder contains the primary JSON files that control OmniRoute's runtime behavior. These files are read by the server at startup and exposed through the Settings skill endpoints.

Payload Validation Rules (config/payloadRules.json)

The payloadRules.json file defines rules that filter or reshape incoming request payloads, including size limits and prohibited fields. This configuration is consumed by the request-validation middleware in src/middleware/payloadValidator.ts to sanitize incoming traffic before it reaches application logic.

Internationalization Data (config/i18n.json and config/i18n-schema.json)

The i18n.json file serves as the global localization catalogue, mapping language codes to translation files used by both the UI and CLI. The Settings skill and internationalization layer (src/i18n/*) depend on this file to serve the correct language bundles.

The i18n-schema.json file provides a JSON-Schema definition that validates the structure of i18n.json. According to the OmniRoute source code, the validation step in src/lib/validation/i18nValidator.ts ensures new languages conform to the expected schema before being accepted.

Quality Gate Baselines (config/quality/*.json)

The config/quality/ directory contains a collection of baseline JSON files used by the Quality Gate tooling to enforce code-quality metrics. These files define thresholds for complexity, duplication, and file-size limits. The CI scripts in scripts/check/quality/ read these baselines during automated checks to determine if code changes meet project standards.

Project Root Configuration Files

Beyond the config/ directory, OmniRoute maintains several critical configuration files in the repository root that control the build process, dependencies, and development environment.

Environment Variables (.env.example)

The .env.example file serves as a template for environment variables required at runtime, including API keys, database paths, and feature flags. Developers copy this file to .env and populate it with secrets during onboarding. The server initialization code in src/server/init.ts loads these variables to configure the runtime environment.

TypeScript Compiler Settings (tsconfig.json variants)

OmniRoute uses multiple TypeScript configuration files to support different build and check scenarios:

• tsconfig.json – Primary compiler options for the main application build
• tsconfig.typecheck-core.json – Strict type-checking configuration for core modules
• tsconfig.typecheck-noimplicit-core.json – Alternative type-checking rules without implicit any checks

These files are consumed by the build pipeline via npm run typecheck:* scripts to ensure type safety across different code paths.

Dependency and Build Configuration

The repository includes several additional root-level configuration files:

• package.json and package-lock.json – Define project dependencies, npm scripts, and metadata for installation and CI builds
• .size-limit.json – Configures the size-limit tool to enforce bundle size caps during CI runs via npm run size-limit
• .markdownlint.json – Specifies linting rules for Markdown documentation, consumed by npm run lint:md in the documentation CI pipeline

How OmniRoute Loads Configuration at Runtime

Configuration files are loaded at startup using a utility function pattern found in src/lib/config/load.ts. This pattern uses Node.js filesystem APIs to read and parse JSON files synchronously during initialization.

// src/lib/config/load.ts
import { readFileSync } from 'fs';
import { resolve } from 'path';

export function loadJson<T>(relativePath: string): T {
  const fullPath = resolve(process.cwd(), relativePath);
  const raw = readFileSync(fullPath, 'utf-8');
  return JSON.parse(raw) as T;
}

// Example usage in src/server/init.ts
const payloadRules = loadJson<Record<string, unknown>>('config/payloadRules.json');
console.log('Payload max size →', payloadRules.maxBytes);

The Settings skill exposes these configurations through REST endpoints. Administrators can query current settings via the /api/settings/* endpoints, which map to src/lib/db/settings.ts for reading the underlying JSON files.

# Get the current payload rules

curl -X GET https://localhost:20128/api/settings/payload-rules \
  -H "Authorization: Bearer $OMNIRoute_API_KEY"

Modifying Configuration Programmatically

While the Settings UI (pages/settings/payload-rules.tsx) provides a frontend interface, administrators can also update configurations programmatically by merging changes into the JSON files directly.

import { readFileSync, writeFileSync } from 'fs';
import { resolve } from 'path';

function updatePayloadRules(updates: Partial<Record<string, unknown>>) {
  const cfgPath = resolve('config/payloadRules.json');
  const current = JSON.parse(readFileSync(cfgPath, 'utf-8'));
  const merged = { ...current, ...updates };
  writeFileSync(cfgPath, JSON.stringify(merged, null, 2));
}

// Increase the request-size limit to 5 MiB
updatePayloadRules({ maxBytes: 5 * 1024 * 1024 });

This merge pattern mirrors the persistence logic in the Settings UI, ensuring that partial updates do not overwrite unrelated configuration keys.

Accessing Configuration in the Frontend

The frontend application directly imports configuration files where appropriate. For example, the locale switcher component in src/app/components/LocaleSwitcher.tsx imports i18n.json to build the language selection interface.

// src/app/components/LocaleSwitcher.tsx
import localeData from '../../config/i18n.json';

export function LocaleSwitcher() {
  return (
    <select>
      {Object.entries(localeData).map(([code, name]) => (
        <option key={code} value={code}>
          {name}
        </option>
      ))}
    </select>
  );
}

The i18n.json file is validated against i18n-schema.json at startup, preventing runtime errors from malformed localization data.

Summary

• OmniRoute configuration files reside primarily in the config/ directory, with additional files in the project root for build and environment management.
• config/payloadRules.json controls request validation rules consumed by src/middleware/payloadValidator.ts.
• config/i18n.json and config/i18n-schema.json manage localization data and schema validation for the internationalization layer.
• config/quality/*.json provides baselines for automated quality gates in CI pipelines.
• .env.example, tsconfig*.json, and package.json support development, compilation, and dependency management.
• The Settings skill API (/api/settings/*) exposes these files for runtime querying and modification without requiring server restarts for most changes.

Frequently Asked Questions

Where are OmniRoute configuration files stored?

OmniRoute stores runtime configuration files in the config/ directory at the repository root, with specific files like payloadRules.json, i18n.json, and i18n-schema.json located there. Additional configuration files—including .env.example, tsconfig.json variants, and .size-limit.json—reside in the project root to manage build processes and environment variables.

How do I update payload validation rules in OmniRoute?

You can update payload rules by modifying config/payloadRules.json directly or by using the Settings skill API endpoint at /api/settings/payload-rules. The server uses the loadJson function in src/lib/config/load.ts to read these rules at startup, and the Settings UI (pages/settings/payload-rules.tsx) provides a web interface for administrators to modify size limits and prohibited fields without editing files manually.

What is the purpose of i18n-schema.json in OmniRoute?

The i18n-schema.json file provides a JSON-Schema definition that validates the structure of i18n.json. According to the OmniRoute source code, the validation step in src/lib/validation/i18nValidator.ts uses this schema to ensure that new language entries conform to expected formats before being accepted into the configuration, preventing runtime errors in the internationalization layer (src/i18n/*).

Can I modify OmniRoute settings without restarting the server?

Yes, many OmniRoute settings can be modified at runtime through the Settings skill API (/api/settings/*), which exposes endpoints backed by src/lib/db/settings.ts. While the server loads initial configurations at startup via import or require statements in src/server/init.ts, the Settings skill persists changes back to the JSON files or to a SQLite key-value store for transient settings, allowing dynamic updates without requiring a full server restart.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}