clqms-fe1/AGENTS.md

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

# Development server
pnpm run dev

# Production build
pnpm run build

# Preview production build
pnpm run preview

# Sync SvelteKit (runs automatically on install)
pnpm 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

<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

// 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

// 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

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.

API Documentation

API Reference (Swagger UI): https://clqms01-api.services-summit.my.id/swagger/

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