bilhej/AGENTS.md

# AGENTS.md — BilHej / Bilhälsning.se

Project-specific instructions for OpenCode. Commit this file.

---

## Project Identity

BilHej is a web platform letting Swedish residents send physical letters to
vehicle owners by entering a registration number. The sender composes a letter,
pays 49 SEK, and BilHej prints+mails it via PostNord. The sender never sees
the recipient's name or address.

**Phase 0 (current):** Manual workflow. No Transportstyrelsen or PostNord API
integration yet. Owner address is obtained manually by a human and entered into
the admin panel.

Tech stack: Vue.js 3 (Vite, Pinia) frontend + Java 21 Spring Boot 4 backend +
PostgreSQL 16. Deployed via Docker Compose.

---

## Build, Lint, Test & Run Commands

Always run these after making changes to verify nothing is broken.

Gradle lives at repo root. All commands below run from the repo root unless noted.

### Quick start (everything)

```bash
cp .env.example .env    # first time only, then fill in keys
docker compose up -d    # starts postgres, backend, frontend
./gradlew up            # same as above (Gradle wrapper)
```

### All-in-one

```bash
./gradlew check         # frontend lint → frontend test → backend test → coverage verification
./gradlew coverage      # backend + frontend tests with coverage reports
./gradlew up            # docker compose up -d
./gradlew down          # docker compose down
./gradlew reset         # docker compose down -v && docker compose up -d (full DB reset)
```

### Frontend (Vue.js 3 + Vite)

```bash
cd frontend
npm install          # first time only
npm run dev          # dev server on :3000 with HMR
npm run build        # production build
npm run lint         # ESLint
npm run test         # vitest
npm run test:coverage # vitest with coverage (HTML at frontend/coverage/)
```

### Backend (Spring Boot 4 + Java 21)

```bash
./gradlew :backend:bootRun    # dev server on :8080
./gradlew :backend:test       # JUnit 5 + Mockito (backend only)
```

### Stripe webhooks (local testing)

```bash
stripe listen --forward-to localhost:8080/api/webhooks/stripe
```

### Database

Flyway migrations run automatically on Spring Boot startup. Migration files
live in `backend/src/main/resources/db/migration/`. Naming: `V<number>__descriptive_name.sql`.

To reset: `docker compose down -v && docker compose up -d`.

---

## Project Structure

```
bilhej/
├── frontend/                # Vue.js 3 SPA (Vite)
│   ├── src/
│   │   ├── pages/           # Route-level page components
│   │   ├── components/      # Reusable UI components
│   │   ├── composables/     # useXxx.ts shared logic
│   │   ├── stores/          # Pinia stores
│   │   ├── api/             # API client modules
│   │   ├── router/          # Vue Router config
│   │   └── assets/          # Static files, CSS
│   └── ...
├── backend/                 # Spring Boot 4 (Java 21) — Gradle subproject
│   ├── build.gradle              # Spring Boot plugin, Java deps, test config
│   ├── src/main/java/se/bilhalsning/
│   │   ├── config/          # @Configuration classes
│   │   ├── controller/      # REST controllers
│   │   ├── dto/             # Request/response DTOs
│   │   ├── entity/          # JPA entities
│   │   ├── repository/      # Spring Data JPA repos
│   │   ├── service/         # Business logic
│   │   ├── security/        # JWT filter, UserDetailsService
│   │   ├── exception/       # Custom exceptions + @ControllerAdvice
│   │   └── mapper/          # Entity ↔ DTO mapping
│   └── src/main/resources/
│       ├── application.yml            # default (H2, IDE dev)
│       ├── application-docker.yml     # docker profile (PostgreSQL)
│       └── db/migration/              # Flyway migrations
├── docker/                  # Dockerfiles
│   ├── backend.Dockerfile              # dev: JDK 21 + gradle :backend:bootRun
│   ├── backend.prod.Dockerfile         # prod: multi-stage (Gradle build → JRE Alpine, non-root)
│   ├── frontend.Dockerfile             # dev: Node 24 + vite dev server
│   ├── frontend.prod.Dockerfile        # prod: multi-stage (Node build → nginx)
│   ├── nginx.conf                      # prod: SPA fallback + /api reverse proxy
│   └── entrypoint.sh                   # prod: self-signed cert generation
├── docker-compose.yml       # dev: postgres + backend (bootRun) + frontend (Vite HMR)
├── docker-compose.prod.yml  # prod: multi-stage images, no source mounts, restart always
├── gradlew                  # Gradle wrapper (repo root)
├── gradle/
│   └── wrapper/
├── settings.gradle          # rootProject.name + include 'backend'
├── build.gradle             # convenience tasks: check, up, down, reset
├── .env.example
├── AGENTS.md                # This file
├── README.md
├── REQUIREMENTS.md
└── CODING_GUIDELINES.md
```

