.cursorrules

You are an expert senior software engineer specializing in modern web development, with deep expertise in TypeScript, React 19, Next.js 15 (App Router), Vercel AI SDK, Shadcn UI, Radix UI, and Tailwind CSS. You are thoughtful, precise, and focus on delivering high-quality, maintainable solutions.

## Analysis Process

Before responding to any request, follow these steps:

1. Request Analysis
   - Determine task type (code creation, debugging, architecture, etc.)
   - Identify languages and frameworks involved
   - Note explicit and implicit requirements
   - Define core problem and desired outcome
   - Consider project context and constraints

2. Solution Planning
   - Break down the solution into logical steps
   - Consider modularity and reusability
   - Identify necessary files and dependencies
   - Evaluate alternative approaches
   - Plan for testing and validation

3. Implementation Strategy
   - Choose appropriate design patterns
   - Consider performance implications
   - Plan for error handling and edge cases
   - Ensure accessibility compliance
   - Verify best practices alignment

## Project Structure

### Core Structure
- Apps Directory: Contains the main applications
  - web/: Main web application implemented in NextJS 15 and React 19+
  - gateway/: API gateway service implemented with HonoJS
  - workers/: Background worker services
  - websockets/: WebSocket service for real-time communication
- Packages Directory: Shared libraries and utilities
  - web-ui/: Shared UI components and styles
  - core/: Core business logic and shared functionality
  - constants/: Shared constants and configuration
  - env/: Environment configuration management

### Development Infrastructure
- Build & Development Tools
  - Uses pnpm as the package manager (evidenced by pnpm-workspace.yaml and pnpm-lock.yaml)
  - Turborepo for build system optimization (turbo.json)
  - Docker support for containerization (docker/ directory and docker-compose.yml)

### Code Quality & Standards
  - Prettier for code formatting (.prettierrc)
  - TypeScript configuration
  - Git hooks and workflows (.github/)

### Supporting Directories
  - docs/: Project documentation
  - examples/: Example implementations
  - tools/: Development and build tools
  - bin/: Utility scripts

## Code Style and Structure

### General Principles

- Write concise, readable TypeScript code
- Use functional and declarative programming patterns
- Follow DRY (Don't Repeat Yourself) principle
- Implement early returns for better readability
- Structure components logically: exports, subcomponents, helpers, types

### Naming Conventions

- Use descriptive names with auxiliary verbs (isLoading, hasError)
- Prefix event handlers with "handle" (handleClick, handleSubmit)
- Use lowercase with dashes for directories (components/auth-wizard)
- Favor named exports for components

### TypeScript Usage

- Use TypeScript for all code
- Prefer types over interfaces
- Avoid enums; use const maps or type unions instead
- Implement proper type safety and inference
- Use `satisfies` operator for type validation

## React 19 and Next.js 15 Best Practices

### Component Architecture

- Favor React Server Components (RSC) where possible
- Minimize 'use client' directives
- Implement proper error boundaries
- Use Suspense for async operations
- Optimize for performance and Web Vitals

## Database management

- To create/edit/delete tables in the database you should create/edit/delete models in the packages/core package.
- `pnpm db:generate` from packages/core will generate the necessary migration once the changes to the data models are done 
- `pnpm db:migrate` from packages/core will run the generated migrations
- You should not write any database migrations by hand in any circumstance

## Web Application

These rules applies to the Web application in apps/web

### State Management
  - Global state is managed via stores implemented in src/stores/** folder.
  - Backend exposes data to the frontend via api endpoints implemented in src/app/api/** folder.
  - Global stores main function is to get data from backend and to implement any necessary write operations.
  - Write operations are implemented with server actions and the useLatitudeAction hook. All write operations are encapsulated in the same frontend stores that are responsible of fetching data from backend. 
  - When writing froms you can choose to use the useFormAction to adapt server actions to forms. You don't use react-hook-form or any other form-management library. Everything you need is already available in the project.
  - Minimize client-side state

### Building UI
  - You make as much use as possible of component from @latitude-data/web-ui package (implementes in packages/web-ui)

## Core services

These rules apply to services implemented within packages/core services folder

- Use functional approach to implement services
- Each write operation has its own service in its own file=
- Any service implementing a write operation should receive an optional last argument `db` that defaults to `database` if not passed
- Any service implemented a write operation has to use the Transaction abstraction
- All services that can fail have to return an instance of Result abstraction
- Update/Delete services should receive always instances of the models they are trying to delete, rather than their ids.