### Start Services with Homebrew

Source: https://github.com/mtes-mct/trackdechets/blob/dev/CONTRIBUTING.md

Starts the previously installed services using Homebrew services. Verify their status with 'brew services list'.

```bash
brew services start redis
brew services start nginx
brew services start mongodb-community
brew services start elasticsearch@6
```

--------------------------------

### Install Application Dependencies

Source: https://github.com/mtes-mct/trackdechets/blob/dev/CONTRIBUTING.md

Install all project dependencies using npm. This command should be run after cloning the repository and setting up the environment.

```bash
npm install
```

--------------------------------

### Start Storybook

Source: https://github.com/mtes-mct/trackdechets/blob/dev/CONTRIBUTING.md

Optional command to start the Storybook development server for the frontend components.

```bash
npx nx run front:storybook
```

--------------------------------

### Install Core Services with Homebrew

Source: https://github.com/mtes-mct/trackdechets/blob/dev/CONTRIBUTING.md

Installs essential services like PostgreSQL, Redis, Nginx, MongoDB, and Elasticsearch@6 using Homebrew. Ensure Homebrew is installed and updated before running these commands.

```bash
brew install postgresql
brew install redis
brew install nginx
brew tap mongodb/brew
brew update
brew install mongodb-community@6.0
brew install elasticsearch@6
```

--------------------------------

### Start Database Containers

Source: https://github.com/mtes-mct/trackdechets/blob/dev/CONTRIBUTING.md

Initialize and start the necessary database containers using Docker Compose. Ensure your environment is set up for local development.

```bash
docker compose docker-compose.yml up -d
```

--------------------------------

### Install NVM and Node.js

Source: https://github.com/mtes-mct/trackdechets/blob/dev/CONTRIBUTING.md

Install Node Version Manager (nvm) and the required Node.js version (v20) for the backend. After installation, set the default version and install project dependencies.

```bash
brew install nvm
nvm install 20 // version pour le back
echo v20 > .nvmrc
nvm use && npm install && npm nx run back:codegen
```

--------------------------------

### Run Integration Tests

Source: https://github.com/mtes-mct/trackdechets/blob/dev/CONTRIBUTING.md

Commands to run integration tests, which require a test database setup. First, start background queues, then run the integration tests.

```bash
npm run bg:integration # Démarrage des queues en background, nécessaires aux tests
npx nx run back:test:integration # Lancement des tests d'intégration
```

```bash
npx nx run back:test:integration --testFile workflow.integration.ts
```

--------------------------------

### Start Development Servers

Source: https://github.com/mtes-mct/trackdechets/blob/dev/CONTRIBUTING.md

Commands to start the backend and frontend development servers. Use `run-many` for concurrent startup or individual commands for separate consoles.

```bash
npx nx run-many -t serve
```

```bash
npx nx run api:serve # API
npx nx run front:serve # Frontend
npx nx run-many --parallel=4 -t serve --projects=tag:backend:background
```

--------------------------------

### Start Services for Integration/E2E Tests

Source: https://github.com/mtes-mct/trackdechets/blob/dev/CONTRIBUTING.md

Start the necessary services (DB, ES, etc.) and the Trackdechets backend/frontend for integration and end-to-end tests using the 'integration' configuration.

```bash
docker compose up -d
npx nx run-many -t serve --configuration=integration --projects=api,front,tag:backend:background --parallel=6
```

--------------------------------

### Start PostgreSQL Container for Manual Restore

Source: https://github.com/mtes-mct/trackdechets/blob/dev/CONTRIBUTING.md

Use this command to start the PostgreSQL container in development mode, preparing it for a manual database backup restoration.

```bash
docker compose -f docker-compose.dev.yml up --build postgres
```

--------------------------------

### GitHub Actions: Deploy to Production Workflow

Source: https://github.com/mtes-mct/trackdechets/blob/dev/kubernetes/AUTOMATION.md

This workflow automates the build and deployment of applications to production. It checks out code, sets up Node.js, installs dependencies, builds applications, logs into the GitHub Container Registry, builds and pushes Docker images, installs kubectl and kustomize, configures kubectl, updates kustomization files with new image tags, deploys to production using kubectl, and verifies the deployment.

