localmodelroutex/CONTRIBUTING.md

Contributing to LMR

Thanks for your interest. This page tells you how to set up a development environment, how to run the checks, and what a good pull request looks like.

Development setup

You need Go 1.27 or newer, Node 22 or newer, Docker, and make.

cd backend
cp .env.example .env
echo GATEWAY_SECURITY_ENCRYPTION_KEY=$(openssl rand -hex 32) >> .env
make dev

make dev starts a Postgres container, applies the migrations, runs the Go server on port 8080, and runs the Vite dev server on port 5173 with a proxy to the Go server. The dashboard needs an OIDC provider to sign in. Any provider works; the .env.example file shows the Authentik shape.

Run make help to list every target.

Checks

Run these before you open a pull request. The CI pipeline runs the same set.

cd backend
go vet ./...
make test                 # unit tests, no database needed
make lint                 # golangci-lint, config in backend/.golangci.yml
cd dashboard && npx tsc --noEmit && npm run build

Database tests

The internal/store and internal/catalog packages have integration tests against a real Postgres. They skip unless GATEWAY_TEST_DB_URL is set.

cd backend
make dev-db                                   # or any Postgres 16
export GATEWAY_TEST_DB_URL='postgres://gateway:gateway@localhost:5432/gateway?sslmode=disable'
GATEWAY_DB_URL=$GATEWAY_TEST_DB_URL go run ./cmd/migrate up
go test ./internal/store/ ./internal/catalog/

The tests delete and recreate rows, so point them at a throwaway database.

Project layout

See the "Repo layout" section of the README and the architecture notes. The short version:

• backend/internal/api holds the HTTP handlers.
• backend/internal/providers holds the provider abstraction. Each upstream type lives in its own package and registers itself in init().
• backend/internal/catalog holds the runtime model library.
• backend/internal/store holds hand-written SQL on pgx.
• backend/migrations holds the schema. Add a new numbered pair of up and down files for every schema change. Never edit an applied one.
• backend/dashboard holds the React UI. The Go binary embeds the build.

Adding a provider

1. Create backend/internal/providers/<type>/ with a New factory and an init() that calls providers.Register.
2. Implement the capability interfaces the upstream supports: ChatCompleter, Embedder, ImageGenerator, ModelLister.
3. Import the package in backend/internal/providers/all.
4. If the upstream is OpenAI-compatible, embed openaicompat.Transport and only add what differs. See the openrouter package for an example.
5. Add the type to the providers table in the README and to the dashboard's provider form.

Pull requests

• Keep one change per pull request.
• Add or update tests for the code you touch. Handler tests live in backend/internal/api and use fake dependencies, so they do not need a database.
• Run gofmt. The lint step fails on unformatted code.
• Write commit messages as <area>: <short summary> in the imperative mood, for example catalog: store output modalities as capabilities. Explain the reason in the body when it is not obvious from the diff.
• Do not include generated files. The internal/web/dist folder and bin/ are ignored on purpose.

Reporting bugs

Open an issue with the version or commit, the steps to reproduce, the expected result, and the actual result. For a request that failed at the proxy, include the row from the Logs page with the key prefix removed.

Security problems go to the address in SECURITY.md, not to the issue tracker.

License

By contributing you agree that your contributions are licensed under the GNU Affero General Public License, version 3, the same as the project.