first commit
This commit is contained in:
@@ -0,0 +1,94 @@
|
||||
---
|
||||
alwaysApply: true
|
||||
---
|
||||
# Backend Architecture - Supabase
|
||||
|
||||
## Overview
|
||||
The backend is built on Supabase, providing PostgreSQL database, authentication, and Edge Functions for serverless API endpoints.
|
||||
|
||||
## Database Structure
|
||||
|
||||
### Core Tables
|
||||
- `conversations`: Chat conversations between users and AI
|
||||
- `messages`: Individual messages within conversations
|
||||
|
||||
### Key Relationships
|
||||
- Users have many conversations
|
||||
- Conversations have many messages
|
||||
- Users have one subscription
|
||||
|
||||
## Edge Functions (`supabase/functions/`)
|
||||
|
||||
### Authentication & User Management
|
||||
- User registration and login handled by Supabase Auth
|
||||
- JWT tokens for API authentication
|
||||
|
||||
### Core Functions
|
||||
|
||||
#### Chat Functions
|
||||
- `chat/`: Parametric AI generation chat
|
||||
|
||||
### Shared Utilities (`_shared/`)
|
||||
- `cors.ts`: Simple file with cors headers
|
||||
- `messageUtils.ts`: Utility functions for formating user messages
|
||||
- `parseParameter.ts`: Parameter parsing utilities
|
||||
- `supabaseClient.ts`: Functions for getting supabase client
|
||||
|
||||
## API Patterns
|
||||
|
||||
### Authentication
|
||||
- All sensitive functions require JWT authentication
|
||||
- Use Supabase client for user verification
|
||||
- Implement proper role-based access control
|
||||
|
||||
### Error Handling
|
||||
- Consistent error response format
|
||||
- Proper HTTP status codes
|
||||
- Detailed error messages for debugging
|
||||
|
||||
### CORS Configuration
|
||||
- Configured for frontend domain
|
||||
- Handle preflight requests
|
||||
- Support for development and production
|
||||
|
||||
### Environment Variables
|
||||
- Stored in `supabase/functions/.env`
|
||||
- Include API keys for external services
|
||||
- Environment-specific configurations
|
||||
|
||||
### Configuration
|
||||
- New functions should be put in config.toml
|
||||
- Persistent storage buckets can be put either in a migration or in config.toml
|
||||
|
||||
## External Service Integration
|
||||
|
||||
### AI Services
|
||||
- **Anthropic Claude**: Text generation and chat
|
||||
|
||||
## Database Migrations
|
||||
|
||||
### Migration Files
|
||||
- Located in `supabase/migrations/`
|
||||
- Version-controlled database schema changes
|
||||
- Include both schema and data migrations
|
||||
|
||||
### Migration Patterns
|
||||
- Use descriptive migration names
|
||||
- Test migrations in development first
|
||||
|
||||
## Development Workflow
|
||||
|
||||
### Local Development
|
||||
- Use `supabase start` for local database
|
||||
- `supabase functions serve` for local functions
|
||||
- ngrok so model can access
|
||||
|
||||
### Testing
|
||||
- Test functions locally before deployment
|
||||
- Use Supabase CLI for database operations
|
||||
- Validate webhook endpoints
|
||||
|
||||
### Deployment
|
||||
- Functions deployed via Supabase CLI
|
||||
- Database migrations applied automatically
|
||||
- Environment variables configured in Supabase dashboard
|
||||
@@ -0,0 +1,40 @@
|
||||
---
|
||||
description:
|
||||
globs:
|
||||
alwaysApply: true
|
||||
---
|
||||
# Code Style Conventions
|
||||
version: 1.0.0
|
||||
|
||||
## TypeScript Rules
|
||||
|
||||
### Naming Conventions
|
||||
- Variables: `^[a-z][a-zA-Z0-9]*$`
|
||||
- Functions: `^[a-z][a-zA-Z0-9]*$`
|
||||
- Classes: `^[A-Z][a-zA-Z0-9]*$`
|
||||
- Interfaces: `^[A-Z][a-zA-Z0-9]*$`
|
||||
- Types: `^[A-Z][a-zA-Z0-9]*$`
|
||||
|
||||
### Formatting
|
||||
- Max line length: 100 characters
|
||||
- Indentation: 2 spaces
|
||||
- Semicolons: required
|
||||
- Quotes: single quotes
|
||||
|
||||
## React Rules
|
||||
- Component naming: `^[A-Z][a-zA-Z0-9]*$`
|
||||
- File naming: `^[A-Z][a-zA-Z0-9]*\.tsx$`
|
||||
- Props interface: `^[A-Z][a-zA-Z0-9]*Props$`
|
||||
|
||||
## Import Rules
|
||||
### Order
|
||||
1. react
|
||||
2. external-libraries
|
||||
3. components
|
||||
4. hooks
|
||||
5. utils
|
||||
6. types
|
||||
7. styles
|
||||
|
||||
### Grouping
|
||||
- Use newlines between import groups
|
||||
@@ -0,0 +1,78 @@
|
||||
---
|
||||
description:
|
||||
globs: *.sql,supabase.ts,supabase/*
|
||||
alwaysApply: false
|
||||
---
|
||||
# Database Workflow Rules
|
||||
version: 1.0.0
|
||||
|
||||
## Database Schema Changes
|
||||
|
||||
### NEVER Create Manual Migrations
|
||||
- Do NOT manually create migration files in `supabase/migrations/`
|
||||
- Always use the declarative schema approach
|
||||
- Update schema files in `supabase/schemas/` folder instead
|
||||
- Only modify generated migrations files if absolutely necessary
|
||||
|
||||
### Schema File Management
|
||||
- Modify existing table schemas in `supabase/schemas/` files
|
||||
- Add new tables by creating new schema files
|
||||
- Follow the existing schema file patterns and naming conventions
|
||||
|
||||
## Migration Generation Process
|
||||
|
||||
### Step 1: Stop Supabase
|
||||
```bash
|
||||
supabase stop
|
||||
```
|
||||
|
||||
### Step 2: Generate Migration
|
||||
```bash
|
||||
supabase db diff -f <migration_name>
|
||||
```
|
||||
- Replace `<migration_name>` with descriptive name (e.g., `add_user_preferences`, `create_new_table`)
|
||||
- Migration will be generated in `supabase/migrations/` with timestamp
|
||||
|
||||
### Step 3: Apply Migration
|
||||
```bash
|
||||
supabase start && supabase migration up
|
||||
```
|
||||
|
||||
## Local Development Only
|
||||
|
||||
### CRITICAL: Never Push to Remote
|
||||
- NEVER use `supabase db push`
|
||||
- NEVER use `supabase db pull`
|
||||
- ALL migrations should be tested locally only
|
||||
- Remote database changes are forbidden
|
||||
|
||||
## Type Generation
|
||||
|
||||
### Auto-Generate Types
|
||||
- NEVER manually edit `shared/database.ts`
|
||||
- Always regenerate after schema changes:
|
||||
```bash
|
||||
supabase gen types typescript --local > shared/database.ts
|
||||
```
|
||||
|
||||
## Workflow Summary
|
||||
|
||||
1. **Edit Schema**: Modify `supabase/schemas/` files
|
||||
2. **Stop Database**: `supabase stop`
|
||||
3. **Generate Migration**: `supabase db diff -f <name>`
|
||||
4. **Apply Migration**: `supabase start && supabase migration up`
|
||||
5. **Update Types**: `supabase gen types typescript --local > shared/database.ts`
|
||||
|
||||
## Common Commands Reference
|
||||
|
||||
```bash
|
||||
# Development workflow
|
||||
supabase stop
|
||||
supabase db diff -f <migration_name>
|
||||
supabase start && supabase migration up
|
||||
supabase gen types typescript --local > shared/database.ts
|
||||
|
||||
# NEVER use these commands
|
||||
# supabase db push ❌
|
||||
# supabase db pull ❌
|
||||
```
|
||||
@@ -0,0 +1,39 @@
|
||||
---
|
||||
globs: supabase/**/*
|
||||
alwaysApply: false
|
||||
---
|
||||
# Deployment Restrictions
|
||||
version: 1.0.0
|
||||
|
||||
## Function Deployment
|
||||
|
||||
### NEVER Deploy Functions
|
||||
- **NEVER** run `supabase functions deploy` commands
|
||||
- **NEVER** run `npx supabase functions deploy` commands
|
||||
- **NEVER** attempt to deploy any Supabase Edge Functions
|
||||
- **NEVER** suggest or recommend deploying functions
|
||||
|
||||
### Local Development Only
|
||||
- All function testing should be done locally with `supabase functions serve`
|
||||
- Use local Supabase instance for development and testing
|
||||
- Function deployment is exclusively the responsibility of the human developer
|
||||
|
||||
### Code Changes Only
|
||||
- AI assistant should only:
|
||||
- Modify function code
|
||||
- Update type definitions
|
||||
- Make local code changes
|
||||
- Run type checks
|
||||
- Test locally if needed
|
||||
|
||||
### Deployment Handoff
|
||||
- After making function changes, simply inform the user that:
|
||||
- The code changes are complete
|
||||
- Function deployment is required for the changes to take effect
|
||||
- The user needs to deploy manually when ready
|
||||
|
||||
## Rationale
|
||||
- Production deployments require human oversight
|
||||
- Deployment credentials should not be accessed by AI
|
||||
- Local testing is sufficient for development workflow
|
||||
- Human developer maintains control over when and what gets deployed
|
||||
@@ -0,0 +1,97 @@
|
||||
---
|
||||
alwaysApply: true
|
||||
---
|
||||
# Frontend Architecture - React/TypeScript
|
||||
|
||||
## Component Architecture
|
||||
|
||||
### Views (Page Components)
|
||||
- Located in `src/views/`
|
||||
- Each view represents a full page/route
|
||||
- Use React Router for navigation
|
||||
- Implement proper loading and error states
|
||||
- Examples: `PromptView`, `EditorView`, `HistoryView`
|
||||
|
||||
### Reusable Components
|
||||
- Located in `src/components/`
|
||||
- Organized by feature/domain
|
||||
- Use TypeScript interfaces for props
|
||||
- Follow shadcn/ui patterns
|
||||
- Implement proper accessibility
|
||||
|
||||
### Component Categories
|
||||
- `ui/`: Base UI components (buttons, inputs, etc.)
|
||||
- `chat/`: Components used in ChatSection
|
||||
- `parameter/`: Components used in ParameterSection
|
||||
- `viewer/`: Components used in ViewerSection
|
||||
- `history/`: Components used in the history page
|
||||
|
||||
## State Management
|
||||
|
||||
### Contexts (`src/contexts/`)
|
||||
- `AuthContext`: User authentication and session
|
||||
- `BlobContext`: STL blob generated from OpenSCAD WASM
|
||||
- `ColorContext`: Purely stylistic color for model
|
||||
- `CurrentMessageContext`: Current message being processed
|
||||
- `SelectedItemsContext`: Selected items across components
|
||||
|
||||
### React Query
|
||||
- Used for server state management
|
||||
- Configured in `src/main.tsx`
|
||||
- Provides caching, synchronization, and background updates
|
||||
- Handle loading, error, and success states
|
||||
|
||||
## Custom Hooks (`src/hooks/`)
|
||||
- `useOpenSCAD`: OpenSCAD integration
|
||||
- `useItemSelection`: Item selection management
|
||||
- `useToast`: Toast notification management
|
||||
|
||||
## Services (`src/services/`)
|
||||
- `conversationService`: Chat/conversation API calls, mutations and queries
|
||||
- `messageService`: Message handling and processing, mutations and queries
|
||||
- All services use Supabase client for API calls
|
||||
|
||||
## Utilities (`src/utils/`)
|
||||
- `file-utils`: Primarily for getting a safe filename when exporting a file
|
||||
- `parameterUtils`: Parameter validation and processing
|
||||
- `downloadUtils`: Functions for downloading generated model
|
||||
|
||||
## Types (`src/types/`)
|
||||
- `misc.ts`: Miscellaneous type definitions, should probably get broken up in the future
|
||||
- Use proper TypeScript interfaces and types
|
||||
- Export types for reuse across components
|
||||
|
||||
## 3D Graphics Integration
|
||||
|
||||
### Three.js Setup
|
||||
- Use React Three Fiber for React integration
|
||||
- Implement proper cleanup and resource management
|
||||
- Handle WebGL context loss gracefully
|
||||
- Use proper lighting and materials
|
||||
|
||||
### OpenSCAD Integration
|
||||
- Web Worker in `src/worker/` for OpenSCAD processing
|
||||
- WASM-based OpenSCAD compilation
|
||||
- Real-time parameter updates
|
||||
- Error handling for compilation failures
|
||||
|
||||
## Routing Structure
|
||||
- Main routes defined in `src/main.tsx`
|
||||
- Error boundaries for route error handling
|
||||
|
||||
## Styling
|
||||
- Tailwind CSS for utility-first styling
|
||||
- shadcn/ui components for consistent design
|
||||
- Custom CSS in `src/index.css`
|
||||
- Not standard css classes, adam specific, refer to tailwind.config.js for specifics
|
||||
|
||||
## Error Handling
|
||||
- Error boundaries for component error catching
|
||||
- Toast notifications for user feedback
|
||||
- Proper error states in components
|
||||
|
||||
## Performance
|
||||
- React Query for efficient data fetching
|
||||
- Proper memoization with `useMemo` and `useCallback`
|
||||
- Lazy loading for route components
|
||||
- Image optimization and lazy loading
|
||||
@@ -0,0 +1,93 @@
|
||||
---
|
||||
description:
|
||||
globs:
|
||||
alwaysApply: false
|
||||
---
|
||||
# Adam - AI-Powered 3D CAD Model Generation Platform
|
||||
|
||||
## Project Overview
|
||||
Adam is a web application that enables users to generate 3D CAD models through AI-powered natural language, images, and direct manipulation. The platform combines parametric modeling with creative AI generation.
|
||||
|
||||
## Tech Stack
|
||||
- **Frontend**: React 19 + TypeScript + Vite
|
||||
- **UI Framework**: Radix UI + Tailwind CSS + shadcn/ui
|
||||
- **3D Graphics**: Three.js + React Three Fiber
|
||||
- **Backend**: Supabase (PostgreSQL + Edge Functions)
|
||||
- **Authentication**: Supabase Auth
|
||||
- **AI Services**: Anthropic Claude
|
||||
- **State Management**: React Query + Context API
|
||||
- **Routing**: React Router v6
|
||||
|
||||
## Project Structure
|
||||
```
|
||||
adam/
|
||||
├── src/ # Frontend source code
|
||||
│ ├── components/ # Reusable UI components
|
||||
│ ├── views/ # Page-level components
|
||||
│ ├── contexts/ # React contexts
|
||||
│ ├── hooks/ # Custom React hooks
|
||||
│ ├── services/ # API service functions
|
||||
│ ├── utils/ # Utility functions
|
||||
│ ├── types/ # TypeScript type definitions
|
||||
│ ├── lib/ # Third-party library configurations
|
||||
│ └── worker/ # Web Worker for OpenSCAD processing
|
||||
├── supabase/ # Backend configuration
|
||||
│ ├── functions/ # Edge functions
|
||||
│ ├── migrations/ # Database migrations
|
||||
│ ├── schemas/ # Database schemas
|
||||
│ └── config.toml # Supabase configuration
|
||||
├── public/ # Static assets
|
||||
└── shared/ # Items shared between backend and frontend
|
||||
```
|
||||
|
||||
## Development Conventions
|
||||
|
||||
### Code Style
|
||||
- Use TypeScript for all new code
|
||||
- Follow React 19 patterns and hooks
|
||||
- Use functional components with hooks
|
||||
- Implement proper error boundaries
|
||||
- Use React Query for server state management
|
||||
|
||||
### Component Structure
|
||||
- Components in `src/components/` are reusable
|
||||
- Views in `src/views/` are page-level components
|
||||
- Use proper TypeScript interfaces for props
|
||||
- Implement proper loading and error states
|
||||
|
||||
### State Management
|
||||
- Use React Context for global state (auth, user data)
|
||||
- Use React Query for server state
|
||||
- Use local state for component-specific data
|
||||
- Implement proper loading states and error handling
|
||||
|
||||
### API Integration
|
||||
- All API calls go through Supabase Edge Functions
|
||||
- Use React Query for caching and synchronization
|
||||
- Implement proper error handling and retry logic
|
||||
- Use TypeScript interfaces for API responses.
|
||||
|
||||
### 3D Graphics
|
||||
- Use Three.js for 3D rendering
|
||||
- Implement proper cleanup for Three.js resources
|
||||
- Use React Three Fiber for React integration
|
||||
- Handle WebGL context loss gracefully
|
||||
|
||||
### Security
|
||||
- All sensitive operations go through authenticated Edge Functions
|
||||
- Implement proper CORS policies
|
||||
- Validate all user inputs
|
||||
- Use environment variables for sensitive data
|
||||
|
||||
## Environment Setup
|
||||
- Frontend: `.env.local` for Vite environment variables
|
||||
- Backend: `supabase/functions/.env` for Edge Function environment variables
|
||||
- Use ngrok for local webhook development
|
||||
|
||||
## Common Patterns
|
||||
- Use React Query for data fetching and caching
|
||||
- Implement proper loading states with skeleton components
|
||||
- Use toast notifications for user feedback
|
||||
- Implement proper error boundaries
|
||||
- Use React Router for navigation
|
||||
- Follow the established component hierarchy
|
||||
@@ -0,0 +1,119 @@
|
||||
---
|
||||
description:
|
||||
globs: *.ts,*.tsx
|
||||
alwaysApply: false
|
||||
---
|
||||
# TypeScript Workflow Rules
|
||||
version: 1.1.0
|
||||
|
||||
## Type Checking
|
||||
|
||||
### Always Run Type Check After Type Changes
|
||||
- When modifying database schemas that affect TypeScript types
|
||||
- When updating type definitions or interfaces
|
||||
- When there are potential type conflicts or errors
|
||||
- When the LLM cannot see all related files that might be affected
|
||||
|
||||
### Type Check Commands
|
||||
|
||||
#### Frontend (Node.js/TypeScript)
|
||||
For files in `src/`, `shared/`, and other frontend directories:
|
||||
```bash
|
||||
npm run typecheck
|
||||
```
|
||||
|
||||
#### Supabase Edge Functions (Deno)
|
||||
For files in `supabase/functions/`, you must cd into each function directory:
|
||||
```bash
|
||||
cd supabase/functions/[function-name]
|
||||
deno check index.ts
|
||||
```
|
||||
|
||||
Example:
|
||||
```bash
|
||||
cd supabase/functions/chat
|
||||
deno check index.ts
|
||||
```
|
||||
|
||||
You can also run the npm command
|
||||
```bash
|
||||
npm run lint:supabase
|
||||
```
|
||||
|
||||
## When to Run Type Check
|
||||
|
||||
### Database Schema Changes
|
||||
- After running `supabase gen types typescript --local`
|
||||
- After applying migrations that change table structures
|
||||
- When adding new columns, tables, or modifying existing ones
|
||||
|
||||
### Type Definition Updates
|
||||
- After modifying `src/types/` or `shared/*.ts` files
|
||||
- When updating component prop interfaces
|
||||
- When changing API response types
|
||||
- When modifying context or hook return types
|
||||
|
||||
### Potential Type Issues
|
||||
- When using `any` types as workarounds
|
||||
- When there are TypeScript errors in the editor
|
||||
- When importing/exporting between files with type dependencies
|
||||
- When the LLM cannot see all related files in the conversation
|
||||
|
||||
## Workflow Integration
|
||||
|
||||
### With Database Changes
|
||||
1. Edit schema files in `supabase/schemas/`
|
||||
2. Generate migration: `supabase db diff -f <name>`
|
||||
3. Apply migration: `supabase start && supabase migration up`
|
||||
4. Regenerate types: `supabase gen types typescript --local > shared/database.ts`
|
||||
5. **Run type check**:
|
||||
- Frontend: `npx tsc -b`
|
||||
- Edge Functions: `cd supabase/functions/[function-name] && deno check index.ts`
|
||||
6. Fix any type errors in the codebase
|
||||
|
||||
### With Frontend Changes
|
||||
1. Modify TypeScript files in `src/` or `shared/`
|
||||
2. **Run type check**: `npx tsc -b`
|
||||
3. Fix any type errors
|
||||
4. Continue with implementation
|
||||
|
||||
### With Supabase Edge Function Changes
|
||||
1. Modify TypeScript files in `supabase/functions/`
|
||||
2. **Run type check**: `cd supabase/functions/[function-name] && deno check index.ts`
|
||||
3. Fix any type errors
|
||||
4. Continue with implementation
|
||||
|
||||
## Error Resolution
|
||||
|
||||
### Common Type Issues
|
||||
- Missing properties in interfaces
|
||||
- Incorrect return types from functions
|
||||
- Type mismatches between components
|
||||
- Missing imports for type definitions
|
||||
|
||||
### Resolution Steps
|
||||
1. Run appropriate type check command based on file location:
|
||||
- Frontend: `npx tsc -b`
|
||||
- Edge Functions: `cd supabase/functions/[function-name] && deno check index.ts`
|
||||
2. Fix errors systematically, starting with the most critical
|
||||
3. Re-run type check after each fix
|
||||
4. Ensure all type errors are resolved before proceeding
|
||||
|
||||
## Best Practices
|
||||
|
||||
### Type Safety
|
||||
- Avoid using `any` types unless absolutely necessary
|
||||
- Use proper TypeScript interfaces and types
|
||||
- Leverage the generated Supabase types
|
||||
- Maintain type consistency across the codebase
|
||||
|
||||
### Development Workflow
|
||||
- Run type checks frequently during development
|
||||
- Fix type errors immediately when they appear
|
||||
- Use TypeScript strict mode settings
|
||||
- Keep type definitions up to date with schema changes
|
||||
|
||||
### Environment-Specific Considerations
|
||||
- **Frontend**: Uses Node.js TypeScript compiler, supports all standard TypeScript features
|
||||
- **Edge Functions**: Uses Deno's TypeScript compiler, may have different import/export requirements
|
||||
- **Shared Types**: Files in `shared/` are used by both environments, ensure compatibility
|
||||
Reference in New Issue
Block a user