chore: reorganize and expand cursor rules documentation for AI agents and development standards

.cursorrules

@@ -12,7 +12,7 @@ Omnivore is a complete, open-source read-it-later solution with web, mobile, and
 - Mobile apps (iOS/Android)
 - Browser extensions
 
-## Architecture Rules
+## Core Architecture Principles
 
 ### Monorepo Structure
 
@@ -23,201 +23,50 @@ Omnivore is a complete, open-source read-it-later solution with web, mobile, and
 - Web frontend in `packages/web`
 - API server in `packages/api`
 
-### TypeScript Standards
+### Technology Stack
 
-- Use strict TypeScript configuration
-- Prefer interfaces over types for object shapes
-- Use enums for constants with multiple values
-- Always define return types for functions
-- Use optional chaining and nullish coalescing operators
-- Avoid `any` type - use `unknown` if needed
-- Use proper generic constraints
+- **Backend**: Node.js 22 (migrating to 23 after stabilization), TypeScript, GraphQL
+- **Frontend**: Next.js with App Router, React, TypeScript, Stitches
+- **Database**: PostgreSQL with vector extensions, Redis for caching/queues
+- **Mobile**: Swift/SwiftUI (iOS), Kotlin/Compose (Android)
+- **Testing**: Jest (preferred), Mocha/Chai (legacy - gradually phase out)
 
-### GraphQL API Patterns
+### Development Standards
 
-- Follow GraphQL best practices with proper schema design
-- Use GraphQL Code Generator for type generation
-- Implement proper error handling with GraphQL error types
-- Use DataLoader pattern for N+1 query prevention
-- Implement proper authentication and authorization
-- Use subscriptions for real-time features
-- Follow relay-style pagination for lists
+- Use strict TypeScript configuration throughout
+- Implement comprehensive testing (80% coverage minimum)
+- Follow security best practices (JWT auth, input validation, HTTPS)
+- Use Docker containers for all services
+- Implement proper error handling and logging
+- Follow GraphQL-first API design
+- Maintain cross-platform compatibility
 
-### Database Patterns
+## Detailed Guidelines
 
-- Use migrations for all schema changes
-- Place migrations in `packages/db/migrations/`
-- Use descriptive migration names with timestamps
-- Always include both up and down migrations
-- Use proper indexing for performance
-- Implement soft deletes where appropriate
-- Use database transactions for complex operations
+For comprehensive development guidelines, refer to the organized cursor rules in the `cursor-rules/` directory:
 
-### Frontend (Next.js) Patterns
+- **[Frontend Development](./cursor-rules/frontend-frameworks-cursorrules.md)** - Next.js, React patterns
+- **[Backend Development](./cursor-rules/backend-fullstack-cursorrules.md)** - GraphQL, microservices
+- **[Mobile Development](./cursor-rules/mobile-development-cursorrules.md)** - iOS, Android, extensions
+- **[Database & API](./cursor-rules/database-api-cursorrules.md)** - PostgreSQL, Redis patterns
+- **[Testing](./cursor-rules/testing-cursorrules.md)** - Jest, E2E, coverage standards
+- **[Build Tools](./cursor-rules/build-tools-development-cursorrules.md)** - Lerna, Docker, CI/CD
+- **[Language-Specific](./cursor-rules/language-specific-cursorrules.md)** - TypeScript, Swift, Kotlin
+- **[Security](./cursor-rules/security-cursorrules.md)** - Authentication, data protection
 
-- Use App Router for new features
-- Implement proper SSR/SSG where beneficial
-- Use SWR for data fetching and caching
-- Follow component composition patterns
-- Use Stitches for styling (already in use)
-- Implement proper error boundaries
-- Use TypeScript with proper prop types
-- Follow accessibility best practices
+## AI Agent Guidelines
 
-### Docker and Containerization
+For AI assistants and automated tools working on this codebase, refer to [AGENTS.md](./AGENTS.md) for:
 
-- Each service should have its own Dockerfile
-- Use multi-stage builds for production images
-- Implement proper health checks
-- Use docker-compose for local development
-- Follow security best practices in containers
-- Use .dockerignore files appropriately
+- Expected behaviors and contribution patterns
+- Code quality standards and testing requirements
+- Security considerations and best practices
+- Communication protocols and workflow guidelines
 
-### Testing Standards
+## Critical Considerations
 
