# AGENTS.md - Coding Guidelines for CLQMS Frontend

## Project Overview

SvelteKit frontend for Clinical Laboratory Quality Management System (CLQMS). Uses Svelte 5 runes, TailwindCSS 4, DaisyUI, and Lucide icons.

## Build Commands

```bash
# Development server
npm run dev

# Production build
npm run build

# Preview production build
npm run preview

# Sync SvelteKit (runs automatically on install)
npm run prepare
```

## Testing

**No test framework configured yet.** When adding tests:
- Use Vitest for unit tests (recommended with SvelteKit)
- Use Playwright for E2E tests
- Run single test: `vitest run src/path/to/test.js`
- Run tests in watch mode: `vitest`

## Code Style Guidelines

### JavaScript/TypeScript

- **ES Modules**: Always use `import`/`export` (type: "module" in package.json)
- **Semicolons**: Use semicolons consistently
- **Quotes**: Use single quotes for strings
- **Indentation**: 2 spaces
- **Trailing commas**: Use in multi-line objects/arrays
- **JSDoc**: Document all exported functions with JSDoc comments

### Svelte Components

```svelte
<script>
  // 1. Imports first - group by: Svelte, $lib, external
  import { onMount } from 'svelte';
  import { goto } from '$app/navigation';
  import { auth } from '$lib/stores/auth.js';
  import { login } from '$lib/api/auth.js';
  import { Icon } from 'lucide-svelte';
  
  // 2. Props (Svelte 5 runes)
  let { children, data } = $props();
  
  // 3. State
  let loading = $state(false);
  let error = $state('');
  
  // 4. Derived state (if needed)
  let isValid = $derived(username.length > 0);
  
  // 5. Effects
  $effect(() => {
    // side effects
  });
  
  // 6. Functions
  function handleSubmit() {
    // implementation
  }
</script>
```

### Naming Conventions

- **Components**: PascalCase (`LoginForm.svelte`)
- **Files/Routes**: lowercase with hyphens (`+page.svelte`, `user-profile/`)
- **Variables**: camelCase (`isLoading`, `userName`)
- **Constants**: UPPER_SNAKE_CASE (`API_URL`, `STORAGE_KEY`)
- **Stores**: camelCase, descriptive (`auth`, `userStore`)
- **Event handlers**: prefix with `handle` (`handleSubmit`, `handleClick`)

### Imports Order

1. Svelte imports (`svelte`, `$app/*`)
2. $lib aliases (`$lib/stores/*`, `$lib/api/*`, `$lib/components/*`)
3. External libraries (`lucide-svelte`)
4. Relative imports (minimize these, prefer `$lib`)

### Project Structure

```
src/
  lib/
    api/          # API client and endpoints
    stores/       # Svelte stores
    components/   # Reusable components
    assets/       # Static assets
  routes/         # SvelteKit routes
    (app)/        # Route groups
    login/
    dashboard/
```

### API Client Patterns

```javascript
// src/lib/api/client.js - Base client handles auth
import { apiClient, get, post, put, del } from '$lib/api/client.js';

// src/lib/api/feature.js - Feature-specific endpoints
export async function getItem(id) {
  return get(`/api/items/${id}`);
}

export async function createItem(data) {
  return post('/api/items', data);
}
```

### Error Handling

```javascript
// API errors are thrown with message
try {
  const result = await api.login(username, password);
} catch (err) {
  error = err.message || 'An unexpected error occurred';
  console.error('Login failed:', err);
}
```

### Styling with Tailwind & DaisyUI

- Use Tailwind utility classes
- DaisyUI components: `btn`, `card`, `alert`, `input`, `navbar`
- Color scheme: `primary` (emerald), `base-100`, `base-200`
- Custom colors in `app.css` with `@theme`

### Authentication Patterns

- Auth state in `$lib/stores/auth.js`
- Check auth in layout `onMount`
- Redirect to `/login` if unauthenticated
- API client auto-redirects on 401

### Environment Variables

```javascript
const API_URL = import.meta.env.VITE_API_URL || '';
```

### LocalStorage

- Only access in browser: check `browser` from `$app/environment`
- Use descriptive keys: `clqms_username`, `clqms_remember`

## Proxy Configuration

API requests to `/api` are proxied to `http://localhost:8000` in dev.

## Important Notes

- No ESLint or Prettier configured yet - add if needed
- No test framework configured yet
- Uses Svelte 5 runes: `$props`, `$state`, `$derived`, `$effect`
- SvelteKit file-based routing with `+page.svelte`, `+layout.svelte`