allmy.work/CLAUDE.md

## Project Configuration

- **Language**: TypeScript
- **Package Manager**: Bun
- **Add-ons**: none

---

# CLAUDE.md

## Project Overview

**Name**: allmywork
**Purpose**: Portfolio web application
**Stack**: SvelteKit + Bun + Biome + Tailwind CSS + Feature Sliced Design (FSD)
**Deployment**: Self-hosted on VPS with Docker

---

## Bun Usage Guidelines

**Always use `bun` commands, never `npm`**:

- **Package management**: `bun install`, `bun add`, `bun remove`
- **Script execution**: `bun run <script-name>`
- **Running binaries**: Use `bunx <package>` instead of `npx <package>`
- **Test runner**: `bun test` or `bun run test` (Vitest via Bun)

**Examples**:
```bash
# Install dependencies
bun install

# Add dependency
bun add -D tailwindcss

# Run script
bun run dev

# Run binary (instead of npx)
bunx @biomejs/biome init

# Run tests (Vitest via Bun)
bun run test
```

---

## Agent Fleet

Use the following agents for different tasks:

| Agent | When to Use |
|--------|-------------|
| `technical-architect` | Design architecture, API schemas, database design |
| `builder` | Write code, implement features, fix bugs, manage Git |
| `qa-reliability-engineer` | Test strategy, performance analysis, SLOs |
| `design-specialist` | UI/UX design, component design, styling |
| `knowledge-architect` | Documentation, research, explain concepts |
| `ops-engineer` | Deployment, CI/CD, infrastructure |
| `security` | Security review, vulnerability assessment |
| `workflow-orchestrator` | Multi-agent task coordination |

---

## Technology Stack

### Core Framework
- **SvelteKit**: Full-stack framework with file-based routing
- **Svelte 5**: Using runes (`$state`, `$derived`, `$effect`) and snippets
- **TypeScript**: Strict mode enabled

### Runtime & Build
- **Bun**: Package manager and runtime
- **Vite**: Build tool (included with SvelteKit)

### Code Quality
- **Biome**: Linting and formatting (ESLint/Prettier replacement)
- Configuration: Includes `.svelte` files in `files.includes`

### Styling
- **Tailwind CSS**: Utility-first CSS
- Integration: Via PostCSS with `vitePreprocess({ style: true })`
- Pattern: Mixed approach - utilities for one-off, classes for repeated patterns

### Architecture
- **Feature Sliced Design (FSD)**:
  - `pages/` - Full pages
  - `features/` - User interactions
  - `entities/` - Business entities
  - `widgets/` - Composed components
  - `shared/` - Shared code
  - `app/` - SvelteKit routes (configured via `svelte.config.ts`)

### Testing
- **Vitest**: Unit testing (Vite-native)
- **Playwright**: E2E testing
- Coverage target: 80%+ for new code

---

## Development Workflow

### 1. Start Development
```bash
# Install dependencies
bun install

# Start dev server
bun run dev -- --open

# Watch for changes
bun run dev
```

**Note**: Always use `bun` commands, never `npm`. For running binaries (like npx), use `bunx` instead.

### 2. Code Quality
```bash
# Lint code
bun run lint

# Format code
bun run format

# Check format without modifying
bun run format:check

# Fix all issues
bun run lint:fix && bun run format
```

### 3. Testing
```bash
# Run unit tests
bun run test

# Run E2E tests
bun run test:e2e

# Run all tests
bun run test:all

# Watch mode
bun run test:watch

# Coverage report
bun run test:coverage
```

### 4. Build & Deploy
```bash
# Build for production
bun run build

# Preview build
bun run preview

# Build Docker image
docker build -t allmywork:latest .

# Run Docker container
docker run -d -p 3000:3000 --restart unless-stopped allmywork:latest
```

---

## Code Conventions

### Naming

| Type | Convention | Example |
|------|------------|----------|
| Components | PascalCase | `UserProfile.svelte` |
| Functions/Files | camelCase | `formatDate.ts`, `getUserData` |
| Types/Interfaces | PascalCase | `UserData`, `PaymentResult` |
| Constants | UPPER_SNAKE_CASE | `MAX_RETRY_COUNT` |

### Comment Style

