feat: Add dashboard loading and error UIs, introduce standardized API response utilities, enhance call log redaction and configurable retention, and document architectural decisions.

Author: diegosouzapw

.github/workflows/ci.yml

@@ -108,3 +108,39 @@ jobs:
       - run: npx playwright install --with-deps chromium
       - run: npm run build
       - run: npm run test:e2e
+
+  test-integration:
+    name: Integration Tests
+    runs-on: ubuntu-latest
+    needs: build
+    env:
+      JWT_SECRET: ci-test-secret-with-sufficient-length-for-validation
+      API_KEY_SECRET: ci-test-api-key-secret-long
+      INITIAL_PASSWORD: ci-test-password-for-integration
+      DATA_DIR: /tmp/omniroute-ci
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-node@v6
+        with:
+          node-version: 22
+          cache: npm
+      - run: npm ci
+      - run: npm run test:integration
+        continue-on-error: true
+
+  test-security:
+    name: Security Tests
+    runs-on: ubuntu-latest
+    needs: build
+    env:
+      JWT_SECRET: ci-test-secret-with-sufficient-length-for-validation
+      API_KEY_SECRET: ci-test-api-key-secret-long
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-node@v6
+        with:
+          node-version: 22
+          cache: npm
+      - run: npm ci
+      - run: npm run test:security
+        continue-on-error: true

CONTRIBUTING.md

@@ -159,7 +159,7 @@ src/                        # TypeScript (.ts / .tsx)
 │   ├── cacheLayer.ts       # LRU cache
 │   ├── semanticCache.ts    # Semantic response cache
 │   ├── idempotencyLayer.ts # Request deduplication
-│   └── localDb.ts          # LowDB (JSON) storage
+│   └── localDb.ts          # Settings facade (LowDB for config, SQLite for domain data)
 ├── shared/
 │   ├── components/         # React components (.tsx)
 │   ├── middleware/          # Correlation IDs, etc.

docs/ARCHITECTURE.md

@@ -771,8 +771,8 @@ Environment variables actively used by code:
 
 ## Operational Verification Checklist
 
-- Build from source: `cd /root/dev/omniroute && npm run build`
-- Build Docker image: `cd /root/dev/omniroute && docker build -t omniroute .`
+- Build from source: `npm run build`
+- Build Docker image: `docker build -t omniroute .`
 - Start service and verify:
 - `GET /api/settings`
 - `GET /api/v1/models`

docs/adr/ADR-001-nextjs-foundation.md

@@ -0,0 +1,37 @@
+# ADR-001: Next.js as the Foundation for an AI Gateway
+
+## Status: Accepted
+
+## Context
+
+OmniRoute is an AI routing gateway that translates, forwards, and manages requests across 20+ LLM providers. We needed a framework that could serve both the API proxy layer and a management dashboard from a single codebase.
+
+**Alternatives considered:**
+
+- **Express.js only** — Simpler proxy, but requires separate frontend tooling
+- **Fastify** — Fast, but no built-in SSR/dashboard support
+- **Next.js** — Unified full-stack framework with API routes, SSR, and static pages
+
+## Decision
+
+We chose Next.js because:
+
+1. **Single deployment** — API routes (`/api/*`) and dashboard UI in one process
+2. **Middleware layer** — Native request interception for auth guards and request tracing
+3. **File-based routing** — Easy to map provider endpoints to handlers
+4. **Built-in TypeScript** — Type safety across the entire codebase
+
+## Consequences
+
+**Positive:**
+
+- One `npm run build` produces both API and UI
+- Middleware provides centralized auth and request tracing
+- Dashboard gets automatic code splitting and optimization
+
+**Negative:**
+
+- Next.js middleware has limitations (no heavy imports, edge runtime constraints)
+- Serverless deployment model doesn't align with persistent WebSocket/SSE connections
+- Build times are longer than Express-only setups
+- The SSE proxy layer (`open-sse/`) operates outside Next.js conventions

docs/adr/ADR-002-hub-spoke-translation.md

@@ -0,0 +1,37 @@
+# ADR-002: Hub-and-Spoke Translation with OpenAI as Intermediate Format
+
+## Status: Accepted
+
+## Context
+
+OmniRoute routes requests across 20+ providers, each with its own API format (OpenAI, Anthropic Messages, Google Gemini, AWS Bedrock, etc.). Direct provider-to-provider translation would require O(n²) translators.
+
+**Alternatives considered:**
+
+- **Direct translation** — Each pair needs a dedicated translator (n² complexity)
+- **Common intermediate format** — Translate to/from a canonical format (2n complexity)
+- **Protocol buffers** — Strong typing but heavy overhead for a proxy
+
+## Decision
+
+We use the **OpenAI Chat Completions format** as the canonical intermediate representation. All incoming requests are normalized to OpenAI format, processed, then translated to the target provider's format.
+
+```
+Client → [any format] → OpenAI canonical → [target format] → Provider
+Provider → [response] → OpenAI canonical → [original format] → Client
+```
+
+## Consequences
+
+**Positive:**
+
+- Only 2 translators per provider (inbound + outbound) instead of n² pairs
+- OpenAI format is the de facto standard — most clients already use it
+- Adding a new provider requires only implementing one translator pair
+- Streaming (SSE) works consistently through the canonical format
+
+**Negative:**
+
+- Some provider-specific features may be lost in translation
+- The double translation adds latency (typically < 5ms)
+- OpenAI format changes require updating the canonical representation

