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

> Discover OmniRoute configuration files. Learn how JSON files in config/ and the project root manage runtime settings, feature toggles, and more for your project structure.

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

---

**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`](https://github.com/diegosouzapw/OmniRoute/blob/main/config/payloadRules.json))

The [`payloadRules.json`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/middleware/payloadValidator.ts) to sanitize incoming traffic before it reaches application logic.

### Internationalization Data ([`config/i18n.json`](https://github.com/diegosouzapw/OmniRoute/blob/main/config/i18n.json) and [`config/i18n-schema.json`](https://github.com/diegosouzapw/OmniRoute/blob/main/config/i18n-schema.json))

The [`i18n.json`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/i18n-schema.json) file provides a JSON-Schema definition that validates the structure of [`i18n.json`](https://github.com/diegosouzapw/OmniRoute/blob/main/i18n.json). According to the OmniRoute source code, the validation step in [`src/lib/validation/i18nValidator.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/server/init.ts) loads these variables to configure the runtime environment.

### TypeScript Compiler Settings ([`tsconfig.json`](https://github.com/diegosouzapw/OmniRoute/blob/main/tsconfig.json) variants)

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

- **[`tsconfig.json`](https://github.com/diegosouzapw/OmniRoute/blob/main/tsconfig.json)** – Primary compiler options for the main application build
- **[`tsconfig.typecheck-core.json`](https://github.com/diegosouzapw/OmniRoute/blob/main/tsconfig.typecheck-core.json)** – Strict type-checking configuration for core modules
- **[`tsconfig.typecheck-noimplicit-core.json`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/package.json)** and **[`package-lock.json`](https://github.com/diegosouzapw/OmniRoute/blob/main/package-lock.json)** – Define project dependencies, npm scripts, and metadata for installation and CI builds
- **[`.size-limit.json`](https://github.com/diegosouzapw/OmniRoute/blob/main/.size-limit.json)** – Configures the `size-limit` tool to enforce bundle size caps during CI runs via `npm run size-limit`
- **[`.markdownlint.json`](https://github.com/diegosouzapw/OmniRoute/blob/main/.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`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/config/load.ts). This pattern uses Node.js filesystem APIs to read and parse JSON files synchronously during initialization.

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

// 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`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/db/settings.ts) for reading the underlying JSON files.

```bash

# 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`](https://github.com/diegosouzapw/OmniRoute/blob/main/pages/settings/payload-rules.tsx)) provides a frontend interface, administrators can also update configurations programmatically by merging changes into the JSON files directly.

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

```

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`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/app/components/LocaleSwitcher.tsx) imports [`i18n.json`](https://github.com/diegosouzapw/OmniRoute/blob/main/i18n.json) to build the language selection interface.

```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 [`i18n.json`](https://github.com/diegosouzapw/OmniRoute/blob/main/i18n.json) file is validated against [`i18n-schema.json`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/config/payloadRules.json)** controls request validation rules consumed by [`src/middleware/payloadValidator.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/middleware/payloadValidator.ts).
- **[`config/i18n.json`](https://github.com/diegosouzapw/OmniRoute/blob/main/config/i18n.json)** and **[`config/i18n-schema.json`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/payloadRules.json), [`i18n.json`](https://github.com/diegosouzapw/OmniRoute/blob/main/i18n.json), and [`i18n-schema.json`](https://github.com/diegosouzapw/OmniRoute/blob/main/i18n-schema.json) located there. Additional configuration files—including `.env.example`, [`tsconfig.json`](https://github.com/diegosouzapw/OmniRoute/blob/main/tsconfig.json) variants, and [`.size-limit.json`](https://github.com/diegosouzapw/OmniRoute/blob/main/.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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/config/load.ts) to read these rules at startup, and the Settings UI ([`pages/settings/payload-rules.tsx`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/i18n-schema.json) in OmniRoute?

The [`i18n-schema.json`](https://github.com/diegosouzapw/OmniRoute/blob/main/i18n-schema.json) file provides a JSON-Schema definition that validates the structure of [`i18n.json`](https://github.com/diegosouzapw/OmniRoute/blob/main/i18n.json). According to the OmniRoute source code, the validation step in [`src/lib/validation/i18nValidator.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/db/settings.ts). While the server loads initial configurations at startup via `import` or `require` statements in [`src/server/init.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/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.