-- Write unit tests for all business logic
-- Use integration tests for API endpoints
-- Implement E2E tests for critical user flows
-- Use proper mocking for external dependencies
-- Maintain test coverage above 80%
-- Use descriptive test names and organize in suites
+**Multi-Platform Impact**: This is a complex application with multiple platforms. Always consider the impact of changes across web, mobile, and browser extension clients. Prioritize user experience and data consistency across all platforms.
 
-### Mobile Development
+**Migration Strategy**: Gradually migrate from Mocha/Chai to Jest for testing. Use Node.js 22 for stability, plan migration to 23 after project stabilization.
 
-- iOS: Use Swift with SwiftUI
-- Android: Use Kotlin with Jetpack Compose
-- Share GraphQL schemas between platforms
-- Implement proper offline capabilities
-- Use platform-specific UI patterns
-- Handle deep linking appropriately
-
-### Browser Extension Development
-
-- Support Chrome, Firefox, Safari, and Edge
-- Use Manifest V3 where applicable
-- Implement proper content security policies
-- Handle permissions appropriately
-- Use background scripts efficiently
-- Implement proper error handling
-
-### Code Quality
-
-- Use ESLint with TypeScript support
-- Follow Prettier formatting
-- Use consistent naming conventions
-- Implement proper logging
-- Use environment variables for configuration
-- Follow SOLID principles
-- Implement proper error handling
-
-### Performance Considerations
-
-- Implement proper caching strategies
-- Use database indexes appropriately
-- Optimize bundle sizes for web and mobile
-- Implement lazy loading where beneficial
-- Use CDN for static assets
-- Monitor performance metrics
-
-### Security Guidelines
-
-- Implement proper authentication (JWT)
-- Use HTTPS everywhere
-- Validate all inputs
-- Implement proper CORS policies
-- Use environment variables for secrets
-- Regular security audits
-- Implement rate limiting
-
-### API Design
-
-- Follow RESTful principles for REST endpoints
-- Use proper HTTP status codes
-- Implement proper versioning
-- Use consistent error response formats
-- Implement proper pagination
-- Use proper HTTP methods
-- Document all APIs
-
-### Documentation Standards
-
-- Update README.md when adding new features
-- Document all environment variables
-- Maintain API documentation
-- Include setup instructions for new developers
-- Document deployment procedures
-- Use inline comments for complex logic
-
-### Development Workflow
-
-- Use feature branches for development
-- Implement proper CI/CD pipelines
-- Use semantic versioning
-- Write meaningful commit messages
-- Use pull request templates
-- Implement proper code review processes
-
-### Environment Management
-
-- Use different configurations for dev/staging/prod
-- Implement proper secrets management
-- Use environment-specific docker-compose files
-- Implement proper logging levels
-- Use monitoring and alerting
-
-### Content Processing
-
-- Implement proper content extraction
-- Use readability algorithms for article parsing
-- Handle different content types (PDF, articles, etc.)
-- Implement proper error handling for content fetching
-- Use queues for background processing
-- Implement retry mechanisms
-
-### User Experience
-
-- Implement proper loading states
-- Use optimistic updates where appropriate
-- Handle offline scenarios gracefully
-- Implement proper error messages
-- Use consistent UI patterns
-- Implement proper keyboard navigation
-
-## File-specific Rules
-
-### GraphQL Schema Files
-
-- Use descriptive field names
-- Implement proper type relationships
-- Use unions for polymorphic types
-- Document schema with descriptions
-- Follow GraphQL naming conventions
-
-### React Components
-
-- Use functional components with hooks
-- Implement proper prop validation
-- Use consistent naming (PascalCase)
-- Keep components focused and small
-- Use proper state management
-- Implement proper cleanup in useEffect
-
-### API Handlers
-
-- Implement proper error handling
-- Use proper HTTP status codes
-- Validate input parameters
-- Implement proper logging
-- Use proper middleware patterns
-- Handle edge cases gracefully
-
-### Database Models
-
-- Use proper relationships
-- Implement proper validations
-- Use descriptive field names
-- Implement proper indexes
-- Use proper data types
-- Handle cascading properly
-
-Remember: This is a complex application with multiple platforms. Always consider the impact of changes across web, mobile, and browser extension clients. Prioritize user experience and data consistency across all platforms.
+**Performance**: Implement proper caching, optimize bundle sizes, use appropriate database indexing, and monitor performance metrics across all platforms.

AGENTS.md

