# Development Guide

Detailed setup, testing, code quality, and deployment instructions for Pluscare.

## Local environment (Laravel Sail)

### Enable git hooks (one-time, per clone)

This repo ships a shared **pre-push** hook that runs static analysis and blocks the push if it finds errors. On pushes to `testing` or `production`, it also runs the PHP test suite with a coverage gate. Activate it once on your **host** (not inside Sail):

```bash
composer hooks:install
# equivalent: git config core.hooksPath .githooks
```

In an emergency you can bypass the hook with `git push --no-verify`.

### Clone and start

Make sure you have [Docker and Docker Compose installed](https://www.docker.com/).

```bash
git clone git@github.com:Cplussrl/pluscare.git
cd pluscare
cp .env.example .env
./vendor/bin/sail up -d
```

### Install dependencies

```bash
./vendor/bin/sail composer install
./vendor/bin/sail npm install
```

### Application key and database

```bash
./vendor/bin/sail artisan key:generate
./vendor/bin/sail artisan migrate --seed
```

### Run the app

```bash
./vendor/bin/sail npm run dev          # frontend dev server
./vendor/bin/sail artisan queue:work   # queue worker (required for jobs)
```

The app runs at http://localhost. Default admin credentials:

- Email: `test@example.com`
- Password: `password`

### Local tools

| Service | URL | Credentials |
|---------|-----|-------------|
| Adminer (DB GUI) | http://localhost:8099 | User: `sail`, Password: `password` |
| Mailpit (emails) | http://localhost:8025 | — |

## Project structure

```
├── app/              # Laravel backend
├── resources/js/     # React + Inertia frontend
│   ├── Pages/
│   ├── Components/
│   └── types/
├── database/         # Migrations, seeders
├── routes/           # Web/API routes
├── tests/            # Backend tests
├── public/           # Public assets
└── tailwind.config.js
```

## Running tests

Backend (PHPUnit):

```bash
./vendor/bin/sail test
```

### Test coverage gate

CI enforces a **minimum PHP line-coverage floor** (currently **45%**). The suite must pass **and** meet the floor, or the Quality workflow fails and deploys to `testing` / `production` are blocked.

Run the same gate locally:

```bash
./vendor/bin/sail composer test:coverage
```

To inspect coverage without enforcing the floor:

```bash
./vendor/bin/sail artisan test --coverage
```

**Requirements:** a coverage driver (`pcov` or `xdebug`) must be enabled in PHP. Sail's PHP 8.4 image includes PCOV by default.

**Ratchet rule:** when total coverage improves, raise `--min=45` in both `.github/workflows/quality.yml` and the `test:coverage` script in `composer.json`. Never lower the floor.

The same test suite (with coverage gate) runs automatically in CI on GitHub-hosted runners before any deploy to `testing` or `production`.

## Code quality and static analysis

This project enforces static analysis on **both** PHP and JS/TS. The same checks that run in CI can (and should) be run locally before you push. A release/deploy will **fail** if any of these report errors.

### Tools

| Area | Tool | What it checks |
|------|------|----------------|
| PHP | **Larastan** (PHPStan, lvl 5) | Type errors, dead code, Laravel-aware bugs |
| JS / TS | **ESLint** | Lint rules, React hooks, code-quality issues |
| JS / TS | **tsc --noEmit** | TypeScript type errors |

### Run the checks locally

PHP (Larastan):

```bash
./vendor/bin/sail composer analyse
```

JS / TS (ESLint + type-check):

```bash
./vendor/bin/sail npm run check
```

> `npm run lint` auto-fixes issues; `npm run check` only verifies (no fixes) and is what the pre-push hook and CI gate use.

PHP test coverage (same gate as CI):

```bash
./vendor/bin/sail composer test:coverage
```

### Pre-push hook

After enabling git hooks, every `git push` automatically runs Larastan + ESLint + `tsc` and is blocked if errors are found.

When pushing to **`testing`** or **`production`**, the hook also runs `composer test:coverage` (tests + minimum coverage floor). Bypass only in emergencies with `git push --no-verify`.

### What CI does

A GitHub-hosted **Quality** workflow (`.github/workflows/quality.yml`) runs on every pull request and on pushes to `main`. It executes:

- Larastan (PHPStan level 5 + baseline)
- ESLint (verify only)
- TypeScript type-check (`tsc --noEmit`)
- PHPUnit tests with PCOV coverage (MySQL service container), failing if coverage drops below the configured floor (`--min=45`)

Deploys to `testing` and `production` depend on this workflow via `needs: quality` in `.github/workflows/deploy.yml`. **If static analysis, tests, or coverage fail, the deploy does not run.**

### PHPStan baseline

The file `phpstan-baseline.neon` records pre-existing violations so they don't break the build.

**Rules:**

- **New / changed code must pass** at level 5 — do not add new errors.
- If you legitimately resolve baselined errors, regenerate it:
  ```bash
  ./vendor/bin/sail composer analyse:baseline
  ```
- Do **not** regenerate the baseline just to silence a new error you introduced. Fix the code instead.

For PR workflow and commit conventions, see [CONTRIBUTING.md](../CONTRIBUTING.md).

## Deployment

### Server requirements

- PHP 8.4
- Queue worker (e.g. Supervisor or Laravel Horizon)

### Steps

1. Set up `.env` with production values.
2. Install dependencies:

```bash
composer install --optimize-autoloader --no-dev
npm ci && npm run build
```

3. Run migrations:

```bash
php artisan migrate --force
```

4. Start queue workers and the web server.

## Custom commands

| Command | Description |
|---------|-------------|
| `measures:sync <email> <type> <from> <to>` | Sync measures of the given type for the user with the given email, within the specified date range |

## Integration dashboards

| Integration | Management URL |
|-------------|----------------|
| Withings API | [Withings developer dashboard](https://developer.withings.com/dashboard/) |
| WhatsApp API | [Meta App dashboard](https://developers.facebook.com/apps/1133990871534824/dashboard/?business_id=977057774056489) |
| WhatsApp message templates | [WhatsApp Manager](https://business.facebook.com/latest/whatsapp_manager/overview?business_id=977057774056489&asset_id=679759214507935) |

See also [features/withings-integration.md](features/withings-integration.md) and [features/notifications.md](features/notifications.md).