```yaml
name: Deploy to Production

on:
  push:
    branches:
      - main
    paths:
      - "apps/**"
      - "libs/**"
      - "kubernetes/**"

env:
  REGISTRY: ghcr.io/trackdechets

jobs:
  build-and-deploy:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      packages: write

    steps:
      - name: Checkout
        uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: "20"
          cache: "npm"

      - name: Install dependencies
        run: npm ci

      - name: Build applications
        run: npx nx run-many --target=build --all --parallel=3

      - name: Login to GitHub Container Registry
        uses: docker/login-action@v3
        with:
          registry: ghcr.io
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}

      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v3

      - name: Build and push Docker images
        run: |
          # Get git SHA for image tagging
          SHORT_SHA=$(git rev-parse --short HEAD)

          # Build and push all images
          for app in ui api notifier cron queues-runner queues-indexation queues-bulk-indexation queues-bulk-indexation-master queues-webhooks queues-gerico; do
            echo "Building $app..."
            docker buildx build \
              --platform linux/amd64 \
              --file apps/$app/Dockerfile \
              --tag $REGISTRY/$app:$SHORT_SHA \
              --tag $REGISTRY/$app:latest \
              --push \
              .
          done

      - name: Install kubectl
        uses: azure/setup-kubectl@v3
        with:
          version: "v1.28.0"

      - name: Install kustomize
        run: |
          curl -s "https://raw.githubusercontent.com/kubernetes-sigs/kustomize/master/hack/install_kustomize.sh" | bash
          sudo mv kustomize /usr/local/bin/

      - name: Configure kubectl
        run: |
          echo "${{ secrets.KUBECONFIG }}" | base64 -d > $HOME/.kube/config

      - name: Update kustomization with new image tags
        run: |
          SHORT_SHA=$(git rev-parse --short HEAD)
          cd kubernetes/overlays/production

          # Update all image tags to new SHA
          kustomize edit set image \
            $REGISTRY/ui:$SHORT_SHA \
            $REGISTRY/api:$SHORT_SHA \
            $REGISTRY/notifier:$SHORT_SHA \
            $REGISTRY/cron:$SHORT_SHA \
            $REGISTRY/queues-runner:$SHORT_SHA \
            $REGISTRY/queues-indexation:$SHORT_SHA \
            $REGISTRY/queues-bulk-indexation:$SHORT_SHA \
            $REGISTRY/queues-bulk-indexation-master:$SHORT_SHA \
            $REGISTRY/queues-webhooks:$SHORT_SHA \
            $REGISTRY/queues-gerico:$SHORT_SHA

      - name: Deploy to production
        run: |
          kubectl apply -k kubernetes/overlays/production

      - name: Wait for rollout
        run: |
          kubectl rollout status deployment/api -n trackdechets --timeout=5m
          kubectl rollout status deployment/ui -n trackdechets --timeout=5m
          kubectl rollout status deployment/notifier -n trackdechets --timeout=5m

      - name: Verify deployment
        run: |
          # Check all pods are running
          kubectl get pods -n trackdechets

          # Check API health
          kubectl exec -n trackdechets deployment/api -- curl -f http://localhost:4000/.well-known/apollo/server-health

```

--------------------------------

### GraphQL Query Example

Source: https://github.com/mtes-mct/trackdechets/blob/dev/apps/doc/docs/concepts/graphql.md

Example of a GraphQL query to fetch user profile information, including nested company data.

```APIDOC
## GraphQL Query: Fetch User Profile

### Description
This is an example of a GraphQL query to retrieve the current user's name, email, and details about their associated companies.

### Query
```graphql
query {
  me {
    name
    email
    companies {
      name
      siret
    }
  }
}
```
```

--------------------------------

### Gabin's Combination 1,1,1 Example

Source: https://github.com/mtes-mct/trackdechets/wiki/Sondage-conventions-de-nommage

Example of Gabin's preferred naming convention combination for entities, queries, and mutations.

```plaintext
dasri, dasris, createDasri
```

```plaintext
bsdd, bsdds, createBsdd
```

```plaintext
bsds
```

--------------------------------

