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:

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:

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:

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:

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.

2.6 KiB Raw Blame History