OSS-QMET

OSS-QMET is a full-stack demo application for defining and evaluating open-source software quality models. The current implementation supports:

• user registration and login
• visual custom model creation
• DSL parse and preview
• persistence of custom quality models in PostgreSQL
• My Models and model detail retrieval
• model update and delete flows

Tech Stack

• Backend: Spring Boot, Spring Data JPA, Flyway, PostgreSQL
• Frontend: React, Vite, Vitest, Playwright
• Local infrastructure: Docker Compose

Prerequisites

• Docker Desktop with docker compose
• Java 17 or newer
• Node.js 20 or newer
• npm

Repository Layout

• ossBackend
• ossFrontend
• docker-compose.yml
• .env.example

Local Environment

The backend defaults are already set for local development:

• backend: http://localhost:8081
• frontend: http://127.0.0.1:3000
• postgres: localhost:5432

Recommended local env files:

1. Root env for backend and Docker:

cp .env.example .env

2. Frontend env:

printf 'VITE_API_BASE_URL=http://localhost:8081/api\n' > ossFrontend/.env

Do not commit .env files.

Start The Database

From the repository root:

docker compose up -d postgres

To start both database and backend container together:

docker compose up -d

Check container status:

docker compose ps

PostgreSQL data is stored in the named Docker volume oss-postgres-data.

Start The Backend

Run the backend locally:

cd ossBackend
./mvnw spring-boot:run

Backend base URL:

http://localhost:8081/api

Backend configuration is environment-driven through:

• SPRING_DATASOURCE_URL
• SPRING_DATASOURCE_USERNAME
• SPRING_DATASOURCE_PASSWORD
• FRONTEND_ORIGIN
• SERVER_PORT

Default values are defined in application.properties.

Start The Frontend

cd ossFrontend
npm install
npm run dev -- --host 127.0.0.1

Frontend URL:

http://127.0.0.1:3000

The frontend reads VITE_API_BASE_URL from ossFrontend/.env.

Database Migrations

Flyway runs automatically on backend startup.

Migration files live in:

/Users/huseyintenlik/AKY/open-source-software/ossBackend/src/main/resources/db/migration

Current baseline migration:

V1__init.sql

Rules for schema changes:

1. Do not manually alter local tables.
2. Add a new versioned Flyway migration.
3. Commit the migration with the related code change.

Exact Demo Startup Flow

This is the shortest reliable local startup sequence:

1. Start Postgres:

cd /Users/huseyintenlik/AKY/open-source-software
docker compose up -d postgres

2. Start backend:

cd /Users/huseyintenlik/AKY/open-source-software/ossBackend
./mvnw spring-boot:run

3. Start frontend:

cd /Users/huseyintenlik/AKY/open-source-software/ossFrontend
npm run dev -- --host 127.0.0.1

4. Open:

http://127.0.0.1:3000

5. Register a user, then verify this path:
   • log in
   • create a custom visual model
   • save it
   • open My Models
   • reload and confirm the model still exists
   • view details
   • edit and save
   • delete the model

Tests

Backend Tests

cd ossBackend
./mvnw test

Backend tests use an isolated H2 configuration from ossBackend/src/test/resources/application.properties, so they do not depend on the local PostgreSQL instance.

Frontend Unit Tests

cd ossFrontend
npm run test

Frontend Production Build

cd ossFrontend
npm run build

Playwright E2E

Start the backend first, then run:

cd ossFrontend
npm run e2e

Playwright uses playwright.config.ts and starts its own frontend dev server on 127.0.0.1:3000.

Demo Accounts

No global seeded demo accounts are committed.

For demos, create an account through the registration screen. Passwords are stored with BCrypt hashing in the backend.

Troubleshooting

Docker does not start

• Make sure Docker Desktop is running.
• Retry:

docker info
docker compose ps

Backend cannot connect to Postgres

• Check that the database container is healthy:

docker compose ps

• Confirm .env values match docker-compose.yml.

CORS errors from the browser

Set FRONTEND_ORIGIN to the exact frontend origin, for example:

FRONTEND_ORIGIN=http://127.0.0.1:3000

Port 8081 is already in use

Stop the conflicting process or override SERVER_PORT, then update the frontend VITE_API_BASE_URL to match.

Playwright browsers are missing

cd ossFrontend
npx playwright install chromium

Current Scope Notes

What is solid now:

• Dockerized local PostgreSQL
• Flyway-driven schema setup
• environment-based backend config
• custom model persistence with nested structure
• model retrieval, update, and delete
• backend unit tests
• frontend unit tests
• Playwright smoke coverage for auth and model persistence

What still remains a simplification:

• evaluation logic is still lighter than the target OSS-QMET vision
• DSL support is practical and usable, but not yet a full formal language implementation
• some advanced domain concepts are preserved through DTO snapshot state rather than a fully normalized schema