peakup/CLAUDE.md

CLAUDE.md – peakUp Project Guidelines

Last updated: 2026-04-04 | 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: Development generators

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, 120 char, K&R braces, no star imports
• Use AbstractEntity and AbstractTimestampedEntity
• TimescaleDB hypertables via AbstractTimescaleEntity

Frontend

• 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.