> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nt3.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Contributing to Entri

> Set up the development environment, follow the conventions, and ship your first PR.

Entri is open source and contributions are very welcome — bug fixes, new features, docs improvements, file-format support, you name it.

## Prerequisites

* **Node 22** (`.nvmrc` is in the repo)
* **pnpm 10** — `corepack enable` is enough; the version is pinned via `packageManager` in `package.json`
* **Docker** with the Compose plugin (Docker Desktop ships with both)

## Get the code running

```bash theme={null}
git clone https://github.com/nt3-io/platform.git entri
cd entri

# 1. Boot the data services (MongoDB, Redis, TypeSense)
pnpm compose:up

# 2. Configure your environment
cp .env.example .env
# Edit .env to fill in any optional credentials you want to test

# 3. Install dependencies
pnpm install

# 4. Run database migrations
pnpm migrate

# 5. Run the API and the web app in two terminals
pnpm dev:api      # http://localhost:3333
pnpm dev          # http://localhost:4200
```

That's it — open [http://localhost:4200](http://localhost:4200) and sign up for a local account. See the [self-hosting guide](/developers/self-hosting) for more on the local stack.

## Repository layout

```
apps/
  api/        NestJS backend (REST + GraphQL)
  app/        React + Vite frontend
  cli/        nt3 CLI (NestJS Commander)
  docs/       Mintlify documentation site (this site)
  infra/      Pulumi IaC for the reference Cloud Run deployment
```

Code shared across apps lives in each app's `src/shared/`. There is no top-level `packages/` directory — Nx handles cross-project references.

## Development conventions

### Linting and formatting

Entri uses **Biome** for both linting and formatting. Run before pushing:

```bash theme={null}
pnpm lint           # check
pnpm lint:fix       # auto-fix
```

A pre-commit hook (Husky + lint-staged) runs Biome on staged files automatically.

<Note>
  Biome's `useImportType` rule rewrites `import { Foo }` to `import type { Foo }`, which breaks NestJS dependency injection (Nest reads runtime class identities via `emitDecoratorMetadata`). The rule is disabled for `apps/api/**` and `apps/cli/**` in `biome.json`, so write normal class imports there — no per-import `biome-ignore` comments needed. The rule remains enabled in `apps/app/**`.
</Note>

### Tests

```bash theme={null}
pnpm test:api       # API unit + integration tests
pnpm test:app       # Frontend tests
```

The API integration tests use `mongodb-memory-server` for the database and a `MockCacheService` (`apps/api/test/mocks/cache.service.mock.ts`) for the cache — no real Mongo or Redis needed.

### Internationalization

All user-facing strings in the web app must be wrapped with [Lingui](https://lingui.dev) macros:

```tsx theme={null}
import { Trans, useLingui } from '@lingui/react/macro'

// JSX text
<Trans>Save changes</Trans>

// String props
const { t } = useLingui()
<input placeholder={t`Enter a key…`} />
```

After adding or changing strings, run `pnpm i18n:extract` to update the PO catalogs in `apps/app/locales/{en,nl,fr}/messages.po`.

### GraphQL

The API generates the GraphQL schema from decorators (code-first). After changing resolvers or schema types, regenerate the frontend types:

```bash theme={null}
pnpm dev:api                       # in one terminal
pnpm generate:graphql-types        # in another
```

### Docs

Documentation lives in `apps/docs/` (Mintlify). Preview locally:

```bash theme={null}
cd apps/docs
pnpx mintlify dev
```

When you add new pages, register them in `apps/docs/docs.json` under the appropriate tab and group, otherwise they won't appear in the sidebar.

If you change a REST endpoint, re-export the OpenAPI spec:

```bash theme={null}
curl http://localhost:3333/api/docs-json > apps/docs/api-reference/openapi.json
```

## Pull request process

1. **Fork** the repo and create a topic branch from `main`. Use a descriptive branch name like `feat/typesense-search` or `fix/import-empty-namespace`.
2. **Make focused commits.** Conventional Commit prefixes (`feat:`, `fix:`, `chore:`, `docs:`, `refactor:`) are the project convention.
3. **Run `pnpm lint` and the relevant tests** before pushing.
4. **Open a PR** with a clear description of the change, the motivation, and a test plan. Link any related issues.
5. **Be patient with review** — maintainers will respond, and the project also runs an automated AI reviewer that may post inline suggestions.
6. **Update docs** if your change affects user-visible behavior, configuration, or the API surface. Use the `apps/docs/` table in `CLAUDE.md` as a guide.

## Reporting bugs and requesting features

Open a [GitHub issue](https://github.com/nt3-io/platform/issues) and include:

* A clear description of what you expected vs. what happened
* Steps to reproduce, ideally a minimal example
* Your Entri version (commit SHA or release tag), runtime (self-hosted Docker / Cloud Run / etc.), and Node/pnpm versions
* Relevant log output

For security issues, **do not open a public issue**. Email the maintainers privately — see `SECURITY.md` in the repo for the current contact.

## Code of conduct

Be respectful. Be patient with newcomers. Assume good intent. The project follows the [Contributor Covenant](https://www.contributor-covenant.org/version/2/1/code_of_conduct/).

## Going further

* [Self-hosting](/developers/self-hosting) — production deployment details
* [Quick Start](/developers/quickstart) — using the CLI as an end user
* [GitHub repository](https://github.com/nt3-io/platform)