### Install Playwright Dependencies

Source: https://github.com/mtes-mct/trackdechets/blob/dev/CONTRIBUTING.md

Install project dependencies and Playwright's Chromium browser with necessary system dependencies for end-to-end testing.

```bash
npm i
npx playwright install chromium --with-deps
```

--------------------------------

### Run Application Services

Source: https://github.com/mtes-mct/trackdechets/blob/dev/CONTRIBUTING.md

Start the main API, frontend, and background services. It's recommended to run these in separate terminals for better visibility.

```bash
> npx nx run api:serve # API
> npx nx run front:serve # Frontend
> npx nx run-many --parallel=4 -t serve --projects=tag:backend:background # Services annexes: notifier & queues
```

--------------------------------

### Benoit's Combination 6,1,1 Example

Source: https://github.com/mtes-mct/trackdechets/wiki/Sondage-conventions-de-nommage

Example of Benoit's preferred naming convention combination (suffix 'bsd', plural query, verb-first mutation).

```plaintext
dasriBsd, dasriBsds, createDasriBsd
```

```plaintext
bsd, bsds, createBsd
```

```plaintext
searchBsds
```

--------------------------------

### Clone Repository and Checkout Dev Branch

Source: https://github.com/mtes-mct/trackdechets/blob/dev/CONTRIBUTING.md

Clone the project repository and switch to the development branch to start contributing.

```bash
git clone git@github.com:MTES-MCT/trackdechets.git
cd trackdechets
git checkout --track origin/dev
```

--------------------------------

### Benoit's Combination 7,1,1 Example

Source: https://github.com/mtes-mct/trackdechets/wiki/Sondage-conventions-de-nommage

Example of Benoit's preferred naming convention combination (suffix 'bordereau', plural query, verb-first mutation).

```plaintext
dasriBordereau, dasriBordereaux, createDasriBordereau
```

```plaintext
bordereau, bordereaux, createBordereau
```

```plaintext
searchBordereaux
```

--------------------------------

### Orion's Combination 7,1,4 Example

Source: https://github.com/mtes-mct/trackdechets/wiki/Sondage-conventions-de-nommage

Example of Orion's preferred naming convention combination (suffix 'bordereau', plural query, verb-first snake_case mutation).

```plaintext
dasriBordereau dasriBordereaux create_dasriBordereau
```

--------------------------------

### Run Partial Database Backup Script

Source: https://github.com/mtes-mct/trackdechets/blob/dev/CONTRIBUTING.md

Execute the script to create a partial database dump. This script identifies and backs up related objects starting from a specified BSD.

```bash
npx nx run partial-backup:run
```

--------------------------------

### Query Naming Conventions

Source: https://github.com/mtes-mct/trackdechets/wiki/Sondage-conventions-de-nommage

Examples of naming conventions for queries, including pluralization and verb-based naming.

```plaintext
<name>, <name>s
```

```plaintext
<name>_findUnique, <name>_findMany
```

```plaintext
{ bsd|bordereau|form { <name> } }, { bsds|bordereaux|forms { <name> } }
```

--------------------------------

### Launch Playwright Recorder

Source: https://github.com/mtes-mct/trackdechets/blob/dev/CONTRIBUTING.md

Start the Playwright recorder to generate end-to-end test code by interacting with the application in a browser. Specify the base URL and viewport size.

```bash
npx playwright codegen trackdechets.local --viewport-size=1920,1080
```

--------------------------------

### GraphQL Syntax Error Example

Source: https://github.com/mtes-mct/trackdechets/blob/dev/apps/doc/docs/reference/errors.md

This example demonstrates a syntax error in a GraphQL query due to a missing closing brace.

```graphql
query {
  me  // accolade manquante
    email
  }
}
```

--------------------------------

### GraphQL Mutation Example

Source: https://github.com/mtes-mct/trackdechets/blob/dev/apps/doc/docs/concepts/graphql.md

Example of a GraphQL mutation to mark a waste manifest as received, including input data for the reception.

