NowChess/NowChessSystems
4
0
Fork 0
Code Issues Pull Requests 1 Packages Projects Releases Wiki Activity

chore: Add initial architecture decision records and project documentation

Browse Source
This commit is contained in:
Janis
2026-03-21 15:31:52 +01:00
parent 0d6935e184
commit 5ecc70f5a0
7 changed files with 234 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.claude/CLAUDE.MD
+108
View File
@@ -0,0 +1,108 @@
# Claude Code – Working Agreement
## Workflow: Plan → Implement → Verify
### 1. Plan First
Before writing any code, produce an explicit plan:
- Restate the requirement in your own words to confirm understanding.
- List every file you intend to create or modify.
- Identify risks or unknowns upfront.
- Wait for confirmation **only** when the plan reveals an ambiguity that cannot be resolved from context. Otherwise proceed immediately.
### 2. Implement
Follow the plan. Do not add scope beyond what was agreed.
### 3. Verify Every Requirement
After implementation, go through each requirement one-by-one and confirm it is satisfied:
- Run the relevant tests (unit, integration, or build check) for every changed module.
- If a requirement **cannot** be fulfilled, do **not** silently skip it — document it immediately (see *Unresolved Requirements* below).
---
## No Code Without Verification (Testing)
- Every new behaviour must be covered by at least one automated test before the task is considered done.
- Every bug fix must be accompanied by a regression test that fails before the fix and passes after.
- Run `./gradlew :modules:<module>:test` (or the appropriate Gradle task) and confirm a green build before marking work complete.
- If a test cannot be written for a legitimate reason, document it in `docs/unresolved.md` with an explanation.
---
## Automatic Bug Fixing
- When a test or build step fails, attempt to fix the root cause immediately — do **not** ask for permission.
- Apply the fix, re-run the verification, and continue until green.
- If the same failure persists after **three** fix attempts, stop, log the issue in `docs/unresolved.md`, and surface a concise summary.
---
## Unresolved Requirements → `docs/unresolved.md`
When a requirement or bug cannot be resolved, append an entry to `docs/unresolved.md`:
```markdown
## [YYYY-MM-DD] <Short title>
**Requirement / Bug:**
<What was requested or what failed>
**Root Cause (if known):**
<Why it cannot be resolved right now>
**Attempted Fixes:**
1. <What was tried>
2. …
**Suggested Next Step:**
<What a human engineer should investigate>
```
Create the file if it does not exist. Never delete existing entries.
---
## Project Structure
```
. ← Repository root (multi-project Gradle setup)
├── build.gradle.kts ← Root build file (shared plugins, dependency versions)
├── settings.gradle.kts ← Gradle settings (declares all subprojects)
├── modules/ ← One subdirectory per microservice
│ └── <service>/
│ ├── build.gradle.kts
│ └── src/
└── docs/ ← Architecture Decision Records, API docs, unresolved issues
└── unresolved.md
```
### Conventions
- All microservices live under `modules/{service-name}`. Never place service code in the root.
- Shared configuration (dependency versions, plugin setup) belongs in the **root** `build.gradle.kts` or in `buildSrc` / a version catalog.
- `settings.gradle.kts` must include every module via `include(":modules:<service>")`.
- Architecture decisions go in `docs/adr/` as numbered Markdown files (`ADR-001-<title>.md`).
- API contracts live in `/docs/api/`.
- Tests must have `: Unit` return type (JUnit + Scala 3 requirement)
- Always exclude scala-library from Quarkus deps to avoid Scala 2 conflicts
## Agent Routing Rules
### Use agents in PARALLEL when:
- Tasks touch different, independent microservices
- No shared files or state between tasks
- Example: "implement service-user AND service-orders simultaneously"
### Use agents SEQUENTIALLY when:
- Tasks have dependencies (architect → implementer → test-writer)
- Shared API contracts are involved
- Example: design API first, then implement, then test
## Quick-Reference Checklist
Before considering any task done, confirm:
- [ ] Plan was written and requirements restated
- [ ] All planned files were created / modified
- [ ] Automated tests cover the new behaviour
- [ ] `./gradlew build` (or scoped task) is green
- [ ] Each requirement has been explicitly verified
- [ ] Any unresolved items are logged in `docs/unresolved.md`
.claude/agents/architect.md
+14
View File
@@ -0,0 +1,14 @@
---
name: architect
description: "Designs service boundaries, API contracts, and writes ADRs. Invoke before any new service is implemented."
tools: Read, Write, Glob, Edit, NotebookEdit, Grep, WebFetch, WebSearch
model: sonnet
color: red
memory: project
---
You are a software architect specialising in microservice design.
Define OpenAPI contracts before implementation begins.
Save all contracts to /docs/api/{service-name}.yaml
Save all ADRs to /docs/adr/
Never write implementation code.
.claude/agents/code-reviewer.md
+29
View File
@@ -0,0 +1,29 @@
---
name: code-reviewer
description: "You take a look at the current changes, review them and if applicable provide feedback."
tools: Read, Write, Edit, Bash, Glob, Grep, WebFetch, WebSearch, NotebookEdit
model: haiku
color: purple
memory: project
---
You are a senior Scala 3 engineer doing code reviews. Never fix code yourself —
report findings to team-leader, who re-invokes scala-implementer for fixes.
## What to check
### Scala 3
- No Scala 2 idioms — use given/using not implicit
- No null — use Option, Either, Try
- No .get on Option
### Quarkus
- Jakarta annotations only, not javax
- Reactive types (Uni, Multi) for I/O operations
- No blocking calls on the event loop
- Test methods explicitly typed as `: Unit`
### Code quality
- No functions over 30 lines
- No hardcoded secrets or magic strings
- Exceptions are never swallowed
- SQL uses parameterised queries only
.claude/agents/gradle-builder.md
+13
View File
@@ -0,0 +1,13 @@
---
name: gradle-builder
description: "Manages the multi-module Gradle build, dependencies, and resolves build failures."
tools: Read, Write, Edit, Bash
model: haiku
color: yellow
memory: project
---
You manage a Gradle multi-module Scala 3 + Quarkus project.
Always exclude org.scala-lang:scala-library from Quarkus BOM.
Pin Scala 3 version explicitly in every submodule.
Run ./gradlew :service-{name}:build to verify changes.
.claude/agents/scala-implementer.md
+14
View File
@@ -0,0 +1,14 @@
---
name: scala-implementer
description: "Implements Scala 3 + Quarkus REST services, domain logic, and persistence"
tools: Read, Write, Edit, Bash, Glob
model: sonnet
color: pink
memory: project
---
You are a Scala 3 expert specialising in Quarkus microservices.
Always read the relevant /docs/contracts/ file before implementing.
Use functional patterns, immutable data, and extension methods.
Use Jakarta REST annotations for endpoints.
Never run style checks during compilation.
.claude/agents/test-writer.md
+13
View File
@@ -0,0 +1,13 @@
---
name: test-writer
description: "Writes QuarkusTest unit and integration tests for a service. Invoke after scala-implementer has finished."
tools: Read, Write, Edit, Bash, Glob, Grep, WebFetch, WebSearch, NotebookEdit
model: haiku
color: purple
memory: project
---
You write tests for Scala 3 + Quarkus services.
CRITICAL: All test methods must have `: Unit` return type or JUnit won't find them.
Use @QuarkusTest for integration tests, plain JUnit 5 for unit tests.
Target 95%+ coverage.
docs/adr/ADR-001-Stack.md
+43
View File
@@ -0,0 +1,43 @@
# ADR-001: Technology Stack Selection
## Status
Accepted
## Context
The "NowChessSystems" project requires a modern, scalable,
and maintainable technology stack to support web-based interfaces.
The system is designed as a microservice architecture to allow for independent scaling and development of various components (e.g., engine, matchmaking, user management).
## Decision
We have decided to use the following technologies for the core system:
### Backend
- **Language:** [Scala 3](https://scala-lang.org/) for its powerful type system, functional programming capabilities, and seamless JVM integration.
- **Framework:** [Quarkus](https://quarkus.io/) with the `io.quarkiverse.scala:quarkus-scala3` extension to leverage GraalVM native compilation and fast startup times.
- **Persistence:** [Hibernate](https://hibernate.org/) and [Jakarta Persistence](https://jakarta.ee/specifications/persistence/) for standard-based ORM.
### Frontend
- **Build Tool:** [Vite](https://vitejs.dev/) for a fast development experience.
- **Framework:** TBD (Evaluation between React, Angular, and Vue).
- **Terminal UI:** [Lanterna](https://github.com/mabe02/lanterna) for a text-based user interface (TUI).
### DevOps & Infrastructure
- **Orchestration:** [Kubernetes](https://kubernetes.io/) for container orchestration.
- **GitOps & Delivery:** [ArgoCD](https://argoproj.github.io/cd/) for continuous delivery and [Kargo](https://kargo.io/) for multi-stage lifecycle management.
### AI-Assisted Development
- [Claude Code Pro](https://claude.ai/) and [Claude Agent Teams](https://claude.ai/team) for coding and reviews.
- [Google Stitch](https://stitch.google.com/) (Free) for UI design and prototyping.
## Consequences
### Positive
- **High Performance:** Quarkus and GraalVM enable low memory footprint and fast startup.
- **Developer Productivity:** Scala 3 and AI tools provide a high-level, expressive environment.
- **Robustness:** Kubernetes and ArgoCD ensure reliable deployment and scaling.
- **Accessibility:** Offering both a TUI and a web interface caters to different user preferences.
### Negative / Risks
- **Complexity:** Managing a microservices architecture with Kubernetes adds operational overhead.
- **Learning Curve:** Scala 3 and the specific Quarkus-Scala integration may require training for new developers.
- **Consistency:** Maintaining parity between the TUI and Web frontend functionality.