99 lines
4.7 KiB
Markdown
99 lines
4.7 KiB
Markdown
# CLAUDE.md – peakUp Project Guidelines
|
||
|
||
**Last updated:** 2026-05-15 | Single source of truth. Strict compliance required.
|
||
|
||
## 1. Core Rules
|
||
|
||
- Never assume. Always read files first with tools.
|
||
- Validate state before and after changes using terminal commands.
|
||
- Remove dead/unreachable code immediately (ask first if unsure).
|
||
- Trivial tasks: Ask "Trivial? Direct edit or full workflow?"
|
||
|
||
## 2. Mandatory 4-Phase Workflow
|
||
|
||
1. **PROPOSAL** – Clear plan + impact. Wait for `OK PROPOSAL`.
|
||
2. **VALIDATE** – Brutal self-critique (NullAway, layering, regressions). Wait for `OK VALIDATE`.
|
||
3. **IMPLEMENT** – One unit at a time. Show exact diff only.
|
||
4. **VERIFICATION** – Run relevant tests. Suggest commit message.
|
||
|
||
## 3. Project Overview
|
||
|
||
- **Backend**: Quarkus (Java 21), Hibernate, PostgreSQL/TimescaleDB
|
||
- **Frontend**: Vite + React 18 + TS + Tailwind + shadcn/ui
|
||
- **Model**: Shared domain models
|
||
- **Tools**: `peakup-maven` – Maven plugin with two mojos: `PackageInfoGeneratorMojo` (generates `package-info.java`
|
||
with `@NonNull` per package) and `TypeScriptClientGeneratorMojo` (generates TS client from REST endpoints)
|
||
- **Tools**: `peakup-tools` – standalone dev utilities:
|
||
- `ModelGeneratorTool` – generates a full domain slice (entity, DAO, service, resource) from a JSON definition file.
|
||
Schema: `peakup-tools/src/main/resources/model-definition-schema.json`
|
||
Example: `peakup-tools/src/main/resources/example/example-model-definition.json`
|
||
Models are stored: `src/main/resources/definitions`
|
||
Run (from project root):
|
||
```
|
||
# Normal run — fails if any output file already exists, generates Flyway migration
|
||
$MVN -f peakup-tools/pom.xml -Dmaven.repo.local=/home/ingo/.m2/peak-repo \
|
||
compile exec:java -Dexec.mainClass=com.peakup.tools.generator.ModelGeneratorTool \
|
||
"-Dexec.args=path/to/definition.json"
|
||
|
||
# --force — overwrites existing files, skips Flyway migration generation
|
||
$MVN -f peakup-tools/pom.xml -Dmaven.repo.local=/home/ingo/.m2/peak-repo \
|
||
compile exec:java -Dexec.mainClass=com.peakup.tools.generator.ModelGeneratorTool \
|
||
"-Dexec.args=--force path/to/definition.json"
|
||
```
|
||
Output defaults to `peakup-backend/src/main/java/`. Pass a second arg to override output dir,
|
||
third arg to override Flyway migration dir (default: `peakup-backend/src/main/resources/db/migration/`).
|
||
Generated service only contains `getDAO()` + domain-specific methods — CRUD is inherited from
|
||
`AbstractService` as `public final @Transactional`.
|
||
|
||
**Backend Architecture**:
|
||
|
||
- Domain slices: `model` → `dao` → `service`
|
||
- Connectors: `connector/<name>` with full layer (`model` → `dao` → `service` → `client` → `mapper`)
|
||
- External mapping logic **must** be in `connector/<name>/mapper/`
|
||
|
||
## 4. Technical Rules
|
||
|
||
**Java / Backend**
|
||
|
||
- Java 21 + Quarkus
|
||
- Strict NullAway + mandatory `final` where possible
|
||
- Lombok: `@Data`, `@NoArgsConstructor`, `@AllArgsConstructor`, `@Slf4j`
|
||
- Checkstyle: 4 spaces, 240 char max line, K&R braces, no star imports
|
||
- Methods: preferred < 60 lines (blank lines excluded), max 7 parameters
|
||
- **Type safety is mandatory**: use native types throughout — `Instant`/`LocalDate` for dates, `Long`/`Integer` for IDs
|
||
and counts, enums for fixed value sets. Never pass dates, IDs, or enums as `String` across layer boundaries. REST DTOs
|
||
are the only exception — parse to native types immediately at the boundary.
|
||
- Use `AbstractEntity` and `AbstractTimestampedEntity`
|
||
- TimescaleDB hypertables via `AbstractTimescaleEntity`
|
||
|
||
**Frontend**
|
||
|
||
- `peakup-frontend/src/types/` and `peakup-frontend/src/api/` are **generated** – never edit manually.
|
||
- Light mode only (`#FFFFFF`)
|
||
- Accent: `from-red-500 to-orange-500` only for CTAs & charts
|
||
- TanStack Query v5 + TanStack Table v8
|
||
- Minimize `useEffect` for data fetching
|
||
- Charts: Recharts (responsive)
|
||
|
||
## 5. Naming Conventions
|
||
|
||
- Use full, meaningful names everywhere.
|
||
- No abbreviations: `athleteService`, `intervalCount`, `workplan` (not `svc`, `n`, `w`)
|
||
- Avoid `e`, `ex`, `obj`, `res`, `tmp`, `data` etc.
|
||
- Exception: `i`, `j` only in short numeric loops.
|
||
|
||
## 6. Design Violations (Fix when touching)
|
||
|
||
- Move mapping logic from importers into dedicated mappers
|
||
- Move `ActivityConnector` implementations into `connector/<name>/`
|
||
- Extract `IntervalsEnrichmentStatusEnum` and `AbstractEnumConverter`
|
||
|
||
## 7. Useful Commands
|
||
|
||
- `$MVN` = `JAVA_HOME=/home/ingo/.jdks/temurin-21.0.7 mvn -s /home/ingo/.m2/settings_peak.xml`
|
||
- Backend: `$MVN compile`, `quarkus:dev`, `test -Dtest=ClassName`
|
||
- Frontend: `npm run dev`, `npm run build`, `npm run lint`
|
||
|
||
---
|
||
|
||
**Style for Claude**: Be concise. Show **only** changed code + short explanation. Ask before large refactors. |