```APIDOC
## GraphQL Mutation: Mark as Received

### Description
This mutation is used to mark a hazardous waste manifest as received. It requires the manifest ID and details about the reception.

### Mutation
```graphql
mutation {
  markAsReceived(
    id: "sju8d6g0JU61G76F",
    receivedInfo: {
      receivedBy: "Bill",
      receivedAt: "2019-01-17",
      signedAt: "2019-01-17",
      wasteAcceptationStatus: "ACCEPTED",
      quantityReceived: 0
    }){
    id
    status
  }
}
```
```

--------------------------------

### Launch Scaleway Instance

Source: https://github.com/mtes-mct/trackdechets/blob/dev/scripts/scaleway-test/README.md

Execute the main script to launch a pre-configured Scaleway instance for running tests.

```bash
./main_restore.sh
```

--------------------------------

### GraphQL Validation Error Example

Source: https://github.com/mtes-mct/trackdechets/blob/dev/apps/doc/docs/reference/errors.md

This example shows a GraphQL validation error where the query is syntactically correct but references a non-existent field.

```graphql
{
  query {
    me {
      hair_color // le champ hair_color n'existe pas sur le type User
    }
  }
}
```

--------------------------------

### Run Prisma or Nx Migrations

Source: https://github.com/mtes-mct/trackdechets/blob/dev/scripts/scaleway-test/README.md

After the tester script completes, run your desired migrations using Prisma or Nx.

```bash
npx prisma migratre dev
```

```bash
npx nx run @td/scripts:migrate
```

--------------------------------

### GraphQL External Service Error Example

Source: https://github.com/mtes-mct/trackdechets/blob/dev/apps/doc/docs/reference/errors.md

This example illustrates a valid GraphQL query that triggers an error due to an external service issue.

```graphql
query {
  companyInfos(siret: "123") {
    siret
  }
}
```

--------------------------------

### Map Host URLs for Local Development

Source: https://github.com/mtes-mct/trackdechets/blob/dev/CONTRIBUTING.md

Configure your system's host file to map local development URLs to your machine's loopback address. This is crucial for the application to resolve internal services correctly.

```bash
127.0.0.1 api.trackdechets.local
127.0.0.1 trackdechets.local
127.0.0.1 developers.trackdechets.local
127.0.0.1 es.trackdechets.local
127.0.0.1 notifier.trackdechets.local
127.0.0.1 storybook.trackdechets.local
127.0.0.1 s3.trackdechets.local # en cas d'utilisation d'un système de container S3 local
```

```bash
::1 api.trackdechets.local
::1 trackdechets.local
::1 developers.trackdechets.local
::1 es.trackdechets.local
::1 notifier.trackdechets.local
::1 storybook.trackdechets.local
::1 s3.trackdechets.local
```

--------------------------------

### GraphQL Query with Variables Example

Source: https://github.com/mtes-mct/trackdechets/blob/dev/apps/doc/docs/concepts/graphql.md

Example of a GraphQL query that accepts variables, specifically fetching company information using a SIRET number.

```APIDOC
## GraphQL Query: Fetch Company Info by SIRET

### Description
This example shows how to query for company information by providing a SIRET number as a variable.

### Query
```graphql
query {
  companyInfos(siret: "13001045700013") {
    name,
    address
  }
}
```
```

--------------------------------

### Apply New Namespace Structure (Kustomization)

Source: https://github.com/mtes-mct/trackdechets/blob/dev/kubernetes/external-secrets/NAMESPACE_MIGRATION.md

Apply the new frontend and backend resource configurations using Kustomize. This is a consolidated approach for applying all resources within the new namespace structure.

```bash
kubectl apply -k kubernetes/base/frontend-kustomization.yaml

kubectl apply -k kubernetes/base/backend-kustomization.yaml
```

--------------------------------

### Initialize Database and Seed Data

Source: https://github.com/mtes-mct/trackdechets/blob/dev/CONTRIBUTING.md

Push the database schema to Prisma and seed the database with test data. This requires creating a `seed.dev.ts` file in the `back/prisma` directory.

```bash
npx prisma db push
npx prisma db seed
```

--------------------------------

### Create Establishment Sheet

Source: https://github.com/mtes-mct/trackdechets/blob/dev/back/src/companydigest/developper_doc.md

Initiates the asynchronous creation of an establishment sheet.

