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

> Explore the OmniRoute configuration file guide. Learn to manage JSON settings, environment variables, and customize your OmniRoute deployment for optimal performance.

- Repository: [Diego Rodrigues de Sa e Souza/OmniRoute](https://github.com/diegosouzapw/OmniRoute)
- Tags: how-to-guide
- Published: 2026-07-16

---

**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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/middleware/payloadValidator.ts) to enforce security policies at the edge.

### Internationalization Settings (config/i18n.json)

Global localization data resides in [`config/i18n.json`](https://github.com/diegosouzapw/OmniRoute/blob/main/config/i18n.json), which maps language codes to translation bundles used by both the UI and CLI. The [`config/i18n-schema.json`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/tsconfig.json) for the main application build
- [`tsconfig.typecheck-core.json`](https://github.com/diegosouzapw/OmniRoute/blob/main/tsconfig.typecheck-core.json) for strict type-checking runs
- [`tsconfig.typecheck-noimplicit-core.json`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/.size-limit.json) – Enforces bundle size caps via the `size-limit` tool in CI
- [`.markdownlint.json`](https://github.com/diegosouzapw/OmniRoute/blob/main/.markdownlint.json) – Defines linting rules for documentation
- [`package.json`](https://github.com/diegosouzapw/OmniRoute/blob/main/package.json) and [`package-lock.json`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/config/load.ts), the implementation reads files synchronously and parses them into typed objects:

```typescript
// 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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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:

```bash
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`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/db/settings.ts), which reads directly from [`config/payloadRules.json`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/pages/settings/payload-rules.tsx)) implements a similar pattern:

```typescript
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:

```tsx
// 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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/payloadRules.json), [`i18n.json`](https://github.com/diegosouzapw/OmniRoute/blob/main/i18n.json), and the `quality/` folder. Additional configuration files such as `.env.example`, [`tsconfig.json`](https://github.com/diegosouzapw/OmniRoute/blob/main/tsconfig.json), and [`.size-limit.json`](https://github.com/diegosouzapw/OmniRoute/blob/main/.size-limit.json) reside in the project root alongside [`package.json`](https://github.com/diegosouzapw/OmniRoute/blob/main/package.json).

### How do I change payload size limits in OmniRoute?

Modify the `maxBytes` property in [`config/payloadRules.json`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/config/i18n-schema.json) file provides JSON-Schema validation for the [`i18n.json`](https://github.com/diegosouzapw/OmniRoute/blob/main/i18n.json) configuration. This schema is enforced by [`src/lib/validation/i18nValidator.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/validation/i18nValidator.ts) to ensure that all language entries contain the required fields and structure before being loaded into the application.