Configuration File for OmniRoute: Complete Guide to JSON Settings and Environment Variables

OmniRoute stores its runtime settings in multiple JSON files under the config/ directory—including payload rules, internationalization data, and quality gate baselines—alongside environment variables in .env files and build configurations in the project root.

OmniRoute is a routing and proxy application that centralizes its runtime behavior, feature toggles, and localization data in a structured configuration system. The repository diegosouzapw/OmniRoute maintains these settings in the config/ folder and supplementary files in the project root, which are read at startup and exposed through the Settings skill endpoints.

Core Configuration Files in the config/ Directory

The config/ folder contains the primary configuration files that define runtime behavior for OmniRoute.

Payload Validation Rules (config/payloadRules.json)

The config/payloadRules.json file defines rules that filter or reshape incoming request payloads, including size limits and prohibited fields. This file is consumed by the request-validation middleware located at src/middleware/payloadValidator.ts to enforce security policies at the edge.

Internationalization Settings (config/i18n.json)

Global localization data resides in config/i18n.json, which maps language codes to translation bundles used by both the UI and CLI. The config/i18n-schema.json companion file provides JSON-Schema validation to ensure new language entries conform to the expected structure, utilized by src/lib/validation/i18nValidator.ts at startup.

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

The config/quality/ directory contains JSON baseline files used by the Quality Gate tooling to enforce code-quality metrics such as complexity, duplication, and file size limits. These configurations are consumed by CI scripts in scripts/check/quality/ during automated build verification.

Environment and Build Configuration

Beyond the config/ directory, OmniRoute relies on several root-level configuration files for environment setup and build tooling.

Environment Variables (.env.example)

The .env.example file serves as a template for required environment variables, including API keys, database paths, and feature flags. Developers copy this file to .env and populate it with secrets required for runtime operation.

TypeScript Compiler Options (tsconfig*.json)

Three TypeScript configuration files define compiler behavior:

• tsconfig.json for the main application build
• tsconfig.typecheck-core.json for strict type-checking runs
• tsconfig.typecheck-noimplicit-core.json for alternative strictness profiles

These are consumed by the build pipeline via npm run typecheck:* scripts.

Additional Tooling Configs

Supplementary configuration files include:

• .size-limit.json – Enforces bundle size caps via the size-limit tool in CI
• .markdownlint.json – Defines linting rules for documentation
• package.json and package-lock.json – Manage dependencies and npm scripts

Accessing and Modifying Configuration Files

OmniRoute exposes configuration data through the Settings skill, allowing both programmatic access and REST API manipulation.

Loading JSON Configurations at Runtime

The server utilizes a loadJson utility pattern to import configuration files at startup. In src/lib/config/load.ts, the implementation reads files synchronously and parses them into typed objects:

// 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;
}

// Usage example
const payloadRules = loadJson<Record<string, unknown>>('config/payloadRules.json');
console.log('Payload max size →', payloadRules.maxBytes);

This pattern is utilized throughout server initialization in src/server/init.ts.

Querying Settings via the REST API

Administrators can retrieve configuration values through the Settings skill endpoints. For example, querying the current payload rules:

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

The endpoint maps to src/lib/db/settings.ts, which reads directly from config/payloadRules.json.

Persisting Changes Programmatically

Configuration updates can be persisted by writing merged objects back to the source JSON files. The Settings UI (pages/settings/payload-rules.tsx) implements a similar pattern:

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 });

Accessing i18n Data in the Frontend

Frontend components import internationalization data directly from the configuration directory:

// 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 data is validated against i18n-schema.json before being served to ensure structural integrity.

Summary

• OmniRoute uses a multi-file configuration strategy with JSON files in config/ and environment variables in .env.
• Payload rules, i18n data, and quality baselines reside in dedicated JSON files under config/.
• The Settings skill exposes these files through REST endpoints at /api/settings/* and via database abstractions in src/lib/db/settings.ts.
• Runtime loading occurs through the loadJson pattern, while updates are persisted by writing merged objects back to disk.
• TypeScript compilation, bundle size limits, and documentation standards are controlled via root-level configuration files.

Frequently Asked Questions

Where are OmniRoute configuration files located?

OmniRoute stores its primary configuration files in the config/ directory at the repository root, including payloadRules.json, i18n.json, and the quality/ folder. Additional configuration files such as .env.example, tsconfig.json, and .size-limit.json reside in the project root alongside package.json.

How do I change payload size limits in OmniRoute?

Modify the maxBytes property in config/payloadRules.json either by editing the file directly or using the Settings API endpoint at /api/settings/payload-rules. Changes take effect immediately after the file is re-read by the validation middleware in src/middleware/payloadValidator.ts.

Can I modify OmniRoute settings without restarting the server?

Yes, many settings can be modified at runtime through the Settings skill endpoints. The server reads these JSON files dynamically via the loadJson utility, and the Settings UI (pages/settings/payload-rules.tsx) demonstrates how to persist changes back to disk without requiring a process restart.

What validates the structure of the i18n configuration?

The config/i18n-schema.json file provides JSON-Schema validation for the i18n.json configuration. This schema is enforced by src/lib/validation/i18nValidator.ts to ensure that all language entries contain the required fields and structure before being loaded into the application.

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