```APIDOC
## POST /<secret-slug>/api/v1/create

### Description
Creates an establishment sheet. The generation process is asynchronous.

### Method
POST

### Endpoint
`/<secret-slug>/api/v1/create`

### Parameters
#### Request Body
- **orgId** (string) - Required - The organization ID.
- **year** (integer) - Required - The year for which to create the sheet.
```

--------------------------------

### Configure Localhost Aliases

Source: https://github.com/mtes-mct/trackdechets/blob/dev/CONTRIBUTING.md

Add these entries to your /etc/hosts file to map development domains to your local machine. This is crucial for accessing services like the API, frontend, and Storybook during development.

```bash
127.0.0.1 api.trackdechets.local
127.0.0.1 trackdechets.local
127.0.0.1 notifier.trackdechets.local
127.0.0.1 storybook.trackdechets.local
```

```bash
127.0.0.1 es.trackdechets.local
```

--------------------------------

### Run Frontend Unit Tests

Source: https://github.com/mtes-mct/trackdechets/blob/dev/CONTRIBUTING.md

Command to run all frontend unit tests.

```bash
npx nx run front:test
```

--------------------------------

### Install External Secrets Operator with Helm

Source: https://github.com/mtes-mct/trackdechets/blob/dev/kubernetes/external-secrets/README.md

Installs the External Secrets Operator using Helm, including the necessary CRDs. Ensure the `external-secrets-system` namespace exists or is created.

```bash
helm repo add external-secrets https://charts.external-secrets.io
helm repo update
helm install external-secrets \
  external-secrets/external-secrets \
  -n external-secrets-system \
  --create-namespace \
  --set installCRDs=true
```

--------------------------------

### Example Rule for Emitter Company City

Source: https://github.com/mtes-mct/trackdechets/blob/dev/docs/ZodValidation.md

Illustrates a specific rule for the 'emitterCompanyCity' field, demonstrating conditional sealing, requirement based on other fields, and custom error display properties. This example shows how to implement dynamic validation logic.

```javascript
emitterCompanyCity: {
    sealed: {
      /*
      "from" est une fonction, qui peut utiliser le contexte qui
      lui est fourni pour savoir si cette règle doit être activée ou non
      */
      from: sealedFromEmissionExceptForEmitter
    },
    required: {
      /*
      ici "from" est simplement la signature à partir de laquelle
      cette règle est activée
      */
      from: "EMISSION",
      /*
      une condition pour activer cette règle en fonction d'autres
      champs du bordereau
      */
      when: bsvhu => !bsvhu.emitterCompanyAddress
    },
    // un nom de champ lisible pour les erreurs
    readableFieldName: "L\'adresse de l\'émetteur",
    // le chemin du champ dans les objets GraphQL
    path: ["emitter", "company", "city"]
  }
```

--------------------------------

### Local Deployment Script: deploy.sh

Source: https://github.com/mtes-mct/trackdechets/blob/dev/kubernetes/AUTOMATION.md

This script deploys the application to a specified environment (dev, staging, or production). It checks for kubectl and kustomize, verifies cluster connectivity, applies Kubernetes manifests using kustomize, and waits for databases to be ready. Ensure you have the necessary kubectl context configured.

```bash
#!/bin/bash
set -e

ENVIRONMENT=${1:-dev}
VALID_ENVS="dev staging production"

if [[ ! " $VALID_ENVS " =~ " $ENVIRONMENT " ]]; then
  echo "Error: Invalid environment '$ENVIRONMENT'"
  echo "Usage: ./deploy.sh [dev|staging|production]"
  exit 1
fi

echo "🚀 Deploying Trackdéchets to $ENVIRONMENT..."

# Check prerequisites
command -v kubectl >/dev/null 2>&1 || { echo "❌ kubectl not found"; exit 1; }
command -v kustomize >/dev/null 2>&1 || { echo "❌ kustomize not found"; exit 1; }

# Check cluster connectivity
if ! kubectl cluster-info >/dev/null 2>&1; then
  echo "❌ Cannot connect to Kubernetes cluster"
  exit 1
fi

# Deploy
echo "📦 Applying Kubernetes manifests..."
kubectl apply -k "kubernetes/overlays/$ENVIRONMENT"

# Wait for databases
echo "⏳ Waiting for databases to be ready..."
kubectl wait --for=condition=Ready cluster/postgres -n trackdechets --timeout=5m || true
kubectl wait --for=condition=Ready elasticsearch/elasticsearch -n trackdechets --timeout=5m || true

```

