peakup/CLAUDE.md

CLAUDE.md – peakUp Project Guidelines

Last updated: 2026-04-03 | Single source of truth. Strict compliance required.

1. Core Rules

• Never assume. Always read files and structure first using tools.
• Use terminal commands (ls, rg, mvn, npm) to validate before and after changes.
• Remove unreachable/dead code immediately (ask user first if unsure).
• For trivial tasks (renames, typos, small fixes): Ask "Trivial? Direct edit or full workflow?"

2. Mandatory 4-Phase Workflow

1. PROPOSAL – Clear plan + before/after diff + 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.
4. VERIFICATION – Run relevant tests. End with suggested commit message.

3. Project Structure

• peakup-backend: Quarkus (Java 21), Hibernate, PostgreSQL/TimescaleDB
• peakup-frontend: Vite + React 18 + TypeScript + Tailwind + shadcn/ui
• peakup-tools: Development generators
• peakup-model: Shared domain models

Backend Architecture (com.peakup):

• Domain slices (activity, athlete): model → dao → service
• Connectors: connector/<name> with model → dao → service → client → mapper
• All external mapping logic must live in connector/<name>/mapper/

4. Important Technical Rules

Java / Backend:

• Java 21 + Quarkus
• Strict NullAway compliance (@Nullable, @SuppressWarnings("NullAway.Init") only when necessary)
• Lombok: @Data, @NoArgsConstructor, @AllArgsConstructor, @Slf4j
• Checkstyle: 4 spaces, 120 char line limit, K&R braces, no star imports
• Use AbstractEntity and AbstractTimestampedEntity
• TimescaleDB hypertables via AbstractTimescaleEntity

Frontend:

• Light mode only (#FFFFFF)
• Accent: red-to-orange gradient (from-red-500 to-orange-500) only for CTAs and charts
• Use TanStack Query v5 + TanStack Table v8
• Prefer Server Components / minimal useEffect for data fetching
• Charts: Recharts (always responsive)

5. Design Violations to Fix When Touching

• Move mapping logic from importers into dedicated mappers
• Move ActivityConnector implementations into connector/<name>/
• Extract IntervalsEnrichmentStatusEnum and AbstractEnumConverter properly

6. Useful Commands

Backend:

• $MVN compile
• $MVN quarkus:dev
• $MVN test -Dtest=ClassName

Frontend:

• npm run dev
• npm run build

Tools:

• PackageInfoGenerator (in peakup-tools)

---

Style: Be concise. Show only changed code + short explanation. Ask before large refactors.