peakup/CLAUDE.md

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.