chore: Set up shared-models library and initial project structure for NowChessSystems

2026-03-21 17:07:28 +01:00
parent a8d457a612
commit 9c2456e928
28 changed files with 815 additions and 12 deletions
@@ -0,0 +1,57 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Build & Test Commands
+
+```bash
+# Build everything
+./gradlew build
+
+# Build a single module
+./gradlew :modules:<service>:build
+
+# Run tests for a single module
+./gradlew :modules:<service>:test
+
+# Run a specific test class
+./gradlew :modules:<service>:test --tests "de.nowchess.<service>.<ClassName>"
+```
+
+The only current module is `core` (`modules/core`).
+
+## Architecture
+
+**NowChessSystems** is a chess platform built as a Scala 3 + Quarkus microservice system.
+
+- Multi-module Gradle project; every service lives under `modules/{service-name}`.
+- Shared dependency versions live in the root `build.gradle.kts` under `extra["VERSIONS"]`.
+- Each module reads versions via `rootProject.extra["VERSIONS"] as Map<String, String>`.
+- `settings.gradle.kts` must `include(":modules:<service>")` for every module.
+
+### Stack (ADR-001)
+| Layer | Technology |
+|---|---|
+| Language | Scala 3.5.x |
+| Backend framework | Quarkus + `quarkus-scala3` extension |
+| Persistence | Hibernate / Jakarta Persistence |
+| Frontend (TBD) | Vite; React/Angular/Vue under evaluation |
+| TUI | Lanterna |
+| Container orchestration | Kubernetes + ArgoCD + Kargo |
+
+### Key Scala 3 / Quarkus Rules
+- Use `given`/`using`, not `implicit` (no Scala 2 idioms).
+- Use `Option`/`Either`/`Try`, never `null` or `.get`.
+- Jakarta annotations only (`jakarta.*`), never `javax.*`.
+- Use reactive types (`Uni`, `Multi`) for I/O; no blocking calls on the event loop.
+- **Always exclude `org.scala-lang:scala-library` from Quarkus BOM** to avoid Scala 2 conflicts.
+- **All test methods must be explicitly typed `: Unit`** — JUnit 5 + Scala 3 requires this.
+
+### Agent Workflow (for new services)
+1. **architect** → writes OpenAPI contract to `docs/api/{service}.yaml` and ADR to `docs/adr/`.
+2. **scala-implementer** → reads contract, implements service under `modules/{service}/`.
+3. **test-writer** → writes `@QuarkusTest` integration tests and plain JUnit 5 unit tests.
+4. **gradle-builder** → resolves any build/dependency issues.
+5. **code-reviewer** → reviews; reports findings back without self-fixing.
+
+Detailed working agreement (plan/verify/unresolved workflow) is in `.claude/CLAUDE.MD`.