<!-- Keep this file under 150 lines. Detailed docs are in .claude/rules/ with paths frontmatter. Add new documentation as rule files, not here. -->

# CLAUDE.md — Carrot

Carrot helps people reach their goals through daily habits — gamification, community, lifestyle brand. Users set goals (run a marathon, read 50 books, quit smoking); Carrot breaks them into daily habits that stick.

**Phase:** Foundation+ (3 apps + SQL ready + admin portal — as of May 2026)

## Tech Stack

| Layer | Technology |
|-------|-----------|
| Mobile App | Expo SDK 54 / React Native 0.81 / React 19 (iOS + Android + Web export) |
| Landing Page | Astro 5 (static, zero JS by default) — [carrot-landing.pages.dev](https://carrot-landing.pages.dev) |
| Admin Portal | Astro 5 (static) / Tailwind 4 / React island for recharts — Cloudflare Pages auto-deploy — [carrot-admin.pages.dev](https://carrot-admin.pages.dev) (planned) |
| Backend | Supabase (PostgreSQL, Auth, Storage, Edge Functions) — EU/Frankfurt — migrations ready, project not yet created |
| Payments | RevenueCat (Apple/Google In-App Subscriptions) |
| Notifications | Expo Notifications |
| Admin Auth | Cloudflare Access (Email-OTP, 3 admins whitelisted) |
| Language | TypeScript (strict mode, no JS) |
| Monorepo | npm workspaces + Turborepo |
| Mobile Builds | Local only (no EAS) — gradlew / xcodebuild |
| Node | 20+ (see `.nvmrc`) |

## Key Files

- `Carrot Ideas.pdf` — Brand vision: colors, merch designs, collab concepts
- `MARKET_RESEARCH.md` — Full DACH market analysis
- `packages/shared/src/constants/colors.ts` — Brand color tokens
- `packages/shared/src/database.types.ts` — Manual stub matching `supabase/migrations/0001-0009.sql`; will be replaced by `npm run db:types` once Supabase project exists
- `supabase/migrations/` — 9 SQL migrations + `seed.sql`, ready to apply
- `apps/mobile/WEB-CAVEATS.md` — what works on Expo Web export
- `apps/web/wrangler.toml` · `apps/mobile/wrangler.toml` · `apps/admin/wrangler.toml` — CF Pages/Workers config (compat date, vars, observability)
- `docs/CLOUDFLARE_SETUP.md` — Step-by-step CF dashboard walkthrough (3 projects + Access policies)
- `docs/ARCHITECTURE.md` — Technical patterns: offline-first, auth, gamification, push, Supabase
- `docs/DEPENDENCIES.md` — Library decisions, alternatives, phase plan
- `docs/LANDING_PAGE_DESIGN.md` — Landing page UX/UI concept
- `docs/superpowers/plans/` — Implementation plans, including 2026-05-03 master overhaul + mobile plans 2-7

## Language Rules

- Tim communicates in **German** — respond in German
- **Landing page:** bilingual (EN default at `/`, DE at `/de`) — i18n via `src/i18n/translations.ts`
- **App UI:** bilingual (DE/EN) — DACH market first, then international
- Code, variables, comments, commits, route names: **English**

## Product Positioning

- **Goal-oriented, not habit-tracking** — "Set goals. Build habits. Level up."
- Habits are the TOOL, goals are the OUTCOME
- Users don't want to "track habits" — they want to run a marathon, read 50 books, quit smoking
- Copy must always focus on goals/outcomes, not on tracking/features

## Development Principles

- **TypeScript only** — no `.js` files (except config where required: babel, metro)
- **Mobile-first** — the app is the core product
- **GDPR-compliant** from day 1 — health/habit data is special category (Art. 9), EU hosting mandatory
- **No medical claims** — stay in wellness/habits, avoid MDR (Medical Device Regulation)
- **Gamification + social features** — highest priority for retention (category avg: 5-8% day-30 retention)
- **Clean UI** — minimalist, orange + white, design tokens from `@carrot/shared`
- **Local builds** — no EAS account, build via gradlew/xcodebuild
- **New Architecture enabled** — React Native 0.81 with `newArchEnabled: true`

## Commands

```bash
npm run dev:mobile        # Start Expo app
npm run dev:web           # Start landing page (localhost:4321)
npm run build             # Build all packages
npm run typecheck         # TypeScript check all packages
npm run db:types          # Regenerate Supabase types from remote schema
npm run db:reset          # Reset database with seed data
```

Mobile builds (from `apps/mobile/`):

```bash
npm run build:apk         # Android release APK (signed w/ debug key) → ~/Downloads/Carrot-v{version}.apk
npm run build:aab         # Android release AAB (Play Store) → ~/Downloads/ (auto-increments versionCode)
npm run build:web         # Static web export → apps/mobile/dist/ (deploys to carrot-app.pages.dev)
npx expo prebuild         # Generate native projects (ios/, android/)
```

Admin portal (from `apps/admin/`):

```bash
npm run dev               # localhost:3001 (Astro dev)
npm run build             # Astro static export → ./dist
npm run preview           # Local preview of built output
```

Auto-deploys to `carrot-admin.pages.dev` on every push to `main` — no manual deploy step.

## Conventions

- **Commits:** English, concise, meaningful
- **Branching:** `feature/`, `fix/`, `docs/` prefixes
- **No secrets in git** — `.env` in `.gitignore`
- **Tabs** for indentation (see `.prettierrc`)
- **Single quotes**, trailing commas, 100 char print width
- **Design tokens** via `@carrot/shared/constants` — never hardcode colors, spacing, or font sizes
- **File naming:** kebab-case for files, PascalCase for components

## Business Context

- **Location:** Austria. **Target market:** DACH (AT/DE/CH), then Europe.
- **Monetization:** Freemium + Subscription — Solo €50/year, **Squad €80/year** (up to 5 people = €16/person). Merch, later B2B.
- **Squad subscription:** Group plan for 4-6 friends. Squad challenges, leaderboards, streaks, Squad vs Squad. Built-in viral loop (1 buyer invites 4 friends → 5 active users). No competitor offers this.
- **Competitors:** Fabulous (~$30-50M ARR), Habitica (~$2-5M ARR), Streaks, Finch (~$10M+ ARR)
- **Differentiation:** Community + lifestyle brand + creator collabs + German-language content + **Squad group subscriptions** (unique in category)
- **Key risk:** Retention — category average is 5-8% at day 30. Gamification, social accountability, and **Squad accountability** are the primary countermeasures.