Spaces:
Paused
Paused
| alwaysApply: true | |
| # Suna AI Worker Project - Cursor Rules | |
| ## Project Overview | |
| Suna is an open-source generalist AI Worker with a full-stack architecture: | |
| - **Frontend**: Next.js 15+ with TypeScript, Tailwind CSS, Radix UI, React Query | |
| - **Backend**: Python 3.11+ with FastAPI, Supabase, Redis, LiteLLM, Dramatiq | |
| - **Agent System**: Isolated Docker environments with comprehensive tool execution | |
| - **Database**: Supabase for persistence, authentication, real-time features, and RLS | |
| ## Architecture Components | |
| ### Core Stack | |
| - **Frontend**: Next.js App Router + TypeScript + Tailwind + Radix UI | |
| - **Backend**: FastAPI + Supabase + Redis + LiteLLM + Dramatiq workers | |
| - **Database**: PostgreSQL via Supabase with Row Level Security | |
| - **Agent Runtime**: Docker containers with browser automation, code interpreter | |
| - **Authentication**: Supabase Auth with JWT validation | |
| - **Monitoring**: Langfuse tracing, Sentry error tracking, Prometheus metrics | |
| ### File Organization | |
| ```txt | |
| project/ | |
| ├── frontend/ # Next.js application | |
| │ └── src/ | |
| │ ├── app/ # Next.js app router pages | |
| │ ├── components/ # Reusable React components | |
| │ ├── hooks/ # Custom React hooks | |
| │ ├── lib/ # Utilities and configurations | |
| │ ├── providers/ # Context providers | |
| │ └── contexts/ # React contexts | |
| ├── backend/ # Python FastAPI backend | |
| │ ├── agent/ # AI Worker core implementation | |
| │ ├── services/ # Business logic services | |
| │ ├── utils/ # Shared utilities | |
| │ ├── supabase/ # Database migrations & config | |
| │ ├── tools/ # Agent tool implementations | |
| │ ├── auth/ # Authentication logic | |
| │ ├── triggers/ # Event-driven triggers | |
| │ └── api.py # Main FastAPI application | |
| └── docs/ # Documentation | |
| ``` | |
| ## Development Principles | |
| ### Code Quality Standards | |
| - **Type Safety**: Strict TypeScript frontend, comprehensive Python type hints | |
| - **Error Handling**: Structured error responses, proper exception handling | |
| - **Logging**: Structured logging with context throughout the stack | |
| - **Testing**: Unit tests for core logic, integration tests for APIs | |
| - **Security**: Input validation, authentication, encryption for sensitive data | |
| ### Performance Guidelines | |
| - **Frontend**: Code splitting, lazy loading, optimized bundle size | |
| - **Backend**: Async/await patterns, connection pooling, Redis caching | |
| - **Database**: Proper indexing, query optimization, RLS policies | |
| - **Agent**: Timeout handling, resource limits, sandbox isolation | |
| ### Integration Patterns | |
| - **LLM Integration**: LiteLLM for multi-provider support, structured prompts | |
| - **Tool System**: Dual schema decorators (OpenAPI + XML), consistent ToolResult | |
| - **Real-time**: Supabase subscriptions for live updates | |
| ## Key Technologies | |
| ### Frontend Dependencies | |
| - Next.js 15+, React 18+, TypeScript 5+ | |
| - @tanstack/react-query, @supabase/supabase-js | |
| - @radix-ui components, @tailwindcss/typography | |
| - @hookform/resolvers, react-hook-form | |
| ### Backend Dependencies | |
| - FastAPI 0.115+, Python 3.11+ | |
| - Supabase 2.17+, Redis 5.2+, LiteLLM 1.72+ | |
| - Dramatiq 1.18+, Pydantic for validation | |
| - Sentry, Langfuse, Prometheus for observability | |
| ## Advanced Patterns | |
| ### Agent System Architecture | |
| - **Versioning**: Multiple agent versions with `agent_versions` table | |
| - **Configuration**: JSONB config storage with validation | |
| - **Workflows**: Step-by-step execution with `agent_workflows` | |
| - **Triggers**: Scheduled and event-based automation | |
| - **Builder Tools**: Dynamic agent creation and management | |
| ### Security & Authentication | |
| - **JWT Validation**: Supabase token verification without signature check | |
| - **Row Level Security**: Database-level access control | |
| - **Credential Encryption**: Secure storage of sensitive API keys | |
| - **Input Validation**: Pydantic models for all user inputs | |
| ### Database Patterns | |
| - **Migrations**: Idempotent SQL with proper error handling | |
| - **Indexing**: Foreign keys and query optimization | |
| - **Triggers**: Automated timestamp management | |
| - **Enums**: Safe enum creation with duplicate handling | |
| ## Development Workflow | |
| ### Environment Setup | |
| - Use `mise.toml` for tool version management | |
| - Docker Compose for local development stack | |
| - Environment-specific configurations (LOCAL/STAGING/PRODUCTION) | |
| ### Code Standards | |
| - Follow established naming conventions | |
| - Implement proper error boundaries | |
| - Use consistent logging patterns | |
| - Handle loading and error states | |
| ### Testing Strategy | |
| - Unit tests for business logic | |
| - Integration tests for API endpoints | |
| - E2E tests for critical user flows | |
| - Performance testing for agent execution | |
| ## When in Doubt | |
| - Follow existing patterns in the codebase | |
| - Check similar implementations for guidance | |
| - Use established error handling and logging | |
| - Prioritize type safety and security | |
| - Consult domain-specific rule files for detailed guidance | |
| - Check similar implementations for guidance | |
| - Use the established error handling patterns | |
| - Follow the logging conventions with structured logging | |