diff --git a/.cursor/rules/svelte.mdc b/.cursor/rules/svelte.mdc deleted file mode 100644 index 9304b187..00000000 --- a/.cursor/rules/svelte.mdc +++ /dev/null @@ -1,243 +0,0 @@ ---- -globs: apps/web/src/**/* -alwaysApply: false ---- - -You are an expert in Svelte 5, SvelteKit, TypeScript, and modern web development. - -Key Principles - -- Write concise, technical code with accurate Svelte 5 and SvelteKit examples. -- Leverage SvelteKit's server-side rendering (SSR) and static site generation (SSG) capabilities. -- Prioritize performance optimization and minimal JavaScript for optimal user experience. -- Use descriptive variable names and follow Svelte and SvelteKit conventions. -- Organize files using SvelteKit's file-based routing system. - -Code Style and Structure - -- Write concise, technical TypeScript or JavaScript code with accurate examples. -- Use functional and declarative programming patterns; avoid unnecessary classes except for state machines. -- Prefer iteration and modularization over code duplication. -- Structure files: component logic, markup, styles, helpers, types. -- Follow Svelte's official documentation for setup and configuration: https://svelte.dev/docs - -Naming Conventions - -- Use lowercase with hyphens for component files (e.g., `components/auth-form.svelte`). -- Use PascalCase for component names in imports and usage. -- Use camelCase for variables, functions, and props. - -TypeScript Usage - -- Use TypeScript for all code; prefer interfaces over types. -- Avoid enums; use const objects instead. -- Use functional components with TypeScript interfaces for props. -- Enable strict mode in TypeScript for better type safety. - -Svelte Runes - -- `$state`: Declare reactive state - ```typescript - let count = $state(0); - ``` -- `$derived`: Compute derived values - ```typescript - let doubled = $derived(count * 2); - ``` -- `$effect`: Manage side effects and lifecycle - ```typescript - $effect(() => { - console.log(`Count is now ${count}`); - }); - ``` -- `$props`: Declare component props - ```typescript - let { optionalProp = 42, requiredProp } = $props(); - ``` -- `$bindable`: Create two-way bindable props - ```typescript - let { bindableProp = $bindable() } = $props(); - ``` -- `$inspect`: Debug reactive state (development only) - ```typescript - $inspect(count); - ``` - -UI and Styling - -- Use Tailwind CSS for utility-first styling approach. -- Leverage Shadcn components for pre-built, customizable UI elements. -- Import Shadcn components from `#lib/components/ui//index.ts`. -- Organize Tailwind classes using the `cn()` utility from `#lib/utils.ts`. -- Use Svelte's built-in transition and animation features. - -Shadcn Color Conventions - -- Use `background` and `foreground` convention for colors. -- Define CSS variables without color space function: - ```css - --primary: 222.2 47.4% 11.2%; - --primary-foreground: 210 40% 98%; - ``` -- Usage example: - ```svelte -
Hello
- ``` -- Key color variables: - - `--background`, `--foreground`: Default body colors - - `--muted`, `--muted-foreground`: Muted backgrounds - - `--card`, `--card-foreground`: Card backgrounds - - `--popover`, `--popover-foreground`: Popover backgrounds - - `--border`: Default border color - - `--input`: Input border color - - `--primary`, `--primary-foreground`: Primary button colors - - `--secondary`, `--secondary-foreground`: Secondary button colors - - `--accent`, `--accent-foreground`: Accent colors - - `--destructive`, `--destructive-foreground`: Destructive action colors - - `--ring`: Focus ring color - - `--radius`: Border radius for components - -SvelteKit Project Structure - -- Use the recommended SvelteKit project structure: - ``` - - src/ - - lib/ - - routes/ - - app.html - - static/ - - vite.config.ts - ``` - -Component Development - -- Create .svelte files for Svelte components. -- Use .svelte.ts files for component logic and state machines. -- Implement proper component composition and reusability. -- Use Svelte's props for data passing. -- Leverage Svelte's reactive declarations for local state management. - -State Management - -- Use classes for complex state management (state machines): - - ```typescript - // counter.svelte.ts - class Counter { - count = $state(0); - incrementor = $state(1); - - increment() { - this.count += this.incrementor; - } - - resetCount() { - this.count = 0; - } - - resetIncrementor() { - this.incrementor = 1; - } - } - - export const counter = new Counter(); - ``` - -- Use in components: - - ```svelte - - - - ``` - -Routing and Pages - -- Utilize SvelteKit's file-based routing system in the src/routes/ directory. -- Implement dynamic routes using [slug] syntax. -- Use load functions for server-side data fetching and pre-rendering. -- Implement proper error handling with +error.svelte pages. - -Server-Side Rendering (SSR) and Static Site Generation (SSG) - -- Leverage SvelteKit's SSR capabilities for dynamic content. -- Implement SSG for static pages using prerender option. -- Use the adapter-auto for automatic deployment configuration. - -Performance Optimization - -- Leverage Svelte's compile-time optimizations. -- Use `{#key}` blocks to force re-rendering of components when needed. -- Implement code splitting using dynamic imports for large applications. -- Profile and monitor performance using browser developer tools. -- Use `$effect.tracking()` to optimize effect dependencies. -- Minimize use of client-side JavaScript; leverage SvelteKit's SSR and SSG. -- Implement proper lazy loading for images and other assets. - -Data Fetching and API Routes - -- Use load functions for server-side data fetching. -- Implement proper error handling for data fetching operations. -- Create API routes in the src/routes/api/ directory. -- Implement proper request handling and response formatting in API routes. -- Use SvelteKit's hooks for global API middleware. - -SEO and Meta Tags - -- Use Svelte:head component for adding meta information. -- Implement canonical URLs for proper SEO. -- Create reusable SEO components for consistent meta tag management. - -Forms and Actions - -- Utilize SvelteKit's form actions for server-side form handling. -- Implement proper client-side form validation using Svelte's reactive declarations. -- Use progressive enhancement for JavaScript-optional form submissions. - -Internationalization (i18n) with Paraglide.js - -- Use Paraglide.js for internationalization: https://inlang.com/m/gerre34r/library-inlang-paraglideJs -- Install Paraglide.js: `bun add @inlang/paraglide-js` -- Set up language files in the `languages` directory. -- Use the `t` function to translate strings: - - ```svelte - - -