--------------------------------

### GraphQL POST Request Example

Source: https://github.com/mtes-mct/trackdechets/blob/dev/apps/doc/docs/concepts/graphql.md

Example of how to make a GraphQL request using cURL. All GraphQL operations (queries and mutations) are sent as POST requests to the root of the API. The request body must contain a JSON object with a 'query' key.

```APIDOC
## GraphQL POST Request

### Description
This example demonstrates how to send a GraphQL query using cURL. All GraphQL operations are sent via POST requests to the API's root endpoint.

### Method
POST

### Endpoint
https://api.trackdechets.beta.gouv.fr/

### Request Body
- **query** (string) - Required - The GraphQL query or mutation string.

### Request Example
```bash
curl \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  --data '{"query": "query { me { name} }"}' https://api.trackdechets.beta.gouv.fr/
```
```

--------------------------------

### Run Backend Unit Tests

Source: https://github.com/mtes-mct/trackdechets/blob/dev/CONTRIBUTING.md

Commands to run backend unit tests. You can run all tests or specify a single test file.

```bash
npx nx run back:test # run all the tests
npx nx run back:test --testFile src/path/to/my-function.test.ts # run only one test
```

--------------------------------

### Get Sheet Status

Source: https://github.com/mtes-mct/trackdechets/blob/dev/back/src/companydigest/developper_doc.md

Retrieves the current status of a generated establishment sheet.

```APIDOC
## GET /<secret-slug>/api/v1/sheet/<sheetId>

### Description
Retrieves the status of a previously requested establishment sheet.

### Method
GET

### Endpoint
`/<secret-slug>/api/v1/sheet/<sheetId>`

### Parameters
#### Path Parameters
- **sheetId** (string) - Required - The ID of the sheet to check the status for.
```

--------------------------------

### Mutation Naming Conventions

Source: https://github.com/mtes-mct/trackdechets/wiki/Sondage-conventions-de-nommage

Examples of naming conventions for mutations, including verb-first and name-first camelCase, and snake_case.

```plaintext
create<Name>
```

```plaintext
<name>Create
```

```plaintext
<name>_create
```

--------------------------------

### Run Database Migrations

Source: https://github.com/mtes-mct/trackdechets/blob/dev/kubernetes/CHECKLIST.md

Execute database migration scripts using the provided shell script.

```bash
./kubernetes/scripts/migrate.sh
```

--------------------------------

### Calling Registry Update Function

Source: https://github.com/mtes-mct/trackdechets/blob/dev/docs/RegistryExportV2.md

Example of calling the update function for registry entries within the database layer.

```typescript
import { update as updateRegistryLookup } from '../registry';

// ... inside a function
await updateRegistryLookup(registry.id, registry);
```

--------------------------------

### Business Entity Naming Conventions

Source: https://github.com/mtes-mct/trackdechets/wiki/Sondage-conventions-de-nommage

Examples of naming conventions for business entities, including options with and without prefixes/suffixes.

```plaintext
dasri, vhu, amiante
```

```plaintext
bsdDasri, bsdVhu, bsdAmiante
```

```plaintext
bordereauDasri, bordereauVhu, bordereauAmiante
```

```plaintext
formDasri, formVhu, formAmiante
```

```plaintext
dasriForm, vhuForm, amianteForm
```

```plaintext
dasriBsd, vhuBsd, amianteBsd
```

```plaintext
dasriBordereau, vhuBordereau, amianteBordereau
```

--------------------------------

### Check Browser Compatibility

Source: https://github.com/mtes-mct/trackdechets/blob/dev/README.md

Use this command to check the list of browsers supported by the project's configuration. The browser support is defined in the `./front/.browserslistrc` file.

```bash
npx browserslist ">0.1% not dead not op_mini all ie 11"
```