Badge

This monorepo demonstrates one business object from persistence to user interface. A Spring Boot API stores Badge objects in PostgreSQL, three reusable clients expose the same contract, and a React console provides day-to-day CRUD and bulk data operations.

What You Will Run

The tutorial starts a complete local stack and creates one badge. The resulting object has a server-generated Long identifier, a unique immutable code, a required label, an optional description, and server-owned Instant timestamps.

Modules

Module	Purpose
api	Spring Boot CRUD API backed by JPA and PostgreSQL.
java-client	Maven client library using Java HttpClient.
react-client	TypeScript client library for React or browser apps.
backend	React + Vite management console.
dart-client	Dart package for Flutter or Dart services.
docs	MkDocs project documentation.
presentation	Marp overview of the example and its architecture.

See Recommended Copilot Skills for the skills to use when extending or maintaining each part of the monorepo.

Supported Stack Versions

Use these maintained baseline versions for local development and CI. Newer compatible patch releases are supported unless a module pins a version explicitly.

Technology	Version
Node.js	24
pnpm	11
Java	25
Maven	3.9.16
Dart SDK	3.12.2
Spring Boot	4.1.1
Vite	8.2.2
Vitest	4.1.11
Vite React plugin	6.1.1
Redux Toolkit / RTK Query	2.12

Tutorial: Run the Example

1. Start the stack

From the repository root:

make docker-up

Compose publishes the documentation on 8000, the API on 8989, and the console on 5173.

2. Create a badge

curl -X POST http://localhost:8989/api/v1/badge \
    -H "Content-Type: application/json" \
    -d '{"code":"CUSTOMER","label":"Customer","description":"Customer master data"}'

The response resembles:

{
    "id": 1,
    "code": "CUSTOMER",
    "label": "Customer",
    "description": "Customer master data",
    "createdDate": "2026-08-30T17:00:00Z",
    "lastModifiedDate": "2026-08-30T17:00:00Z"
}

The exact identifier and timestamps are assigned by the server.

3. Use the console

Open http://localhost:5173, select Badges, and open the new object by its ID. From this page you can create, inspect, update, delete, seed, import, and export badges.

Swagger UI is available at http://localhost:8989/swagger-ui.html.

4. Stop the stack

make docker-down

The PostgreSQL volume is retained. Follow Reset the demo database when you need a clean database.

Develop and Verify

make setup
make test
make build

Generate Java, React, and Dart coverage reports:

make coverage

Run only the API locally against PostgreSQL on localhost:5432:

make java-run

Then open http://localhost:8080/swagger-ui.html.

Continue with the API reference, architecture explanation, web console guide, or deployment guide.