docs: add llm.txt for LLM and contributor onboarding - #84
Conversation
|
You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard. |
|
@codex review |
Summary of ChangesHello @diegosouzapw, I'm Gemini Code Assist1! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed! This pull request introduces a new Highlights
🧠 New Feature in Public Preview: You can now enable Memory to help Gemini Code Assist learn from your team's feedback. This makes future code reviews more consistent and personalized to your project's style. Click here to enable Memory in your admin console. Changelog
Activity
Using Gemini Code AssistThe full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips. Invoking Gemini You can request assistance from Gemini at any point by creating a comment using either
Customization To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a Limitations & Feedback Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here. You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension. Footnotes
|
|
To use Codex here, create a Codex account and connect to github. |
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
The addition of llm.txt is a valuable resource for onboarding both human contributors and LLMs. However, the document contains several technical inaccuracies regarding the tech stack versions, the database migration strategy, and the architectural implementation of the proxy pipeline. Correcting these will ensure that the documentation remains a reliable source of truth for the project's architecture and conventions.
| ## Tech Stack | ||
|
|
||
| - **Runtime:** Node.js >= 18 | ||
| - **Framework:** Next.js 16 (App Router) with TypeScript |
There was a problem hiding this comment.
Next.js 16 is not yet released (the current stable version is 15). This appears to be a typo and should be corrected to reflect the actual version used in the project.
- **Framework:** Next.js 15 (App Router) with TypeScript
|
|
||
| ## Tech Stack | ||
|
|
||
| - **Runtime:** Node.js >= 18 |
There was a problem hiding this comment.
There is an inconsistency regarding the required Node.js version. This file specifies >= 18, while the README.md (line 917) states Node.js 20+. These should be aligned to avoid confusion during environment setup.
- **Runtime:** Node.js >= 20
|
|
||
| 4. **Environment variables:** All configuration is in `.env` (from `.env.example`). Key vars: `PORT`, `NEXT_PUBLIC_BASE_URL`, `API_KEY`, `ADMIN_PASSWORD`. | ||
|
|
||
| 5. **Database migrations:** SQLite schema is managed inline in `src/lib/db/core.ts` and `src/lib/db/providers.ts`. No migration framework — schema changes are applied on startup. |
There was a problem hiding this comment.
The statement 'No migration framework' is inaccurate. The codebase implements a versioned migration system using a migrationRunner and tracks applied migrations in the _omniroute_migrations table (as seen in src/lib/db/core.ts).
5. **Database migrations:** SQLite schema is managed via a custom migration runner in `src/lib/db/migrationRunner.ts`. Schema changes are applied on startup and tracked in the `_omniroute_migrations` table.
|
|
||
| 6. **Tests use Node.js built-in test runner:** Run `npm test` or `node --test tests/unit/*.test.mjs`. Playwright is used for E2E tests. | ||
|
|
||
| 7. **The proxy pipeline is in `src/sse/`**, not in `src/app/api/v1/`. The API routes in `src/app/api/v1/` delegate to the SSE server running on a separate Express instance. |
There was a problem hiding this comment.
The description of the proxy pipeline delegating to a 'separate Express instance' is incorrect based on the provided code. The API routes in src/app/api/v1/ import and call the SSE handlers directly as functions within the Next.js process.
7. **The proxy pipeline is in `src/sse/`**, not in `src/app/api/v1/`. The API routes in `src/app/api/v1/` call the SSE handlers directly from the `open-sse` workspace within the Next.js process.
There was a problem hiding this comment.
Pull request overview
This PR adds a comprehensive llm.txt file to the project root, following the llmstxt.org standard to facilitate LLM and contributor onboarding. The file provides a structured overview of OmniRoute's architecture, tech stack, project structure, key architectural decisions, main flows, and important implementation notes.
Changes:
- Added
llm.txtwith project overview, tech stack (Next.js 16, React 19, TypeScript, SQLite), complete project structure, 7 key architectural decisions, 3 main flows (Proxy Request, OAuth, Model Listing), important notes for LLMs, and links to project resources
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| ├── open-sse/ # Standalone SSE server (npm workspace) | ||
| │ ├── config/ # Model registries (embedding, image, audio, rerank, moderation) | ||
| │ ├── handlers/ # Request handlers per API type | ||
| │ └── translators/ # Format translators (OpenAI ↔ Claude ↔ Gemini ↔ Responses) |
There was a problem hiding this comment.
The directory name should be translator/ (singular) instead of translators/ (plural). The actual directory in the codebase is open-sse/translator/.
| │ └── translators/ # Format translators (OpenAI ↔ Claude ↔ Gemini ↔ Responses) | |
| │ └── translator/ # Format translators (OpenAI ↔ Claude ↔ Gemini ↔ Responses) |
|
|
||
| 1. **OpenAI-compatible API surface:** All incoming requests follow the OpenAI API format (`/v1/chat/completions`, `/v1/models`, etc.). This makes OmniRoute a drop-in replacement for any tool that supports custom OpenAI endpoints. | ||
|
|
||
| 2. **Provider abstraction via format translators:** Each AI provider (Claude, Gemini, etc.) has a translator in `open-sse/translators/` that converts between the OpenAI format and the provider's native format. This happens transparently. |
There was a problem hiding this comment.
The path should reference open-sse/translator/ (singular) instead of open-sse/translators/ (plural). The actual directory in the codebase is open-sse/translator/.
|
|
||
| 3. **The `open-sse/` directory is a separate npm workspace** with its own config, handlers, and translators. It handles the actual SSE streaming and format translation. | ||
|
|
||
| 4. **Environment variables:** All configuration is in `.env` (from `.env.example`). Key vars: `PORT`, `NEXT_PUBLIC_BASE_URL`, `API_KEY`, `ADMIN_PASSWORD`. |
There was a problem hiding this comment.
The environment variable name is incorrect. According to .env.example, the variable is INITIAL_PASSWORD, not ADMIN_PASSWORD. Also, API_KEY is not a single environment variable in .env.example - instead there are provider-specific API keys like DEEPSEEK_API_KEY, GROQ_API_KEY, etc., and API_KEY_SECRET for encryption.
| 4. **Environment variables:** All configuration is in `.env` (from `.env.example`). Key vars: `PORT`, `NEXT_PUBLIC_BASE_URL`, `API_KEY`, `ADMIN_PASSWORD`. | |
| 4. **Environment variables:** All configuration is in `.env` (from `.env.example`). Key vars include: `PORT`, `NEXT_PUBLIC_BASE_URL`, `INITIAL_PASSWORD`, `API_KEY_SECRET`, and provider-specific keys like `DEEPSEEK_API_KEY`, `GROQ_API_KEY`, etc. |
|
|
||
| 4. **Environment variables:** All configuration is in `.env` (from `.env.example`). Key vars: `PORT`, `NEXT_PUBLIC_BASE_URL`, `API_KEY`, `ADMIN_PASSWORD`. | ||
|
|
||
| 5. **Database migrations:** SQLite schema is managed inline in `src/lib/db/core.ts` and `src/lib/db/providers.ts`. No migration framework — schema changes are applied on startup. |
There was a problem hiding this comment.
This statement is incorrect. The codebase does have a migration framework. There is a src/lib/db/migrationRunner.ts file that manages versioned SQL migrations from src/lib/db/migrations/ directory. The migration system reads numbered SQL files (e.g., 001_initial_schema.sql) and tracks applied migrations in the _omniroute_migrations table. The claim "No migration framework" contradicts the actual implementation.
| 5. **Database migrations:** SQLite schema is managed inline in `src/lib/db/core.ts` and `src/lib/db/providers.ts`. No migration framework — schema changes are applied on startup. | |
| 5. **Database migrations:** SQLite schema is managed via a migration framework in `src/lib/db/migrationRunner.ts`, which applies versioned SQL files from `src/lib/db/migrations/` and tracks applied migrations in the `_omniroute_migrations` table. |
|
|
||
| 6. **Tests use Node.js built-in test runner:** Run `npm test` or `node --test tests/unit/*.test.mjs`. Playwright is used for E2E tests. | ||
|
|
||
| 7. **The proxy pipeline is in `src/sse/`**, not in `src/app/api/v1/`. The API routes in `src/app/api/v1/` delegate to the SSE server running on a separate Express instance. |
There was a problem hiding this comment.
The claim about "SSE server running on a separate Express instance" is inaccurate. The SSE proxy pipeline in src/sse/ is integrated within the Next.js application and delegates directly from the API routes (e.g., src/app/api/v1/chat/completions/route.ts calls handleChat from src/sse/handlers/chat.ts). There is no separate Express server instance for SSE handling - it's all within the Next.js app.
| 7. **The proxy pipeline is in `src/sse/`**, not in `src/app/api/v1/`. The API routes in `src/app/api/v1/` delegate to the SSE server running on a separate Express instance. | |
| 7. **The proxy pipeline is in `src/sse/`**, not in `src/app/api/v1/`. The API routes in `src/app/api/v1/` call into the SSE handlers in `src/sse/` within the same Next.js application (no separate Express server). |
| - **Database:** SQLite via better-sqlite3 (local, zero-config) | ||
| - **State management:** Zustand (client), lowdb (server JSON persistence) | ||
| - **UI:** React 19, Tailwind CSS 4, Recharts for analytics | ||
| - **Auth:** OAuth 2.0 (PKCE) for providers, bcrypt for local user auth |
There was a problem hiding this comment.
The package used is "bcryptjs" not "bcrypt". While they are functionally similar, the actual dependency in package.json is "bcryptjs": "^3.0.3".
| - **Auth:** OAuth 2.0 (PKCE) for providers, bcrypt for local user auth | |
| - **Auth:** OAuth 2.0 (PKCE) for providers, bcryptjs for local user auth |
Summary
Adds a comprehensive
llm.txtfile to the project root, following the llms.txt standard.Content includes:
Why?
This file enables any LLM (or new contributor) to quickly understand the project's architecture, patterns, and conventions — reducing onboarding time and repetitive explanations.
Closes #83