docs/adr/ADR-003-dual-storage-sqlite.md

@@ -0,0 +1,39 @@
+# ADR-003: Dual Storage — SQLite Primary with JSON Migration Path
+
+## Status: Accepted
+
+## Context
+
+OmniRoute originally used LowDB (JSON file) for all persistence. As the project grew, JSON-based storage became a bottleneck for concurrent access, querying, and data integrity.
+
+**Alternatives considered:**
+
+- **LowDB only** — Simple but no concurrent access, no ACID, no querying
+- **SQLite only** — Fast, ACID-compliant, but breaks existing deployments
+- **PostgreSQL** — Production-grade but requires external dependency
+- **Dual storage with migration** — SQLite primary + automatic JSON migration
+
+## Decision
+
+We migrated to **SQLite as the primary store** with an automatic one-time migration from `db.json`:
+
+1. On startup, if `db.json` exists and SQLite is empty, auto-migrate all data
+2. All new reads/writes go through SQLite
+3. The `db.json` file is preserved but no longer written to
+
+Settings remain in a hybrid model where LowDB handles simple key-value configuration for backward compatibility.
+
+## Consequences
+
+**Positive:**
+
+- ACID transactions for provider connections, API keys, and usage data
+- Proper SQL queries for analytics and log filtering
+- Concurrent read/write safety via WAL mode
+- Zero-downtime migration from JSON — users upgrade transparently
+
+**Negative:**
+
+- Two storage engines to maintain (SQLite + LowDB for settings)
+- Migration code must handle edge cases and partial data
+- SQLite binary dependency needed in deployment environments

eslint.config.mjs

@@ -3,26 +3,33 @@ import nextVitals from "eslint-config-next/core-web-vitals";
 /** @type {import("eslint").Linter.Config[]} */
 const eslintConfig = [
   ...nextVitals,
-  // FASE-02: Security rules
+  // FASE-02: Security rules (strict everywhere)
   {
     rules: {
       "no-eval": "error",
       "no-implied-eval": "error",
       "no-new-func": "error",
     },
   },
-  // Global ignores
+  // Relaxed rules for open-sse and tests (incremental adoption)
+  {
+    files: ["open-sse/**/*.ts", "tests/**/*.mjs", "tests/**/*.ts"],
+    rules: {
+      "@typescript-eslint/no-explicit-any": "warn",
+      "@next/next/no-assign-module-variable": "off",
+      "react-hooks/rules-of-hooks": "off",
+    },
+  },
+  // Global ignores (open-sse and tests REMOVED — now linted)
   {
     ignores: [
       ".next/**",
       "out/**",
       "build/**",
       "next-env.d.ts",
-      "tests/**",
       "scripts/**",
       "bin/**",
       "node_modules/**",
-      "open-sse/**",
     ],
   },
 ];

src/app/(dashboard)/dashboard/analytics/loading.tsx

@@ -0,0 +1,15 @@
+"use client";
+
+export default function AnalyticsLoading() {
+  return (
+    <div className="space-y-6 animate-pulse p-6">
+      <div className="h-8 bg-gray-200 dark:bg-gray-700 rounded w-40" />
+      <div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-4 gap-4">
+        {[1, 2, 3, 4].map((i) => (
+          <div key={i} className="h-24 bg-gray-200 dark:bg-gray-700 rounded-lg" />
+        ))}
+      </div>
+      <div className="h-64 bg-gray-200 dark:bg-gray-700 rounded-lg" />
+    </div>
+  );
+}

src/app/(dashboard)/dashboard/providers/error.tsx

@@ -0,0 +1,28 @@
+"use client";
+
+export default function ProvidersError({
+  error,
+  reset,
+}: {
+  error: Error & { digest?: string };
+  reset: () => void;
+}) {
+  return (
+    <div className="flex flex-col items-center justify-center min-h-[400px] p-6">
+      <div className="text-center space-y-4">
+        <h2 className="text-xl font-semibold text-red-600 dark:text-red-400">
+          Failed to load providers
+        </h2>
+        <p className="text-gray-600 dark:text-gray-400 max-w-md">
+          {error.message || "An unexpected error occurred while loading provider data."}
+        </p>
+        <button
+          onClick={reset}
+          className="px-4 py-2 bg-blue-600 text-white rounded-lg hover:bg-blue-700 transition-colors"
+        >
+          Try Again
+        </button>
+      </div>
+    </div>
+  );
+}

src/app/(dashboard)/dashboard/providers/loading.tsx

@@ -0,0 +1,14 @@
+"use client";
+
+export default function ProvidersLoading() {
+  return (
+    <div className="space-y-6 animate-pulse p-6">
+      <div className="h-8 bg-gray-200 dark:bg-gray-700 rounded w-48" />
+      <div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-4">
+        {[1, 2, 3].map((i) => (
+          <div key={i} className="h-40 bg-gray-200 dark:bg-gray-700 rounded-lg" />
+        ))}
+      </div>
+    </div>
+  );
+}