**Multiline** (for documentation and types):
```typescript
/**
 * Process payment with retry logic
 * Handles transient failures with exponential backoff
 */
```

**One-line** (for short remarks):
```typescript
// Validate input before processing
```

**Rule**: "Less is more" - short yet capacitive, explaining core logic and caveats

### Commit Messages

**Format**: `prefix(featureName/fileName): short yet capacitive one-line description`

**Prefixes**:
- `feat` - New feature introduced
- `fix` - Bug fix
- `chore` - Maintenance tasks (no code changes)
- `refactor` - Code refactoring (no functional change)
- `docs` - Documentation changes
- `style` - Code style changes
- `test` - Test additions/corrections
- `perf` - Performance improvements
- `ci` - CI/CD changes
- `build` - Build system changes
- `revert` - Revert previous commit

**Examples**:
```
feat(auth): add OAuth2 token refresh flow
fix(payment): resolve memory leak in service
docs(readme): update deployment instructions
```

---

## FSD Structure

```
src/
├── pages/          # Full pages (top-level FSD layer)
│   ├── home/
│   │   ├── ui/
│   │   │   └── HomePage.svelte
│   │   └── index.ts
│   └── about/
├── features/        # User interactions
│   ├── auth/
│   │   ├── ui/
│   │   │   ├── LoginForm.svelte
│   │   │   └── RegisterForm.svelte
│   │   ├── model/
│   │   │   ├── useAuth.ts
│   │   │   └── types.ts
│   │   └── index.ts
│   └── contact/
├── entities/        # Business entities
│   ├── user/
│   │   ├── ui/
│   │   │   └── UserAvatar.svelte
│   │   ├── model/
│   │   │   └── types.ts
│   │   └── index.ts
│   └── project/
├── widgets/         # Composed UI components
│   ├── header/
│   │   ├── ui/
│   │   │   └── Header.svelte
│   │   └── index.ts
│   └── footer/
├── shared/          # Shared code
│   ├── ui/
│   │   ├── Button.svelte
│   │   └── Input.svelte
│   ├── config/
│   │   └── site.ts
│   └── lib/
│       └── api.ts
└── app/            # SvelteKit app layer
    └── routes/
        ├── +layout.svelte
        ├── +page.svelte
        └── about/
            └── +page.svelte
```

### FSD Rules

- **Bottom-up composition**: entities → features → widgets → pages → app
- **Public API**: Each slice exports via `index.ts`
- **No upward dependencies**: Lower layers cannot import from higher layers
- **Shared**: Only use `shared/` for truly cross-cutting concerns

---

## Key Workflows

### Creating a Feature

1. Create feature branch: `git checkout -b feature/featureName`
2. Plan FSD slice structure (pages → features → entities)
3. Implement entities (bottom layer)
4. Implement features with business logic
5. Compose widgets (if needed)
6. Create page
7. Integrate in `app/routes/+page.svelte`
8. Write tests (unit + E2E)
9. Commit: `git commit -m "feat(feature): description"`
10. Create PR

### Running Tests Before Commit

```bash
# Always run before committing
bun run lint          # Check code quality
bun run test:all      # Run all tests
bun run format:check   # Check formatting

# Fix issues
bun run lint:fix
bun run format
```

### Building for Deployment

1. Run tests: `bun run test:all`
2. Lint code: `bun run lint`
3. Build: `bun run build`
4. Build Docker image: `docker build -t allmywork:latest .`
5. Test Docker container: `docker run -p 3000:3000 allmywork:latest`
6. Deploy to VPS (see docs/deployment.md)

---

## Important Notes

### Svelte 5 Features
- Use runes for reactivity: `$state`, `$derived`, `$effect`
- Use snippets for reusable logic
- TypeScript strict mode enabled

### Biome Configuration
- Lints and formats `.svelte` files
- Initialize with `bunx @biomejs/biome init`
- Run `bun run lint` and `bun run format` before commits
- Configuration in `biome.json`

### Tailwind Usage
- Direct utilities: `class="p-4 bg-blue-500 text-white"` (one-off)
- Component classes: Repeated patterns extracted to shared components
- Design tokens in `tailwind.config.ts`

