CLAUDE.md

1# CLAUDE.md
2 
3This file provides guidance to Claude Code when working with this repository.
4 
5## Project Overview
6 
7Neroli's Lab (SleepAPI) is a full-stack Pokémon Sleep application with three packages:
8 
9- **backend**: Express API (Bun dev, Node.js production)
10- **frontend**: Vue 3 SPA with Vuetify 3
11- **common**: Shared TypeScript library
12 
13## Essential Commands
14 
15### Development
16 
17```bash
18# Start development servers
19cd backend && npm run dev        # Backend with Bun hot reload
20cd frontend && npm run dev       # Frontend with Vite
21 
22# Build common library (build first when changing shared types)
23cd common && npm run build
24cd common && npm run build-watch # Watch mode for development
25```
26 
27### Testing & Quality
28 
29```bash
30# Run tests
31npm run test                     # All tests in package
32npm run test -- testname.test.ts # Specific test file
33npx vitest --run -- testname.test.ts # Direct vitest execution
34 
35# Code quality (REQUIRED after changes)
36npx eslint .                     # Lint current directory
37npm run type-check               # Frontend type checking (in frontend/)
38npm run _compile                  # Backend type checking (in backend/)
39```
40 
41## Architecture Quick Reference
42 
43### File Structure
44 
45- **Backend**: `controllers/` → `services/` → `daos/` → database
46- **Frontend**: `pages/` (routes) → `components/` → `stores/` (Pinia)
47- **Common**: Shared types and utilities
48 
49### Key Patterns
50 
51- Controllers use TSOA decorators (minimal, non-sensitive routes only)
52- DAOs extend AbstractDAO with repository pattern
53- Vue components follow atomic design
54- API clients in `frontend/src/services/` match backend endpoints
55 
56## Required Workflows
57 
58### Code Changes Checklist
59 
601. **Write/update tests** for any functionality changes
612. **Run tests** to verify: `npx vitest --run -- testname.test.ts`
623. **Lint changed files**: `npx eslint .`
634. **Type check**: `npm run type-check` (frontend) or `npm run _compile` (backend)
645. **Build common** if shared types changed: `cd common && npm run build`
65 
66### Testing Patterns
67 
68**Vue Component Tests (required structure):**
69 
70```typescript
71import type { VueWrapper } from '@vue/test-utils';
72import { mount } from '@vue/test-utils';
73import { beforeEach, afterEach, describe, expect, it } from 'vitest';
74import MyComponent from './my-component.vue';
75 
76describe('MyComponent', () => {
77  let wrapper: VueWrapper<InstanceType<typeof MyComponent>>;
78 
79  beforeEach(() => {
80    wrapper = mount(MyComponent, {
81      props: { someProp: 'value' }
82    });
83  });
84 
85  afterEach(() => {
86    wrapper.unmount();
87  });
88 
89  it('renders correctly', () => {
90    expect(wrapper.exists()).toBe(true);
91  });
92});
93```
94 
95**Mocking Strategy:**
96 
97- Only mock external dependencies (APIs, HTTP requests, browser features)
98- Don't mock utility functions or internal services
99- **Use mock factories from `{package}/src/vitest/mocks/`** instead of hard-coded inline mocks
100- Avoid `as any` casts - complex interfaces have proper mock factory methods
101- Each package has its own mocks directory that extends common mocks
102 
103### Frontend Design Work
104 
105- Use Playwright MCP with screenshots for self-feedback loops
106- Follow TDD approach for feature development
107- Prefer utility classes from `frontend/src/assets/common.scss` over Vuetify utilities
108 
109## Environment & Setup
110 
111### Environment Files
112 
113- Frontend: `.env` (copy from `.env.example`)
114- Backend: `.env` (copy from `.env.example`, set `DATABASE_MIGRATION=UP`)
115 
116### Database
117 
118```bash
119docker-compose up -d             # Start MySQL
120# Migrations run automatically on backend start
121```
122 
123### Package Installation
124 
125```bash
126npm install                      # Root (git hooks)
127cd backend && bun install        # Backend dependencies
128cd frontend && npm install       # Frontend dependencies
129cd common && npm install         # Common dependencies
130```
131 
132## Commit Guidelines
133 
134Follow conventional commits (enforced by commitlint):
135 
136- `feat:` new features
137- `fix:` bug fixes
138- `style:` design/UI changes
139- `chore:` maintenance
140- `refactor:` code restructuring
141- `test:` test changes
142- `perf:` performance improvements
143 
144**Rules:**
145 
146- Header ≤72 characters
147- No sentence case (avoid capitals unless proper nouns)
148- No period at end
149- No Claude Code references in commit messages
150 
151## Key Technologies
152 
153- **Backend**: Express 5, TypeScript, Knex, MySQL, TSOA
154- **Frontend**: Vue 3, Vuetify 3, Pinia, Vite, Chart.js
155- **Testing**: Vitest across all packages
156- **Runtime**: Bun (dev), Node.js (production)
157 
158## Common Tasks
159 
160### Adding API Endpoint
161 
1621. Controller in `backend/src/controllers/`
1632. Service in `backend/src/services/`
1643. Types in `common/src/types/`
1654. Build common package
1665. API client in `frontend/src/services/`
167 
168### Database Changes
169 
1701. Migration in `backend/src/database/migration/migrations/`
1712. Update types in `common/src/types/`
1723. Update DAOs
173 
174### CSS Styling
175 
176- Use utility classes from `frontend/src/assets/common.scss`
177- Common flex classes: `.flex-center`, `.flex-between`, `.flex-column`
178- Responsive text classes available
179- Prefer utility classes over Vuetify utilities or custom CSS
180- **Mobile-first:** default / base styles for narrow layouts, then `min-width` (or shared mixins) for larger breakpoints—see `.cursor/rules/frontend-rules/mobile-first-css-agent.mdc` for guides and `frontend/**/*.scss`
181- **Never use inline styles** - always use CSS classes or scoped styles
182 
183## Code Comments Guidelines
184 
185- Only use code comments if vital for explaining the code block
186- Avoid unnecessary comments that do not add meaningful context or explanation
187 
188## Best Practices
189 
190- Never use inline styles
191- Never use any as a type unless working with generics
192 
193### Typography (repo-wide)
194 
195Whenever you author or edit text anywhere in this repository (guides, docs, READMEs, UI copy, comments, commits when you propose message text, examples in code, configuration strings, etc.):
196 
197- **Never** use curly/smart apostrophes (U+2019) or curly double quotes (U+201C, U+201D). Use ASCII `'` (U+0027) and `"` (U+0022) only.
198- **Never** use the Unicode ellipsis character (U+2026). Use three ASCII periods: `...`
199- **Minimize** em dash (U+2014) and en dash (U+2013): prefer hyphen-minus (`-`, U+002D), commas, or rephrasing unless a non-hyphen dash is clearly the right editorial choice.
200 
201Strip invisible formatting characters (for example U+2060 word joiner) that may come from pasted content.
202 
203## Pokemon Sleep Game Mechanics
204 
205This section provides a comprehensive understanding of Pokemon Sleep's core mechanics as implemented in this application.
206 
207### Core Gameplay Loop
208 
209Pokemon Sleep is a sleep-tracking game where players:
210 
2111. Track their sleep to gain Sleep Score (max 100 per session)
2122. Helper Pokemon gather berries and ingredients throughout the day
2133. Feed Snorlax berries to increase its strength
2144. Cook meals 3x daily using gathered ingredients
2155. Weekly cycle resets every Monday at 04:00 local time
216 
217### Helper Pokemon Mechanics
218 
219#### Helping Frequency
220 
221- Pokemon "help" at regular intervals measured in seconds (see @common/src/types/pokemon/)
222- Example: A Pokemon with 2400s frequency helps every 40 minutes
223- Frequency is affected by energy level and various bonuses
224 
225#### Energy System (@backend/src/services/simulation-service/team-simulator/member-state/member-state.ts)
226 
227- Energy decreases by 1 every 10 minutes linearly throughout the day
228- Energy affects helping frequency:
229  - 80+ energy: 45% of base frequency (fastest)
230  - 60-79 energy: 52% of base frequency
231  - 40-59 energy: 58% of base frequency
232  - 1-39 energy: 66% of base frequency
233  - 0 energy: 100% of base frequency (slowest)
234- Energy recovery occurs during sleep and from skills/meals
235 
236#### Sneaky Snacking
237 
238- When Pokemon reach their carry limit, they automatically deliver berries to Snorlax
239- During sneaky snacking: only berries are delivered (no ingredients or skill procs)
240- Pokemon continue gathering at the same rate but auto-deliver
241 
242#### Production Types
243 
244- **Berries**: Directly increase Snorlax strength
245- **Ingredients**: Used for cooking meals
246- Pokemon roll for ingredient finding based on their ingredient percentage (which may be boosted by subskills or nature)
247- Base rates vary by species (see @common/src/types/pokemon/)
248 
249### Pokemon Specialties
250 
251Three main types of specialists with different strengths:
252 
2531. **Berry Specialists**: Higher berry output, lower ingredient/skill rates. Always 2 berries per drop baseline, and lower ingredient amounts (1 at level 1)
2542. **Ingredient Specialists**: Higher ingredient rates, lower skill rate. Always 1 berry per drop baseline, but higher ingredient amounts (2 at level 1)
2553. **Skill Specialists**: Higher skill trigger rates, can store 2 skill triggers before collecting. Lower ingredient rate and always 1 berry per drop and lower ingredient amounts (1 ingredient at level 1)
256 
257The "all" specialist also exists, and is currently only used on Darkrai.
258Darkrai
259 
260### Main Skills
261 
262Skills trigger based on skill percentage (varies by Pokemon and specialty):
263 
264- See skills here: (@common/src/types/mainskill/mainskills/)
265- Skills include energy recovery, strength boosts, ingredient gathering, crit boosts, etc.
266 
267### Cooking System (@backend/src/services/simulation-service/team-simulator/cooking-state/cooking-state.ts)
268 
269#### Meal Times
270 
271- **Breakfast**: 04:00 - 12:00
272- **Lunch**: 12:00 - 18:00
273- **Dinner**: 18:00 - 04:00
274 
275#### Cooking Mechanics
276 
277- Base critical hit chance: 10% (weekday), 30% (Sunday)
278- Critical hits: 2x strength (weekday), 3x strength (Sunday)
279- Pot size determines max ingredients per dish
280- Good Camp bonus: +50% pot size, +20% helper speed/capacity
281 
282#### Recipe Types
283 
284- Three categories: Curries, Salads, Desserts
285- Snorlax requests one type per week
286- Higher level recipes provide more strength
287 
288### Snorlax & Islands
289 
290#### Research Areas
291 
2921. **Greengrass Isle**: Random berry preference weekly
2932. **Cyan Beach**: Oran, Pecha, Pamtre berries
2943. **Taupe Hollow**: Leppa, Figy, Sitrus berries
2954. **Snowdrop Tundra**: Rawst, Persim, Wiki berries
2965. **Lapis Lakeside**: Cheri, Mago, Durin berries
2976. **Old Gold Power Plant**: Electric/Steel types
298 
299#### Snorlax Strength & Drowsy Power
300 
301- Strength calculation: @frontend/src/services/strength/strength-service.ts
302- Favorite berries provide 2x strength
303- Drowsy Power = Snorlax Strength × Sleep Score
304- Higher Drowsy Power attracts more/rarer Pokemon
305 
306### Pokemon Stats & Progression
307 
308#### Natures (@common/src/types/nature/nature.ts)
309 
310Affect five key attributes:
311 
312- Speed of Help (helping frequency)
313- Energy Recovery
314- EXP Gains
315- Ingredient Finding rate
316- Main Skill Chance
317 
318#### Subskills (@common/src/types/subskill/subskills.ts)
319 
320- Unlocked at levels 10, 25, 50, 75, 100
321- Include bonuses like Berry Finding S, Helping Speed M, Energy Recovery Bonus
322- Cannot be changed after catching
323 
324#### Evolution
325 
326- Stats change upon evolution (see @common/src/types/pokemon/)
327- Instanced properties remain (nature, subskills, ingredients)
328- Some Pokemon have special requirements (stones, items)
329 
330### Sleep Tracking
331 
332#### Sleep Types
333 
3341. **Dozing**: Light sleep with movement/noise
3352. **Snoozing**: REM sleep with snoring
3363. **Slumbering**: Deep sleep, minimal movement
3374. **Balanced**: Mix of multiple types
338 
339#### Sleep Score
340 
341- Based on sleep duration (90 minutes minimum)
342- Max score: 100 points
343- Directly converts to Pokemon EXP
344- Multiplied with Snorlax Strength for Drowsy Power
345 
346### Items & Bonuses
347 
348#### Good Camp Ticket
349 
350- +50% pot size
351- +20% helper speed
352- +20% carry capacity
353- Extra hungry Pokemon appears
354- Lasts 7 days
355 
356#### Incense
357 
358- Recovery Incense: +5% energy recovery for box Pokemon
359- Various types affect different aspects of gameplay
360 
361### Instance Properties (@common/src/types/instance/pokemon-instance.ts)
362 
363When catching Pokemon, these properties are rolled:
364 
365- Nature (unchangeable) (@common/src/types/nature/nature.ts)
366- Subskills (5 total, unlocked at certain levels) (@common/src/types/subskill/subskills.ts)
367- Ingredient sets (which specific ingredients from possibilities)
368- Gender
369- Shiny status (cosmetic only)
370 
371### Simulation Engine
372 
373The game simulation is implemented in:
374 
375- @backend/src/services/simulation-service/team-simulator/
376- Handles energy decay, help timing, skill activations, cooking
377- Runs Monte Carlo simulations for accurate predictions
378