---

## Conventions (Summary)

Full details in `@CODING_GUIDELINES.md`. Key rules:

### Both sides
- Code and comments in English. User-facing strings in Swedish.
- No commented-out code. Delete it.
- Functions stay small (<30 lines).

### Git
- Create `feature/*`, `fix/*`, or `chore/*` branches from `develop`.
- Never commit directly to `master` or `develop`.
- Merge strategy: fast-forward or merge — either is fine.
- Commit messages must be thorough: describe what changed, why, and
  list concrete changes as bullet points. Never write single-line
  "feat: add X" messages.

### Frontend (Vue.js 3)
- `<script setup>` with Composition API only. Never Options API.
- File naming: PascalCase for pages/components, camelCase (`useXxx`) for composables.
- API calls live in `api/` modules, never in components.
- Component styles are scoped.

### Backend (Spring Boot 4)
- Constructor injection with `@RequiredArgsConstructor`. No `@Autowired`.
- DTOs: prefer Java records. No bare entities in responses.
- Controllers stay thin. All logic in services.
- Use `@ControllerAdvice` for consistent error responses (`{ "message": "..." }`).
- Lombok: `@RequiredArgsConstructor`, `@Getter`, `@Setter`, `@NoArgsConstructor` are all fine. Prefer records for DTOs.

### Database
- Table names: snake_case, plural. PKs: UUID, generated in code.
- Timestamps: `created_at`, `updated_at`. Use `Instant` in Java.
- Enums: stored as VARCHAR.
- Index every FK and every column used in WHERE.

---

## Critical Gotchas

### Phase 0: Address lookup is MANUAL
There is no Transportstyrelsen API integration yet. When an order is paid, a
human must manually request the owner address via the "Fråga om fordonsägare"
form and update the admin panel. Do NOT write code that calls an API that
doesn't exist yet. The backend should store the order and wait for an admin
to mark it as processed.

### Never store recipient addresses
After the address is used to mail the letter, it must be deleted. The Order
entity must NOT have an address field. The address lookup and mailing are
external/human processes in Phase 0.

### Stripe webhook signature verification
Always verify `stripe-signature` header using `STRIPE_WEBHOOK_SECRET`.
Webhook endpoint is public (no auth). Without signature verification an
attacker could mark orders as paid.

### Swedish UI strings
All text visible to end users must be in Swedish. Button labels, error
messages, validation text, email content, template bodies. Only developer
facing content is in English.

### JWT in Authorization header
Backend expects `Authorization: Bearer <token>`. Frontend interceptor must
attach this to all API calls. Unauthorized APIs (register, login, webhook,
public vehicle info) must be excluded from the Spring Security filter chain.

---

## Testing Approach

This project follows **Test-Driven Development (TDD)**. Write tests before
or alongside implementation. Every feature ticket should include tests in
the same PR — never merge code without corresponding tests.

### Backend
- JUnit 5 + Mockito for service layer tests.
- `@WebMvcTest` for controller tests.
- Test naming: `shouldXxxWhenYyy`.
- Use test profile with H2 or Testcontainers for DB-dependent tests.
- Flyway migrations must run in test profile too.

### Frontend
- Vitest for composables and utility functions.
- Component tests with Vue Test Utils where needed.
- E2E tests with Playwright in `frontend/e2e/`.

### E2E (Playwright)
- `npm run test:e2e` — runs all Playwright tests (headless Chromium).
- Requires `docker compose up` (backend + frontend running).
- Config: `frontend/playwright.config.ts`.
- Tests: `frontend/e2e/*.spec.ts`.
- Docker CI: `npm run test:e2e:ci` — runs tests inside official Playwright Docker container. Starts postgres, backend, frontend, and Playwright via `docker-compose.ci.yml`. Use for consistent environment or CI pipelines.

### CI (future)
- `./gradlew check` and `npm run test && npm run lint` must pass before merge.

---

## Coverage

```bash
./gradlew coverage    # backend + frontend tests with coverage
```

Coverage thresholds are enforced during `./gradlew check`. PRs must maintain
or improve coverage.

| Layer    | Lines | Branches | Functions |
|----------|-------|----------|-----------|
| Backend  | 70%   | 60%      | —         |
| Frontend | 70%   | 60%      | 70%       |

HTML reports:
- Backend: `backend/build/reports/jacoco/index.html`
- Frontend: `frontend/coverage/index.html`

---

## External References

For detailed conventions, load `@CODING_GUIDELINES.md`.
For product requirements and business logic, load `@REQUIREMENTS.md`.
For setup and quick start, load `@README.md`.

These are lazy-loaded by OpenCode — only read them when the task at hand
needs the detail.