### Deployment
- Self-hosted on VPS with Docker
- No Vercel/Netlify integration
- Docker image contains full application
- Use `docker restart allmywork` for updates

### Git Workflow
- Feature branches with PRs
- Use `skip orchestrator` when committing
- Conventional commit format enforced
- Self-review before merging

---

## Documentation

**Project Docs**: `/docs/` folder contains detailed guides
- `docs/development.md` - Development workflow
- `docs/testing.md` - Testing strategy
- `docs/deployment.md` - Deployment procedures
- `docs/fsd.md` - FSD architecture guide

**External Resources**:
- SvelteKit: https://kit.svelte.dev/docs
- Svelte 5: https://svelte.dev/docs/runes
- Bun: https://bun.sh/docs
- Biome: https://biomejs.dev
- Tailwind: https://tailwindcss.com/docs
- FSD: https://feature-sliced.design

---

## Troubleshooting

### Build Issues
```bash
# Clear build cache
rm -rf .svelte-kit
rm -rf node_modules/.vite

# Rebuild
bun install
bun run build
```

### Biome Not Formatting Svelte Files
- Check `biome.json` includes `.svelte` in `files.includes`
- Ensure Biome extension is installed in VS Code

### Tailwind Classes Not Applying
- Check `src/app.css` includes Tailwind directives
- Verify `tailwind.config.ts` content paths include `src/**/*.{svelte,ts,js}`
- Ensure PostCSS is enabled in `svelte.config.ts`

### FSD Import Errors
- Check slice `index.ts` exports
- Verify no upward dependencies
- Ensure proper path aliases configured

---

## Getting Help

**For code implementation**: Use `builder` agent
**For architecture decisions**: Use `technical-architect` agent
**For testing issues**: Use `qa-reliability-engineer` agent
**For UI/UX design**: Use `design-specialist` agent
**For documentation**: Use `knowledge-architect` agent
**For deployment**: Use `ops-engineer` agent
**For security review**: Use `security` agent

**Multi-agent tasks**: Use `workflow-orchestrator` agent

---

## Code Style

### Formatting (Biome)
- Indent: tabs
- Quote style: double quotes for JS/TS, double quotes for Svelte attributes
- Line width: 120 characters
- Semicolons: always
- Trailing commas: all

### TypeScript
- Strict mode: on
- Prefer `interface` over `type` for object shapes
- Always type component props via an `interface Props { ... }` block
- Use `$props()` rune — never `export let`
- Use `$derived()` and `$effect()` — never Svelte 4 `$:` syntax
- Use `$state()` for all reactive primitives

### Component Conventions
- File name: PascalCase (`Button.svelte`, `ProjectCard.svelte`)
- Store files: camelCase with `.svelte.ts` suffix (`sidebarStore.svelte.ts`)
- Story files: `.stories.svelte` suffix (Storybook CSF with Svelte addon)
- Test files: `.test.ts` for unit, `.svelte.test.ts` for component tests
- Each slice exports a public API via `index.ts`

### Svelte 5 Patterns
```svelte
<script lang="ts">
import { cn } from '$shared/lib/cn';
import type { Snippet } from 'svelte';
import type { HTMLButtonAttributes } from 'svelte/elements';

interface Props extends HTMLButtonAttributes {
    variant?: 'primary' | 'secondary';
    children: Snippet;
    class?: string;
}

let { variant = 'primary', children, class: className, ...rest }: Props = $props();

const classes = $derived(cn(baseStyles, variantStyles[variant], className));
</script>

<button class={classes} {...rest}>
    {@render children()}
</button>
```

### Comments
- Multiline JSDoc (`/** ... */`) for exported functions and component description headers
- Single-line (`//`) for inline logic remarks
- Principle: "less is more" — explain the *why*, not the *what*

### Import Order (Biome organizeImports)
1. Svelte/SvelteKit built-ins (`svelte`, `$app/...`)
2. FSD layer aliases (`$shared/...`, `$entities/...`, etc.)
3. Relative imports (`./`, `../`)

### Commit Messages
Format: `prefix(scope): short description`
Prefixes: `feat`, `fix`, `chore`, `refactor`, `docs`, `style`, `test`, `perf`, `ci`, `build`, `revert`
Example: `feat(shared/ui): add Button component with brutalist variants`