@@ -0,0 +1,399 @@
+# Omnivore AI Agents Guidelines
+
+This document outlines the expected behaviors, capabilities, and contribution patterns for AI agents working on the Omnivore codebase. It serves as a comprehensive guide for AI assistants, automated tools, and external agents contributing to the project.
+
+## Table of Contents
+
+- [Agent Types and Roles](#agent-types-and-roles)
+- [Core Principles](#core-principles)
+- [Development Guidelines](#development-guidelines)
+- [Code Quality Standards](#code-quality-standards)
+- [Testing Requirements](#testing-requirements)
+- [Documentation Standards](#documentation-standards)
+- [Security Considerations](#security-considerations)
+- [Communication Protocols](#communication-protocols)
+- [Contribution Workflow](#contribution-workflow)
+- [Troubleshooting and Support](#troubleshooting-and-support)
+
+## Agent Types and Roles
+
+### Code Generation Agents
+
+- **Primary Role**: Generate new code, components, and features
+- **Responsibilities**:
+  - Follow established patterns and architecture
+  - Implement proper error handling and validation
+  - Generate comprehensive tests alongside code
+  - Ensure cross-platform compatibility considerations
+
+### Code Review Agents
+
+- **Primary Role**: Review pull requests and suggest improvements
+- **Responsibilities**:
+  - Verify adherence to coding standards
+  - Check for security vulnerabilities
+  - Validate test coverage
+  - Ensure documentation completeness
+
+### Refactoring Agents
+
+- **Primary Role**: Improve existing code quality and structure
+- **Responsibilities**:
+  - Maintain backward compatibility
+  - Preserve existing functionality
+  - Update related documentation
+  - Migrate tests appropriately
+
+### Documentation Agents
+
+- **Primary Role**: Create and maintain project documentation
+- **Responsibilities**:
+  - Keep documentation current with code changes
+  - Ensure clarity and completeness
+  - Maintain consistent formatting
+  - Update API documentation automatically
+
+## Core Principles
+
+### 1. Truth and Accuracy Over Appeasement
+
+- Pursue technical accuracy using first principles
+- Provide honest assessments of code quality and architecture
+- Suggest pragmatic solutions over popular ones
+- Challenge assumptions when necessary
+
+### 2. Elegance and Simplicity
+
+- Favor simple, readable solutions over complex ones
+- Prioritize maintainability and clarity
+- Use appropriate abstractions without over-engineering
+- Follow the principle of least surprise
+
+### 3. Context Awareness
+
+- Understand the monorepo structure and service interactions
+- Consider impact across web, mobile, and browser extension clients
+- Respect existing architectural decisions
+- Maintain consistency with established patterns
+
+### 4. Comprehensive Understanding
+
+- Thoroughly analyze requirements before implementation
+- Consider edge cases and error scenarios
+- Understand the full scope of changes needed
+- Trace dependencies and impacts across the codebase
+
+## Development Guidelines
+
+### Project Structure Awareness
+
+```
+omnivore/
+├── packages/          # Core services and libraries
+│   ├── api/          # GraphQL API backend
+│   ├── web/          # Next.js frontend
+│   ├── db/           # Database schemas and migrations
+│   └── shared/       # Shared utilities
+├── pkg/              # Additional packages
+├── apple/            # iOS application
+├── android/          # Android application
+└── cursor-rules/     # AI development guidelines
+```
+
+### Technology Stack Considerations
+
+- **Backend**: Node.js 22 (migrating to 23), TypeScript, GraphQL
+- **Frontend**: Next.js, React, TypeScript, Stitches
+- **Database**: PostgreSQL with vector extensions, Redis
+- **Mobile**: Swift/SwiftUI (iOS), Kotlin/Compose (Android)
+- **Testing**: Jest (preferred), Mocha/Chai (legacy - phase out)
+
+### Architecture Patterns
+
+- **Microservices**: Each service in separate package
+- **GraphQL First**: Use GraphQL for API design
+- **Type Safety**: Strict TypeScript throughout
+- **Monorepo**: Lerna-managed workspace
+- **Container-First**: Docker for all services
+
+## Code Quality Standards
+
+### TypeScript Requirements
+
+```typescript
+// ✅ Good: Proper typing with interfaces
+interface UserPreferences {
+  theme: 'light' | 'dark'
+  notifications: boolean
+  readingSpeed: number
+}
+
+// ❌ Avoid: Using any type
+function processData(data: any): any {
+  return data
+}
+
+// ✅ Good: Use unknown and type guards
+function processData(data: unknown): ProcessedData {
+  if (isValidData(data)) {
+    return transformData(data)
+  }
+  throw new Error('Invalid data format')
+}
+```
+
+### Error Handling Patterns
+
+```typescript
+// ✅ GraphQL Error Handling
+export const createArticle = async (
+  parent: unknown,
+  args: CreateArticleInput,
+  ctx: ResolverContext
+): Promise<CreateArticleResult> => {
+  try {
+    // Implementation
+    return { success: true, article }
+  } catch (error) {
+    return {
+      success: false,
+      errorCode: ErrorCode.INTERNAL_ERROR,
+      errorMessage: 'Failed to create article',
+    }
+  }
+}
+```
+
+### Database Migration Patterns
+
+```sql
+-- migrations/2024_01_15_123456_add_user_preferences.sql
+-- UP
+ALTER TABLE users ADD COLUMN preferences JSONB DEFAULT '{}';
+CREATE INDEX idx_users_preferences ON users USING GIN (preferences);
+
+-- DOWN
+DROP INDEX IF EXISTS idx_users_preferences;
+ALTER TABLE users DROP COLUMN IF EXISTS preferences;
+```
+
+## Testing Requirements
+
+### Test Coverage Standards
+
+- **Minimum Coverage**: 80% for all new code
+- **Critical Paths**: 95% coverage for authentication, payment, data integrity
+- **Unit Tests**: All business logic functions
+- **Integration Tests**: All API endpoints
+- **E2E Tests**: Critical user journeys
+
+### Testing Patterns
+
+```typescript
+// ✅ Good: Descriptive test structure
+describe('ArticleService', () => {
+  describe('createArticle', () => {
+    it('should create article with valid URL and return success', async () => {
+      // Arrange
+      const validUrl = 'https://example.com/article'
+      const mockUser = createMockUser()
+
+      // Act
+      const result = await articleService.createArticle(validUrl, mockUser)
+
+      // Assert
+      expect(result.success).toBe(true)
+      expect(result.article).toBeDefined()
+      expect(result.article.url).toBe(validUrl)
+    })
+
+    it('should return error for invalid URL format', async () => {
+      // Test implementation
+    })
+  })
+})
+```
+
+### Migration from Mocha to Jest
+
+When encountering Mocha/Chai tests:
+
+1. Assess complexity of migration
+2. If simple, migrate to Jest
+3. If complex, add note for future migration
+4. Never break existing functionality
+
+## Documentation Standards
+
+### Code Documentation
+
+```typescript
+/**
+ * Processes article content and extracts metadata
+ * @param url - The article URL to process
+ * @param options - Processing options
+ * @returns Promise resolving to processed article data
+ * @throws {ValidationError} When URL format is invalid
+ * @throws {NetworkError} When article cannot be fetched
+ */
+export async function processArticle(
+  url: string,
+  options: ProcessingOptions = {}
+): Promise<ProcessedArticle> {
+  // Implementation
+}
+```
+
+### API Documentation
+
+- Update GraphQL schema descriptions
+- Maintain OpenAPI specs for REST endpoints
+- Include example requests/responses
+- Document error codes and meanings
+
+### README Updates
+
+When adding features:
+
+1. Update relevant README.md files
+2. Include setup instructions
+3. Document new environment variables
+4. Add troubleshooting information
+
+## Security Considerations
+
+### Input Validation
+
+```typescript
+// ✅ Always validate inputs
+export const validateUrl = (url: string): boolean => {
+  try {
+    const parsed = new URL(url)
+    return ['http:', 'https:'].includes(parsed.protocol)
+  } catch {
+    return false
+  }
+}
+```
+
+### Authentication Patterns
+
+- Always verify JWT tokens
+- Implement proper RBAC checks
+- Use parameterized queries
+- Sanitize user inputs
+- Log security events
+
+### Secrets Management
+
+- Never commit secrets to version control
+- Use environment variables
+- Implement proper rotation
+- Use encrypted storage for sensitive data
+
+## Communication Protocols
+
+### Pull Request Guidelines
+
+1. **Title**: Clear, descriptive summary
+2. **Description**: Context, changes, and impact
+3. **Testing**: Evidence of testing performed
+4. **Documentation**: Updates to relevant docs
+5. **Breaking Changes**: Clear indication if any
+
+### Commit Message Format
+
+```
+type(scope): brief description
+
+Detailed explanation of changes and reasoning.
+
+Fixes #issue-number
+```
+
+Types: feat, fix, docs, style, refactor, test, chore
+
+### Issue Reporting
+
+When encountering issues:
+
+1. Provide complete context
+2. Include reproduction steps
+3. Suggest potential solutions
+4. Reference related code sections
+
+## Contribution Workflow
+
+### Before Starting Work
+
+1. Review cursor rules and this agents guide
+2. Understand the specific requirements
+3. Plan the implementation approach
+4. Consider cross-platform impacts
+
+### During Development
+
+1. Follow established patterns
+2. Write tests alongside code
+3. Update documentation as needed
+4. Consider backward compatibility
+
+### Before Submitting
+
+1. Run full test suite
+2. Check linting and formatting
+3. Verify documentation updates
+4. Test across affected platforms
+
+### Code Review Process
+
+1. Address all feedback thoroughly
+2. Explain reasoning for design decisions
+3. Update tests based on review comments
+4. Ensure CI/CD pipeline passes
+
+## Troubleshooting and Support
+
+### Common Issues and Solutions
+
+#### Build Failures
+
+- Check Node.js version (should be 22)
+- Verify all dependencies installed
+- Clear node_modules and reinstall
+- Check TypeScript compilation errors
+
+#### Test Failures
+
+- Run tests in isolation
+- Check for async/await issues
+- Verify mock configurations
+- Ensure test data cleanup
+
+#### Database Issues
+
+- Check migration status
+- Verify connection strings
+- Review query performance
+- Check index usage
+
+### Getting Help
+
+1. **Documentation**: Check existing docs first
+2. **Code Search**: Look for similar implementations
+3. **Issue Tracking**: Search existing issues
+4. **Team Communication**: Reach out to maintainers
+
+### Performance Considerations
+
+- Monitor bundle sizes
+- Optimize database queries
+- Implement proper caching
+- Use lazy loading appropriately
+- Profile critical paths
+
+## Conclusion
+
+This guide serves as a living document for AI agents contributing to Omnivore. It should be updated as the project evolves and new patterns emerge. The goal is to maintain high code quality, security, and user experience across all platforms while enabling efficient AI-assisted development.
+
+Remember: The ultimate goal is creating a robust, maintainable, and user-friendly read-it-later solution that serves users across web, mobile, and browser extension platforms.

cursor-rules/README.md

@@ -0,0 +1,93 @@
+# Omnivore Cursor Rules
+
+This directory contains organized cursor rules for the Omnivore project, structured according to development domains and technologies.
+
+## Why Cursor Rules?
+
+Cursor rules provide AI-powered development assistance by establishing project-specific guidelines, patterns, and best practices. These rules help ensure consistency across the codebase and guide AI assistants in making contextually appropriate suggestions.
+
+## Table of Contents
+
+- [Rules](#rules)
+  - [Frontend Frameworks and Libraries](#frontend-frameworks-and-libraries)
+  - [Backend and Full-Stack](#backend-and-full-stack)
+  - [Mobile Development](#mobile-development)
+  - [Database and API](#database-and-api)
+  - [Testing](#testing)
+  - [Build Tools and Development](#build-tools-and-development)
+  - [Language-Specific](#language-specific)
+  - [Security](#security)
+- [How to Use](#how-to-use)
+- [Contributing](#contributing)
+
+## Rules
+
+### Frontend Frameworks and Libraries
+
+- **[frontend-frameworks-cursorrules.md](./frontend-frameworks-cursorrules.md)** - Next.js, React, and frontend development patterns for the Omnivore web application
+
+### Backend and Full-Stack
+
+- **[backend-fullstack-cursorrules.md](./backend-fullstack-cursorrules.md)** - GraphQL API patterns, microservices architecture, and content processing rules
+
+### Mobile Development
+
+- **[mobile-development-cursorrules.md](./mobile-development-cursorrules.md)** - iOS (Swift/SwiftUI), Android (Kotlin/Compose), and browser extension development guidelines
+
+### Database and API
+
+- **[database-api-cursorrules.md](./database-api-cursorrules.md)** - PostgreSQL, Redis, database migrations, and data consistency patterns
+
+### Testing
+
+- **[testing-cursorrules.md](./testing-cursorrules.md)** - Jest (preferred), Mocha/Chai (legacy), E2E testing, and testing patterns
+
+### Build Tools and Development
+
+- **[build-tools-development-cursorrules.md](./build-tools-development-cursorrules.md)** - Lerna monorepo, Docker, TypeScript configuration, and development workflow
+
+### Language-Specific
+
+- **[language-specific-cursorrules.md](./language-specific-cursorrules.md)** - TypeScript, Node.js, Swift, Kotlin, JavaScript, and SQL coding standards
+
+### Security
+
+- **[security-cursorrules.md](./security-cursorrules.md)** - Authentication, data security, API security, and container security guidelines
+
+## How to Use
+
+1. **Main Rules**: The root `.cursorrules` file contains the core project overview and architecture rules
+2. **Categorized Rules**: Individual files in this directory provide detailed guidelines for specific domains
+3. **AI Integration**: These rules are automatically used by Cursor AI to provide contextual assistance
+4. **Reference**: Use these files as reference when developing features or reviewing code
+
+## Contributing
+
+When adding new rules or updating existing ones:
+
+1. **Categorization**: Place rules in the most appropriate category file
+2. **Consistency**: Maintain consistent formatting and structure across files
+3. **Documentation**: Provide clear explanations and context for complex rules
+4. **Best Practices**: Focus on project-specific patterns and architectural decisions
+5. **Examples**: Include examples where helpful for clarity
+
+### Guidelines for Rule Creation
+
+- **Specificity**: Focus on Omnivore-specific patterns rather than general coding practices
+- **Context**: Provide context about the monorepo structure and service interactions
+- **Practicality**: Ensure rules are actionable and can be followed by developers
+- **Maintenance**: Keep rules up-to-date with the current codebase and architecture
+
+## Project Context
+
+Omnivore is a complete, open-source read-it-later solution with:
+
+- GraphQL API backend (Node.js/TypeScript)
+- Next.js frontend with TypeScript
+- PostgreSQL database with vector extensions
+- Redis for caching and queues
+- Microservices for content processing
+- Mobile apps (iOS/Android)
+- Browser extensions
+
+These rules help maintain consistency across all platforms and ensure high-quality development practices throughout the ecosystem.

cursor-rules/backend-fullstack-cursorrules.md

@@ -0,0 +1,55 @@
+# Backend and Full-Stack - Cursor Rules
+
+## GraphQL API Patterns
+
+- Follow GraphQL best practices with proper schema design
+- Use GraphQL Code Generator for type generation
+- Implement proper error handling with GraphQL error types
+- Use DataLoader pattern for N+1 query prevention
+- Implement proper authentication and authorization
+- Use subscriptions for real-time features
+- Follow relay-style pagination for lists
+
+## API Design
+
+- Follow RESTful principles for REST endpoints
+- Use proper HTTP status codes
+- Implement proper versioning
+- Use consistent error response formats
+- Implement proper pagination
+- Use proper HTTP methods
+- Document all APIs
+
+## API Handlers
+
+- Implement proper error handling
+- Use proper HTTP status codes
+- Validate input parameters
+- Implement proper logging
+- Use proper middleware patterns
+- Handle edge cases gracefully
+
+## GraphQL Schema Files
+
+- Use descriptive field names
+- Implement proper type relationships
+- Use unions for polymorphic types
+- Document schema with descriptions
+- Follow GraphQL naming conventions
+
+## Content Processing
+
+- Implement proper content extraction
+- Use readability algorithms for article parsing
+- Handle different content types (PDF, articles, etc.)
+- Implement proper error handling for content fetching
+- Use queues for background processing
+- Implement retry mechanisms
+
+## Microservices Architecture
+
+- Each service should be in its own package under `packages/` or `pkg/`
+- Shared utilities should be in `packages/utils`
+- Use proper inter-service communication patterns
+- Implement proper service discovery
+- Handle service failures gracefully

cursor-rules/build-tools-development-cursorrules.md

@@ -0,0 +1,59 @@
+# Build Tools and Development - Cursor Rules
+
+## Monorepo Management
+
+- Use Lerna for package management across the monorepo
+- Each service should be in its own package under `packages/` or `pkg/`
+- Use workspace dependencies appropriately
+- Implement proper build ordering
+- Use consistent package.json structures
+
+## Docker and Containerization
+
+- Each service should have its own Dockerfile
+- Use multi-stage builds for production images
+- Implement proper health checks
+- Use docker-compose for local development
+- Follow security best practices in containers
+- Use .dockerignore files appropriately
+
+## TypeScript Configuration
+
+- Use strict TypeScript configuration
+- Extend from base tsconfig.json
+- Use proper module resolution
+- Configure path mapping for imports
+- Use composite projects for monorepo builds
+
+## Code Quality Tools
+
+- Use ESLint with TypeScript support
+- Follow Prettier formatting
+- Use consistent naming conventions
+- Implement proper logging
+- Use environment variables for configuration
+
+## Development Workflow
+
+- Use feature branches for development
+- Implement proper CI/CD pipelines
+- Use semantic versioning
+- Write meaningful commit messages
+- Use pull request templates
+- Implement proper code review processes
+
+## Environment Management
+
+- Use different configurations for dev/staging/prod
+- Implement proper secrets management
+- Use environment-specific docker-compose files
+- Implement proper logging levels
+- Use monitoring and alerting
+
+## Performance Monitoring
+
+- Implement proper caching strategies
+- Monitor build times and optimize
+- Use proper bundling strategies
+- Implement performance metrics collection
+- Monitor application performance in production

cursor-rules/database-api-cursorrules.md

@@ -0,0 +1,44 @@
+# Database and API - Cursor Rules
+
+## Database Patterns
+
+- Use migrations for all schema changes
+- Place migrations in `packages/db/migrations/`
+- Use descriptive migration names with timestamps
+- Always include both up and down migrations
+- Use proper indexing for performance
+- Implement soft deletes where appropriate
+- Use database transactions for complex operations
+
+## Database Models
+
+- Use proper relationships
+- Implement proper validations
+- Use descriptive field names
+- Implement proper indexes
+- Use proper data types
+- Handle cascading properly
+
+## PostgreSQL Specific
+
+- Use vector extensions for search functionality
+- Implement proper connection pooling
+- Use prepared statements for security
+- Optimize queries with proper indexing
+- Use database-specific features appropriately
+
+## Redis Patterns
+
+- Use Redis for caching and queues
+- Implement proper cache invalidation strategies
+- Use appropriate data structures (strings, hashes, sets, etc.)
+- Set proper TTL values for cached data
+- Handle Redis connection failures gracefully
+
+## Data Consistency
+
+- Implement proper ACID transactions where needed
+- Use proper isolation levels
+- Handle concurrent access appropriately
+- Implement proper data validation
+- Use database constraints effectively

cursor-rules/frontend-frameworks-cursorrules.md

@@ -0,0 +1,37 @@
+# Frontend Frameworks and Libraries - Cursor Rules
+
+## Next.js Frontend Patterns
+
+- Use App Router for new features
+- Implement proper SSR/SSG where beneficial
+- Use SWR for data fetching and caching
+- Follow component composition patterns
+- Use Stitches for styling (already in use)
+- Implement proper error boundaries
+- Use TypeScript with proper prop types
+- Follow accessibility best practices
+
+## React Components
+
+- Use functional components with hooks
+- Implement proper prop validation
+- Use consistent naming (PascalCase)
+- Keep components focused and small
+- Use proper state management
+- Implement proper cleanup in useEffect
+
+## User Experience Guidelines
+
+- Implement proper loading states
+- Use optimistic updates where appropriate
+- Handle offline scenarios gracefully
+- Implement proper error messages
+- Use consistent UI patterns
+- Implement proper keyboard navigation
+
+## Performance Considerations
+
+- Optimize bundle sizes for web
+- Implement lazy loading where beneficial
+- Use CDN for static assets
+- Monitor performance metrics

cursor-rules/language-specific-cursorrules.md

@@ -0,0 +1,56 @@
+# Language-Specific - Cursor Rules
+
+## TypeScript Standards
+
+- Use strict TypeScript configuration
+- Prefer interfaces over types for object shapes
+- Use enums for constants with multiple values
+- Always define return types for functions
+- Use optional chaining and nullish coalescing operators
+- Avoid `any` type - use `unknown` if needed
+- Use proper generic constraints
+
+## Node.js Patterns
+
+- Use Node.js version 22 for stability (migrate to 23 after stabilization)
+- Implement proper error handling with try-catch blocks
+- Use async/await over callbacks and promises chains
+- Implement proper stream handling
+- Use proper module patterns (ES modules)
+- Handle process signals appropriately
+
+## Swift (iOS)
+
+- Use SwiftUI for modern iOS development
+- Follow Swift naming conventions
+- Use proper optionals handling
+- Implement proper error handling with Result types
+- Use Combine for reactive programming
+- Follow iOS Human Interface Guidelines
+
+## Kotlin (Android)
+
+- Use Jetpack Compose for modern Android development
+- Follow Kotlin coding conventions
+- Use proper null safety features
+- Implement proper coroutines for async operations
+- Use proper dependency injection patterns
+- Follow Material Design guidelines
+
+## JavaScript/JSX
+
+- Use modern JavaScript features (ES2020+)
+- Prefer const over let, avoid var
+- Use proper destructuring patterns
+- Implement proper error boundaries in React
+- Use proper event handling patterns
+- Follow functional programming principles where appropriate
+
+## SQL
+
+- Use descriptive table and column names
+- Implement proper foreign key relationships
+- Use appropriate data types
+- Create proper indexes for performance
+- Use transactions for data consistency
+- Write readable, well-formatted queries

cursor-rules/mobile-development-cursorrules.md

@@ -0,0 +1,41 @@
+# Mobile Development - Cursor Rules
+
+## iOS Development
+
+- Use Swift with SwiftUI
+- Share GraphQL schemas between platforms
+- Implement proper offline capabilities
+- Use platform-specific UI patterns
+- Handle deep linking appropriately
+
+## Android Development
+
+- Use Kotlin with Jetpack Compose
+- Share GraphQL schemas between platforms
+- Implement proper offline capabilities
+- Use platform-specific UI patterns
+- Handle deep linking appropriately
+
+## Cross-Platform Considerations
+
+- Share GraphQL schemas between platforms
+- Maintain consistent data models
+- Implement proper error handling across platforms
+- Use platform-specific UI/UX patterns
+- Handle offline scenarios consistently
+
+## Browser Extension Development
+
+- Support Chrome, Firefox, Safari, and Edge
+- Use Manifest V3 where applicable
+- Implement proper content security policies
+- Handle permissions appropriately
+- Use background scripts efficiently
+- Implement proper error handling
+
+## Performance Optimization
+
+- Optimize bundle sizes for mobile
+- Implement proper caching strategies
+- Use lazy loading where beneficial
+- Monitor performance metrics on mobile devices

cursor-rules/security-cursorrules.md

@@ -0,0 +1,55 @@
+# Security - Cursor Rules
+
+## Authentication and Authorization
+
+- Implement proper authentication (JWT)
+- Use secure session management
+- Implement proper role-based access control
+- Validate user permissions on every request
+- Use secure token storage practices
+- Implement proper logout functionality
+
+## Data Security
+
+- Use HTTPS everywhere
+- Validate all inputs server-side
+- Implement proper SQL injection prevention
+- Use parameterized queries
+- Sanitize user-generated content
+- Implement proper XSS prevention
+
+## API Security
+
+- Implement proper CORS policies
+- Use rate limiting to prevent abuse
+- Implement proper API versioning
+- Validate request signatures where appropriate
+- Use proper error messages (don't leak sensitive info)
+- Implement request/response logging for audit
+
+## Secrets Management
+
+- Use environment variables for secrets
+- Never commit secrets to version control
+- Use proper secrets rotation
+- Implement proper access controls for secrets
+- Use encrypted storage for sensitive data
+- Regular security audits of dependencies
+
+## Container Security
+
+- Use minimal base images
+- Run containers as non-root users
+- Implement proper network segmentation
+- Use security scanning for container images
+- Keep base images updated
+- Implement proper secrets management in containers
+
+## Browser Extension Security
+
+- Implement proper content security policies
+- Handle permissions appropriately
+- Validate all external communications
+- Use secure storage for sensitive data
+- Implement proper sandboxing
+- Regular security reviews of extension code

cursor-rules/testing-cursorrules.md

@@ -0,0 +1,49 @@
+# Testing - Cursor Rules
+
+## Testing Standards
+
+- Write unit tests for all business logic
+- Use integration tests for API endpoints
+- Implement E2E tests for critical user flows
+- Use proper mocking for external dependencies
+- Maintain test coverage above 80%
+- Use descriptive test names and organize in suites
+
+## Jest Configuration (Preferred)
+
+- Use Jest for unit and integration testing
+- Configure with TypeScript support
+- Use proper setup and teardown procedures
+- Implement proper test isolation
+- Use Jest's built-in mocking capabilities
+
+## Mocha/Chai (Legacy - Gradually Phase Out)
+
+- Existing tests may use Mocha and Chai
+- When refactoring, prefer migrating to Jest
+- Maintain existing test functionality during migration
+- Use consistent assertion styles
+
+## Testing Patterns
+
+- Test business logic independently of framework code
+- Use proper test doubles (mocks, stubs, spies)
+- Test error conditions and edge cases
+- Implement proper async testing patterns
+- Use property-based testing where appropriate
+
+## Test Organization
+
+- Place tests adjacent to source code or in dedicated test directories
+- Use consistent naming conventions (_.test.ts, _.spec.ts)
+- Group related tests in describe blocks
+- Use proper test lifecycle hooks (beforeEach, afterEach)
+- Keep tests focused and independent
+
+## End-to-End Testing
+
+- Use Cypress for E2E testing
+- Test critical user journeys
+- Use proper page object patterns
+- Implement proper test data management
+- Handle async operations appropriately