# Project Rules

## General
- Follow the existing code style and patterns.
- Use npm for running project commands.
- Keep code in TypeScript unless migration is required.

## Frontend Stack
- Framework: Vue 3 + Vite
- UI Library: Vuetify0
- Enabled Features: ESLint, Vue Router, UnoCSS

## Backend Stack
- Language: Java
- Server: Javalin
- Persistence: Postgres with JDBC
- Maven for dependency management

## Database migrations

All internal database schema and data changes must be made with SQL migrations in
`src/main/resources/db/migrations`. Migration filenames use:

```text
yyyyMMddHHmmss_short_description.sql
```

The 14-digit UTC timestamp is the migration version and must be unique. Migrations
are run in filename order at application startup, inside one transaction per file.
Applied versions are recorded in `schema_migrations`, so never edit or rename a
migration that may have run in another environment; add a new migration instead.

Keep migrations compatible with Postgres. Update `src/main/resources/db/reset.sql`
when adding a table so `DB_REINITIALIZE=true` can continue to rebuild disposable
test databases by dropping the application tables and replaying all migrations.



## Tests
Use JUnit 5 for backend unit test
Use Playwright for frontend end-to-end tests

## Full-stack end-to-end tests

Agents running end-to-end tests must use free ports so they do not interfere with
an existing development server. Find two currently available ports with:

```bash
node -e "const net=require('net');let left=2,ports=[];for(let i=0;i<2;i++){const s=net.createServer();s.listen(0,'127.0.0.1',()=>{ports.push(s.address().port);s.close(()=>{if(!--left)console.log(ports.join(' '))})})}"
```

Start the backend from the repository root, substituting the first free port and
the normal local database credentials:

```bash
DB_URL=jdbc:postgresql://localhost:5432/postgres \
DB_USERNAME=root \
DB_PASSWORD=root \
DB_REINITIALIZE=true \
SERVER_PORT=<backend-port> \
mvn exec:java
```

`DB_REINITIALIZE=true` drops and recreates the application's tables at startup,
so only use it for a disposable test database. `SERVER_PORT` defaults to `7070`
when omitted.

From `frontend/`, run Playwright using the second free port. Playwright starts
Vite on that port, and Vite proxies API requests to the backend:

```bash
VITE_API_TARGET=http://127.0.0.1:<backend-port> \
PLAYWRIGHT_BASE_URL=http://127.0.0.1:<frontend-port> \
npm run test:e2e
```

Keep the backend running until Playwright finishes, then stop it. The free-port
check and server startup should happen close together because another process
can claim a released port in between.