{t('welcome_message')}

- ``` - -- Support multiple languages and RTL layouts. -- Ensure text scaling and font adjustments for accessibility. - -Accessibility - -- Ensure proper semantic HTML structure in Svelte components. -- Implement ARIA attributes where necessary. -- Ensure keyboard navigation support for interactive elements. -- Use Svelte's bind:this for managing focus programmatically. - -Key Conventions - -1. Embrace Svelte's simplicity and avoid over-engineering solutions. -2. Use SvelteKit for full-stack applications with SSR and API routes. -3. Prioritize Web Vitals (LCP, FID, CLS) for performance optimization. -4. Use environment variables for configuration management. -5. Follow Svelte's best practices for component composition and state management. -6. Ensure cross-browser compatibility by testing on multiple platforms. -7. Keep your Svelte and SvelteKit versions up to date. - -Documentation - -- Svelte 5 Runes: https://svelte-5-preview.vercel.app/docs/runes -- Svelte Documentation: https://svelte.dev/docs -- SvelteKit Documentation: https://kit.svelte.dev/docs -- Paraglide.js Documentation: https://inlang.com/m/gerre34r/library-inlang-paraglideJs/usage - -Refer to Svelte, SvelteKit, and Paraglide.js documentation for detailed information on components, internationalization, and best practices. diff --git a/AGENTS.md b/AGENTS.md index d06f06b9..1d9f068d 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -2,7 +2,7 @@ ATLANTIS turns NetFlow captures and CSV imports into queryable aggregate databases, then visualizes them in a web dashboard. -## Repository Map +## Repository map - `tools/netflow-db`: Rust pipeline (`atlantis-netflow-db` crate) for ingestion, aggregation, verification, and analysis-window exports. Native `nfcapd` ingestion uses the pinned `nfdump` fork in `vendor/nfdump`. - `apps/web`: Svelte 5/SvelteKit 3 dashboard and API routes. It reads local SQLite during development and Cloudflare D1 in deployment. @@ -14,7 +14,7 @@ ATLANTIS turns NetFlow captures and CSV imports into queryable aggregate databas - `docs/code`: Architecture and development documentation. - `docs/agent`: Generated plans and analysis artifacts. -## Engineering Contracts +## Engineering contracts - Treat ingestion, storage, API queries, and charts as one data contract. When a stored field or dimension changes, account for every Rust writer and verifier, the local SQLite schema, the Drizzle schema and migrations, TypeScript query code, and focused tests. - A pipeline database is a product bound to its schema, flow selection, result configuration, and logical source membership. Semantic changes produce a fresh product database; never silently mix incompatible results in an existing one. @@ -30,19 +30,13 @@ Reuse the existing chart registries, chart utilities, and shared filter componen ## Verification -- Before completion, run `bun run format`, `bun run lint`, and `bun run typecheck` successfully. +- For code changes, run `bun run format`, `bun run lint`, and `bun run typecheck` successfully. For documentation-only changes, run the applicable formatter check. - Run focused tests for the changed surface: `bun run test:web` for dashboard/API behavior, `bun run test:db` for pipeline behavior, and `bun run test:e2e` for user flows that need browser coverage. - Use `bun run test`, not `bun test`; the latter invokes Bun's test runner instead of the repository's Vitest orchestration. - When editing the landing site, also run `bun run --cwd apps/landing lint` and `bun run build:landing`; the root lint script does not cover `apps/landing`. -## Pull Requests +## Pull requests Use the Conventional Commit style for PR titles. -Every PR description must give a reviewer a fast path to approval: - -- Name the flows to exercise, required setup or test data, and expected results. -- Call out important edge cases, failure states, and business-logic decisions. -- List automated verification and any remaining manual verification. - -Keep this focused on observable behavior and decisions rather than an exhaustive implementation summary. +Include a short human review guide with relevant flows, setup or test data, expected behavior, important edge cases, and decisions needing review. Distinguish automated verification from remaining manual checks.