Awesome Cursor Rules Collection

# ALIEN

Check README.md for the idea and core pillars.

## Tech Stack

- Frontend: Next.js, Tailwind, Shadcn, Framer Motion
- Backend: Postgres, Supabase, Drizzle ORM, Server Actions
- Auth: Clerk
- Payments: Stripe
- Deployment: Vercel

## Project Structure

### General Structure

- `actions` - Server actions
  - `db` - Database-related actions (queries, mutations)
  - Other domain-specific actions
- `app` - Next.js app router
  - `api` - API routes
  - `route` - Route-specific code
    - `_components` - One-off components
    - `layout.tsx` - Layout
    - `page.tsx` - Page
- `components` - Shared components
  - `ui` - Reusable UI elements (buttons, inputs, etc.)
  - `utilities` - Helper components (layouts, providers, etc.)
- `db` - Database
  - `migrations` - Auto-generated migrations
  - `queries` - Database queries
  - `schema` - Database schemas
- `lib` - Library code
  - `hooks` - React hooks for shared logic
- `prompts` - AI prompt templates and configurations
- `public` - Static assets
- `types` - Type definitions

## Rules

### General Rules
- Use `@` to import anything from the project unless otherwise specified
- Use kebab case for all files and folders except:
  - React components (PascalCase)
  - React hooks (camelCase)
  - Database schemas (kebab-case)
- All components must be tagged with either `use server` or `use client`
- All code goes in root-level folders, DO NOT create a `src` directory
- Static assets:
  - Use `public` for external files (CSV, images, etc.)
  - Use `app` for route-specific assets

### Data Flow Rules
- Fetch data in server components and pass down as props to client components
- Use server actions from `/actions` for data mutations
- Use `auth` from `@clerk/nextjs/server` for user authentication
- Prefer existing types over new interfaces

### Environment Rules

- All environment variables should go in `.env.local`
- Do not expose environment variables to the frontend
- Use `NEXT_PUBLIC_` prefix for environment variables that need to be accessed from the frontend
- You may import environment variables in server actions and components by using `process.env.VARIABLE_NAME`

### Type Rules

- When importing types, use `@/types`
- Name files like `example-types.ts`
- All types should go in `types`
- Make sure to export the types in `types/index.ts`
- Prefer interfaces over type aliases
- If referring to db types, use `@/db/schema` such as `SelectAction` from `example-schema.ts`

An example of a type:

`types/actions-types.ts`

```ts
export type ActionState<T> = {
  isSuccess: boolean
  message: string
  data?: T
}
```

And exporting it:

`types/index.ts`

```ts
export * from "./actions-types"
```

### Frontend Rules

Follow these rules when working on the frontend.

It uses Next.js, Tailwind, Shadcn, and Framer Motion.

#### General Rules

- Use `lucide-react` for icons
- Use mobile first approach

#### Components

- When editing existing components preserve styles and classes - it's figma designs we should follow
- Use divs instead of other html tags unless otherwise specified
- Separate the main parts of a component's html with an extra blank line for visual spacing
- Use actions, not queries, in the app
- Always tag a component with either `use server` or `use client` at the top, including layouts and pages

##### Organization

- All components be named using kebab case like `example-component.tsx` unless otherwise specified
- Put components in `/_components` in the route if one-off components
- Put components in `/components` from the root if shared components

##### Server Components

- Use `"use server"` at the top of the file
- Implement Suspense for asynchronous data fetching
- Use a separate fetcher component for data loading (see example below)

Example of a server page:

```tsx
"use server"

import { Suspense } from "react"
import { SomeAction } from "@/actions/some-actions"
import SomeComponent from "./_components/some-component"
import SomeSkeleton from "./_components/some-skeleton"

export default async function ExampleServerPage({
  params
}: {
  params: { id: string }
}) {
  return (
    <Suspense fallback={<SomeSkeleton className="some-class" />}>
      <SomeComponentFetcher id={params.id} />
    </Suspense>
  )
}

async function SomeComponentFetcher({ id }: { id: string }) {
  const { data } = await SomeAction(id)

  <SomeComponent className="some-class" initialData={data || []} id={id} />
}
```

Example of a server component:

```tsx
"use server"

interface ExampleServerComponentProps {
  // Your props here
}

export async function ExampleServerComponent({
  props
}: ExampleServerComponentProps) {
  // Your code here
}
```

##### Client Components

- Use `"use client"` at the top of the file

Example of a client page:

```tsx
"use client"

export default function ExampleClientPage() {
  // Your code here
}
```

Example of a client component:

```tsx
"use client"

interface ExampleClientComponentProps {
  // Your props here
}

export default function ExampleClientComponent({
  props
}: ExampleClientComponentProps) {
  // Your code here
}
```

### Backend Rules

Uses Clerk (Auth), Supabase (DB), Drizzle ORM, and Server Actions.

#### API Routes
- New API routes go to app/[api-name]/[route].ts

#### Database Structure and Flow
1. Create schema first: `/db/schema/[name]-schema.ts`
   - Export in `/db/schema/index.ts`
   - Add to schema in `/db/db.ts`
2. Create queries next: `/db/queries/[name]-queries.ts`
   - All database operations go here
   - Return `ActionResult` type
   - Handle try/catch blocks
3. Create actions last: `/actions/[name]-actions.ts`
   - Server actions wrap queries
   - Never write DB logic here
   - Only handle data passing and validation

#### Database Setup
- Create `/db/db.ts` with the following structure:

```typescript
import { config } from "dotenv"
import { drizzle } from "drizzle-orm/postgres-js"
import postgres from "postgres"
// Import your schemas here
import { /* your schemas */ } from "./schema"

config({ path: ".env.local" })

const schema = {
  // Add your schemas here
}

const client = postgres(process.env.DATABASE_URL!)

export const db = drizzle(client, { schema }) 
```

Required environment variables:
- `DATABASE_URL`: Supabase connection string

Required package.json scripts:

```json
{
  "scripts": {
    "db:generate": "drizzle-kit generate",
    "db:migrate": "drizzle-kit migrate"
  }
}
```

Notes:
- Import schemas from `./schema` as they're created
- Add each schema to the schema object
- Use `.env.local` for environment variables
- Run migrations after schema changes:
  ```bash
  npm run db:generate
  npm run db:migrate
  ```

### AI Rules

#### Model Usage
- Use `gpt-4o-mini` for all LLM tasks unless otherwise specified
- Use `text-embedding-3-small` with 256 dimensions for embeddings

#### Embeddings Service
- Create `/lib/services/embeddings-service.ts` with this structure:

```typescript
"use server";

import OpenAI from "openai";

const openai = new OpenAI();

export async function generateEmbeddings(texts: string[]) {
  const response = await openai.embeddings.create({
    model: "text-embedding-3-small",
    dimensions: 256,
    input: texts
  });

  return response.data.map((item) => item.embedding);
}
```

#### Retrieval Service
- Create `/lib/services/retrieval-service.ts` with this structure:

```typescript
import { db } from "@/db";
import { documentsTable } from "@/db/schema/documents-data";
import { cosineDistance, desc, gt, sql } from "drizzle-orm";
import { generateEmbeddings } from "../generation/generate-embeddings";

export async function retrieveDocuments(
  input: string, 
  options: { 
    limit?: number; 
    minSimilarity?: number 
  } = {}
) {
  const { 
    limit = 10, 
    minSimilarity = 0.3 
  } = options;

  const embeddings = await generateEmbeddings([input]);
  const similarity = sql<number>`1 - (${cosineDistance(documentsTable.embedding, embeddings[0])})`;

  const documents = await db
    .select({
      content: documentsTable.content,
      similarity
    })
    .from(documentsTable)
    .where(gt(similarity, minSimilarity))
    .orderBy((t) => desc(t.similarity))
    .limit(limit);

  return documents;
}
```

#### Structured Output Service
- Create `/lib/services/structured-output-service.ts` with this structure:

```typescript
import OpenAI from 'openai';
import { z } from 'zod';
import { zodResponseFormat } from "openai/helpers/zod";

const openai = new OpenAI({
  apiKey: process.env.OPENAI_API_KEY,
});

export interface StructuredOutputResponse<T> {
  success: boolean;
  data?: T;
  error?: string;
}

export class StructuredOutputService {
  private static createErrorResponse(error: string): StructuredOutputResponse<any> {
    return { success: false, error };
  }

  static async process<T>(
    input: string,
    schema: z.ZodSchema,
    prompt: string,
    modelName: string = "gpt-4o-mini"
  ): Promise<StructuredOutputResponse<T>> {
    try {
      const completion = await openai.beta.chat.completions.parse({
        model: modelName,
        messages: [
          { role: "system", content: prompt },
          { role: "user", content: input }
        ],
        response_format: zodResponseFormat(schema, "data")
      });

      const parsedData = completion.choices[0].message.parsed;
      
      if (!parsedData) {
        return this.createErrorResponse('Failed to parse data');
      }

      return {
        success: true,
        data: parsedData as T
      };

    } catch (error) {
      console.error('Error structuring data:', error);
      return this.createErrorResponse(
        error instanceof Error ? error.message : 'Failed to structure data'
      );
    }
  }
}
```

Required environment variables:
- `OPENAI_API_KEY`: OpenAI API key

Notes:
- All services should be in `/lib/services/`
- Each service has a single responsibility
- Services can be composed together as needed

# NOTES
- When the file is exceeding 500 lines inform me

Project: Common-Chat
Tech Stack:
- Next.js (React Framework)
- TypeScript
- Tailwind CSS
- ESLint
- PostCSS

Architecture:
/src
  /app          # Next.js App Router, Pages
  /components   # React Components (Chat, RAG Interface)
  /context      # React Context Providers
  /services     # API Integration, Business Logic
  /types        # TypeScript Definitions

Key Features:
- RAG (Retrieval-Augmented Generation) Interface
- Dynamic Chat System
- Source Management
- Markdown Support
- Responsive Design

Core Components:
- RAGInterface.tsx: Main RAG interaction
- ChatHistory.tsx: Chat management
- ChatMessage.tsx: Message rendering
- Layout.tsx: App structure

When writing react use as much NextUi components as possible, every module of the backend must be written in OOP following MVC pattern.
Entire project uses esm modules import syntax. DO NOT USE require.
ADD JSDOC TO EVERYTHING IN THE BACKEND(CLASSES, METHODS, ETC).

## Flow Overview

1. **Route Match**:
   - A user request (e.g., `GET /orders/:id`) triggers a specific controller method.

2. **Controller**:
   - Extracts and validates input from the request.
   - Delegates business logic to the **Service Layer**.

3. **Service Layer**:
   - Validates and processes data.
   - Coordinates repositories or external APIs to retrieve data.
   - Enforces business rules and logic.

4. **Repository Layer**:
   - Fetches raw data from the database.
   - Converts raw data into **Model** instances.

5. **Model Layer**:
   - Represents the application's domain entities.
   - Provides entity-specific methods (e.g., `calculateTotal()`).
   - Encapsulates logic related to individual entities.

6. **Back to Controller**:
   - The controller serializes the processed model data and sends it as an HTTP response.

---

## Interpretation of MVC

- **Repository**: The data layer, which interacts with the database.
- **Service**: Validates and processes data, coordinates repositories or external APIs to retrieve data, enforces business rules and logic.
- **Controller**: The presentation layer, validates and processes data from the request, and delegates the business logic to the service layer.
- **Model**: Domain entities, properties and methods specific to the entities.
- **View**: The presentation layer, Json responses to the client.

You are an expert AI programming assitant that primarily focues on producing clear, readable React and TypeScript code.

You always use the Latest stable version of TypeScript, JavaScript, React, Node.js, Next.js App Router, Shaden UI, Tailwind CSS and you are familiar with the Latest features and best practices.

You carefully provide accurate, factual, thoughtful answers, and are a genius at reasoning ai to chat, to generate

Code StyLe and Structure
- Write concise, technical TypeScript code with accurate examples.
    - Use functional and declarative programming patterns; avoid classes.
    - Prefer iteration and modularization over code duplication.
- Use descriptive variable names with auxiliary verbs(e.g. isLoading, hasError).
- Structure files: exported component, subcomponents, helpers, static content, types.

Naming Conventions
- Use lowercase with dashes for directories and components file name (e.g. components/auth-wizard).
- Favor named exports for components.

TypeScript Usage
- Use TypeScript for all code; prefer interfaces over types
- Avoid enums; use maps instead
- Use functional components with TypeScript interfaces

Syntax and Formatting:
- Use the "function" keyword for pure functions
- Avoid unnecessary curly braces in conditionals; use concise syntax for simple statements
- Use declarative JSX

Error Handling and Validation:
- Prioritize error handling: handle errors and edge cases early
- Use early returns for error conditions and guard clauses to avoid deeply nested if statements.
- Implement proper error logging and user-friendly messages
- Place the happy path last in the function for improved readability.
- Avoid unnecessary else statements; use if-return pattern instead.
- Use guard clauses to handle preconditions and invalid states early.
- Use Zod for form validation
- Model expected errors as return values in Server Actions
- Use error boundaries for unexpected errors
- Consider using custom error types or error factories for consistent error handling.

UI and Styling
- Use Shadcn UI, and Tailwind CSS for components and styling.
- Add micro-interactions to improve user experience using Tailwind CSS and framer-motion.
- Implement responsive design with Tailwind CSS; use a mobile-first approach.

State Management
  - Use Zustand for global state management.
  - Lift state up when needed to share state between components.
  - Use context for intermediate state sharing when prop drilling becomes cumbersome.

Performance Optimization
- Minimize 'use client', 'useEffect', and 'setstate', I favor React Server Components (RSC).
- Wrap client components in Suspense with fallback.
- Use dynamic Loading for non-critical components.
- Optimize images: use WebP format, include size data, implement lazy loading

Key Conventions:
- Use 'nuqs' for URL search parameter state management
- Prioritize & Optimize Web Vitals (LCP, CLS, FID)
- Limit 'use client':
  - Favor server components and Next.js SSR
  - Use only for Web API access in small components
  - Avoid for data fetching or state management

Other Rules need to follow:
- Referring package.json file when choosing dependencies, use existing packages when possible, consider use existing open source solutions when implementing features from scratch.
- Follow the user's requirements carefully & to the Letter.
- First think step-by-step - describe your plan for what to build in pseudocode, written out in great detail.
- Confirm, then write code!
- Always write correct, up to date, bug free, fully functional and working, secure, performant and efficient code.
- Focus on readability over being performant.
- Fully implement all requested functionality.
- Leave No todo's, placeholders or missing pieces.
- Be sure to reference file names.
- Be concise, Minimize any other prose.
- If you think there might not be a correct answer, you say so. If you do not know the answer, say so instead of guessing.

Don't be lazy, write all the code to implement features I ask for

// Next.js App Router .cursorrules

// Next.js App Router best practices
const nextjsAppRouterBestPractices = [
  "Use server components by default",
  "Implement client components only when necessary",
  "Utilize the new file-based routing system",
  "Use layout.js for shared layouts",
  "Implement loading.js for loading states",
  "Use error.js for error handling",
  "Utilize route handlers for API routes",
];

// TECHNOLOGY STACK
Frontend:
- yarn as package manager
- Framework: Next.js (React)
- Language: TypeScript
- UI Components: shadcn/ui (based on Radix UI primitives)
- Styling: Tailwind CSS
- Icons: Lucide React

Backend:
- Framework: Next.js API Routes (for serverless functions)
- Language: TypeScript (for API routes)

// Folder structure
const folderStructure = `
app/
  layout.js
  page.js
public/
components/
lib/
hooks/
data/
config/
`;

// Additional instructions
const additionalInstructions = `
1. Use TypeScript for type safety
2. Implement proper metadata for SEO
3. Utilize Next.js Image component for optimized images
4. Tailwind CSS for styling
5. Implement proper error boundaries
6. Follow Next.js naming conventions for special files
7. Use environment variables for configuration
`;

You are an expert AI programming assistant specializing in React, TypeScript, and Nx monorepo development for HAQQ blockchain applications.

# Project Overview

This monorepo blockchain project is built with:

- **Nx**: Build system and monorepo management
- **React**: User interface development
- **TypeScript**: Type safety and static typing
- **Tailwind CSS**: Utility-first CSS framework for styling
- **Jest**: Testing framework
- **Storybook**: Component documentation and development environment
- **Wagmi**: React hooks for Ethereum interactions
- **Viem**: Low-level blockchain operations
- **HAQQ Network**: Blockchain integration

# Key Development Principles

1. **Clean and Maintainable Code**: Write clear, readable, and maintainable TypeScript code.
2. **Functional Components**: Utilize React functional components exclusively.
3. **Monorepo Best Practices**: Adhere to Nx monorepo architecture guidelines.
4. **Responsive Design**: Implement responsive layouts using Tailwind CSS.
5. **Comprehensive Testing**: Develop thorough tests and stories for all components and features.

# Key Libraries and Tools

## Blockchain Integration

- **Wagmi**: React hooks and wallet integration for Ethereum.
- **Viem**: TypeScript interface for Ethereum, preferred over Ethers.js.
- **HAQQ Network**: Specific integrations for the HAQQ blockchain.
- **EVM Compatibility**: Ensure compatibility with the Ethereum Virtual Machine.

## Core Technologies

- **React**: For building user interfaces.
- **TypeScript**: For static typing and type safety.
- **Nx**: For monorepo management and build orchestration.
- **TanStack Query**: For efficient data fetching and state management.
- **Tailwind CSS**: For utility-first styling.

# Blockchain Development Standards

- **Transaction Handling**: Implement proper transaction lifecycle management and confirmations.
- **Wallet Integration**: Support multiple wallet providers and handle connection states.
- **Gas Management**: Implement proper gas estimation and fee handling.
- **Network States**: Handle network switching and connection states.
- **Smart Contract Interaction**: Use typed contract interfaces and proper ABI handling.

# Security Considerations

- **Input Validation**: Validate all user inputs, especially for transaction amounts and addresses.
- **Address Handling**: Implement proper address validation and checksum verification.
- **Transaction Safety**: Implement confirmation dialogs and amount validation.
- **Network Security**: Handle network-specific requirements and chain IDs.
- **Private Key Safety**: Never expose or handle private keys in the frontend.

# Coding Standards

- **TypeScript Strict Mode**: Enable and enforce strict type checking.
- **Functional Programming**: Emphasize functional programming paradigms; avoid class-based components.
- **Named Exports**: Use named exports for all components.
- **Component Design**: Keep components small, focused, and reusable.
- **Composition Over Inheritance**: Favor composition patterns over inheritance.
- **Error Handling**: Implement robust error handling mechanisms.
- **Descriptive Naming**: Use clear and descriptive names for variables and functions.
- **Documentation**: Write comments and documentation in English.

# File Structure Conventions

- **Directory Naming**: Use lowercase with dashes (e.g., `components/auth-wizard`).
- **Test Placement**: Place test files adjacent to their implementation files.
- **Story Placement**: Keep Storybook stories alongside their respective components.
- **Nx Workspace Structure**: Follow Nx's recommended workspace organization.

# Component Guidelines

- **Function Declarations**: Define components using function declarations.
- **Props Interfaces**: Name props interfaces as `[ComponentName]Props`.
- **Static Content**: Place static content at the end of files.
- **Separation of Concerns**: Separate presentation logic from business logic.
- **Styling**: Use Tailwind CSS for all styling needs.
- **Accessibility**: Ensure components are accessible and adhere to WCAG guidelines.

# Testing Conventions

- **Unit Tests**: Write unit tests for all business logic.
- **Integration Tests**: Develop integration tests for complex workflows.
- **E2E Tests**: Include E2E tests for critical workflows (especially wallet and blockchain interactions).
- **Mocking**: Apply appropriate mocking strategies where necessary.
- **AAA Pattern**: Follow the Arrange-Act-Assert pattern in tests.

# State Management

- **Local State**: Use React hooks for managing local component state.
- **Error Boundaries**: Implement error boundaries to catch and handle errors gracefully.
- **Loading States**: Handle loading states appropriately to enhance user experience.
- **Data Fetching**: Follow best practices for data fetching and caching.
- **Transaction State**: Manage transaction lifecycle states effectively.
- **Blockchain State**: Handle chain and network state changes.
- **Wallet State**: Manage wallet connection and account states.
- **Cache Management**: Implement proper caching for blockchain data.

# Performance Considerations

- **Code Splitting**: Implement code splitting to optimize load times.
- **Memoization**: Use `React.memo()` and `useMemo()` to prevent unnecessary re-renders.
- **Bundle Optimization**: Optimize bundle size to improve performance.
- **Lazy Loading**: Apply lazy loading for non-critical components and assets.

# Error Handling

- **Error Boundaries**: Use error boundaries to catch UI errors.
- **Typed Errors**: Implement typed error handling for better type safety.
- **User Feedback**: Provide user-friendly error messages.
- **Logging**: Log errors appropriately for monitoring and debugging.
- **Transaction Errors**: Handle blockchain transaction failures gracefully.
- **Network Errors**: Manage network connection and RPC errors.
- **Wallet Errors**: Handle wallet connection and signing errors.
- **Contract Errors**: Process smart contract interaction errors.

# Accessibility

- **WCAG Compliance**: Ensure all components meet WCAG accessibility standards.
- **ARIA Attributes**: Implement proper ARIA attributes for assistive technologies.
- **Keyboard Navigation**: Ensure full keyboard navigability.
- **Screen Reader Testing**: Test components with screen readers to verify accessibility.

# Prioritization in Code Generation

When generating code, prioritize the following aspects in order:

1. **Type Safety**
2. **Readability**
3. **Maintainability**
4. **Performance**
5. **Security**

# Project Structure

- **Location**: All files are located inside the `libs/` and `apps/` directories, following Nx conventions.

# Development Environment

- **Network Configuration**: Set up proper RPC endpoints and chain configurations.
- **Local Development**: Configure local development environment with proper network settings.
- **Testing Environment**: Set up proper test networks and mock providers.
- **CI/CD**: Configure proper build and deployment pipelines for blockchain applications.

# Documentation Requirements

- **Transaction Flows**: Document complex transaction flows and state changes.
- **Contract Interactions**: Document smart contract interaction patterns.
- **Error Codes**: Maintain documentation for blockchain-specific error codes.
- **Network Specifics**: Document network-specific features and requirements.

# PROJECT OVERVIEW
- This project is a comprehensive web application designed for Danish primary school students and teachers. 
- Students can track their progress in courses, access an AI-powered chat for help (both via chat, voice and files), view schedules and achievements, and more.
- Teachers can upload course materials, manage schedules, and monitor student performance.

Project Idea:
- This project is a comprehensive web application designed for Danish primary school students and teachers. 
- Students can track their progress in courses, access an AI-powered chat for help (both via chat, voice and files), view schedules and achievements, and more.
- Teachers can upload course materials, manage schedules, and monitor student performance.
- To begin with the project, we will focus on mathematics, physics, and chemistry (Expand later to other subjects).

Example 1:
- Teacher can chat with AI that knows the Sudents name, class, and what they are working on.
- AI can help the teacher with the lesson plan, students are gennerally having problems (Asking ai about certain problem often) X, enabeling the teacher to focus on that specific subject.
- AI can also help the teacher with the lesson plan, and give feedback on the lesson.

Example 2:
- Student can chat with AI that knows the students name, class, and what they are working on.
- AI can help the student with the lesson plan, specific tasks and problems (Without the teacher being present) + (Without giving the answer away, but instead guiding the student to the answer).
- AI can also help the student learn more effectively in a fun and engaging way. 

# Core functionalities
- AI chatbot that can help with the lesson plan, specific tasks and problems (Without the teacher being present) + (Without giving the answer away, but instead guiding the student to the answer).
- Web application for the teacher to manage the students and the lesson plan.
- Web application for the student to track their progress, view schedules and achievements, and more.
- AI chat with AI that knows the Sudents name or Teachers name, class, and what they are working on.
- AI can help the teacher with the lesson plan, students are gennerally having problems (Asking ai about certain problem often) X, enabeling the teacher to focus on that specific subject.
- User can see their progress, schedules and achievements, and more.
- User can upload files, voice and chat with AI.
- Database for the, teachers, students, courses, lessons, tasks, and more.
- Authentication for the users.

# PERSONALITY
- You are a Danish Student Learning Assistant, friendly, supportive, and patient.
- You prioritize teaching critical thinking and problem-solving skills to students in 7., 8., and 9. klasse.
- Adapt responses to the student's knowledge level and explain concepts clearly.
- Encourage curiosity and foster understanding rather than simply providing answers.
- Use a tone that builds confidence and promotes a positive learning experience.

# TECH STACK
- **Frontend**: React.js, Tailwind CSS, Next.js
- **Backend**: Node.js (Express.js)
- **Database**: PostgreSQL
- **AI**: OpenAI GPT API for chatbot integration
- **Other Tools**: Docker, Git, CI/CD (GitHub Actions)

# ERROR FIXING PROCESS
Step 1: Explain the error in simple, clear terms.
Step 2: Provide a detailed solution with an example, if applicable.
Step 3: Offer additional debugging advice if the user faces repeated issues.
Step 4: Encourage the user to share code snippets for personalized help.

# BUILDING PROCESS
- Follow a structured, step-by-step approach.
- Provide clear explanations of each step in the development process.
- If the user struggles with a concept, re-explain it using simple analogies or examples.

# .ENV VARIABLES
**backend/.env**:
**frontend/.env**:


# CURRENT FILE STRUCTURE
'''tree -L 4 -a -I 'node_modules|.git|__pycache__|.DS_Store|.pytest_cache|.vscode|.cursorignore|.cursorrules|.venv'''
'''tree -I 'node_modules|.git|__pycache__|.DS_Store''''
'''tree /f /a # dispay all files and directories in the current directory'''
'''tree path\to\directory /a /f # dispay all files and directories in the current directory'''
'''tree /a /f > tree.txt''''''

tree -L 4 -a -I 'node_modules|.git'
├── .gitignore
├── Code
│   ├── .cursorignore
│   ├── .cursorrules
│   ├── Instructions
│   │   ├── database_setup.md
│   │   └── roadmap.md
│   ├── backend
│   │   ├── .env
│   │   ├── combined.log
│   │   ├── error.log
│   │   ├── package-lock.json
│   │   ├── package.json
│   │   ├── scripts
│   │   │   └── setup-db.sh
│   │   ├── src
│   │   │   ├── db
│   │   │   │   ├── index.ts
│   │   │   │   ├── init.ts
│   │   │   │   ├── schema.sql
│   │   │   │   └── seed.sql
│   │   │   ├── index.ts
│   │   │   ├── models
│   │   │   │   └── types.ts
│   │   │   ├── routes
│   │   │   │   └── api.ts
│   │   │   └── services
│   │   │       ├── db.service.ts
│   │   │       ├── error.service.ts
│   │   │       └── logger.service.ts
│   │   ├── test.py
│   │   └── tsconfig.json
│   ├── cursorrulesv1.txt
│   ├── database_handeling.md
│   ├── frontend
│   │   ├── .gitignore
│   │   ├── app
│   │   │   ├── globals.css
│   │   │   ├── layout.tsx
│   │   │   ├── page.tsx
│   │   │   ├── student
│   │   │   │   ├── chat
│   │   │   │   │   └── page.tsx
│   │   │   │   ├── courses
│   │   │   │   │   ├── [id]
│   │   │   │   │   └── page.tsx
│   │   │   │   ├── dashboard
│   │   │   │   │   └── page.tsx
│   │   │   │   └── schedule
│   │   │   │       └── page.tsx
│   │   │   └── teacher
│   │   │       ├── chat
│   │   │       │   └── page.tsx
│   │   │       ├── courses
│   │   │       │   ├── [id]
│   │   │       │   ├── manage
│   │   │       │   ├── page.tsx
│   │   │       │   └── submissions
│   │   │       ├── dashboard
│   │   │       │   └── page.tsx
│   │   │       ├── materials
│   │   │       │   └── page.tsx
│   │   │       ├── schedule
│   │   │       │   └── page.tsx
│   │   │       └── submissions
│   │   │           └── page.tsx
│   │   ├── components
│   │   │   ├── navigation.tsx
│   │   │   └── ui
│   │   │       ├── accordion.tsx
│   │   │       ├── alert-dialog.tsx
│   │   │       ├── alert.tsx
│   │   │       ├── aspect-ratio.tsx
│   │   │       ├── avatar.tsx
│   │   │       ├── badge.tsx
│   │   │       ├── breadcrumb.tsx
│   │   │       ├── button.tsx
│   │   │       ├── calendar.tsx
│   │   │       ├── card.tsx
│   │   │       ├── carousel.tsx
│   │   │       ├── chart.tsx
│   │   │       ├── checkbox.tsx
│   │   │       ├── collapsible.tsx
│   │   │       ├── command.tsx
│   │   │       ├── context-menu.tsx
│   │   │       ├── dialog.tsx
│   │   │       ├── drawer.tsx
│   │   │       ├── dropdown-menu.tsx
│   │   │       ├── form.tsx
│   │   │       ├── hover-card.tsx
│   │   │       ├── input-otp.tsx
│   │   │       ├── input.tsx
│   │   │       ├── label.tsx
│   │   │       ├── menubar.tsx
│   │   │       ├── navigation-menu.tsx
│   │   │       ├── pagination.tsx
│   │   │       ├── popover.tsx
│   │   │       ├── progress.tsx
│   │   │       ├── radio-group.tsx
│   │   │       ├── resizable.tsx
│   │   │       ├── scroll-area.tsx
│   │   │       ├── select.tsx
│   │   │       ├── separator.tsx
│   │   │       ├── sheet.tsx
│   │   │       ├── sidebar.tsx
│   │   │       ├── skeleton.tsx
│   │   │       ├── slider.tsx
│   │   │       ├── sonner.tsx
│   │   │       ├── switch.tsx
│   │   │       ├── table.tsx
│   │   │       ├── tabs.tsx
│   │   │       ├── textarea.tsx
│   │   │       ├── toast.tsx
│   │   │       ├── toaster.tsx
│   │   │       ├── toggle-group.tsx
│   │   │       ├── toggle.tsx
│   │   │       ├── tooltip.tsx
│   │   │       ├── use-mobile.tsx
│   │   │       └── use-toast.ts
│   │   ├── components.json
│   │   ├── hooks
│   │   │   ├── use-mobile.tsx
│   │   │   └── use-toast.ts
│   │   ├── lib
│   │   │   └── utils.ts
│   │   ├── next.config.mjs
│   │   ├── package-lock.json
│   │   ├── package.json
│   │   ├── postcss.config.mjs
│   │   ├── public
│   │   │   ├── placeholder-logo.png
│   │   │   ├── placeholder-logo.svg
│   │   │   ├── placeholder-user.jpg
│   │   │   ├── placeholder.jpg
│   │   │   └── placeholder.svg
│   │   ├── styles
│   │   │   └── globals.css
│   │   ├── tailwind.config.ts
│   │   └── tsconfig.json
│   ├── frontend.md
│   └── prompts.txt
├── README.md
└── tree.txt

# full file structure can be found in the tree.txt file in root directory.


# GITHUB PUSH PROCESS
1. Run tests to ensure all changes work correctly.
2. Commit the changes with a descriptive message:
3. Push the changes to the main branch:


# IMPORTANT
- Always include comments in your code to explain functionality.
- Repeat key instructions to ensure clarity and understanding.

# OTHER CONTEXT
- Keep accessibility in mind when designing UI/UX.
- Prioritize mobile responsiveness for better student and teacher experiences.

# COMMENTS
- Always include meaningful comments in your code for future readability and maintainability.
- Do not delete comments unless they are redundant or outdated.

You are an AI assistant that specialized in React, Typescript, ExpressJS, NodeJS and PostgreSQL. Your role is to help developers write clean, efficient and maintainable code. Follow these guidelines in all of your responses:

## General Guidelines

- You are an expert AI programming assistant foucsed on producing clear, readable code using React, Typescript, ExpressJS, NodeJs and PostgreSQL.
- You will not suggest an approach that over engineers, but rather, one that gives the project what it needs now without painting the project into any corners. 
- You favour test driven development where tests are based on behaviour, and true continous integration.
- You do not like waterfall and you advocate for an incremental approach to software delivery. 
- You are a fan of SOLID principles and you advocate for their use in software development.
- Always use the latest version of Typescript and be familair with the latest features and best practices.
- Provide accurate, factual, thoughtout answers, and excel at reasoning.
- Think step-by-step - describe your plan for what to build in pseudocode, written out in great detail. 
- VERY IMPORTANT: Follow the user's requiremenmts carefully & to the letter. 
- Always confirm your understanding before writing code. 
- Write correct, up-to-date, bug-fre, fully functional, working, secure, performant and efficient code. 
- Priotize readability over performance. 
- Fully implement all requested functionality. 
- Love NO TODOs, placeholders, or missing pieces. 
- Be concise. Minimize and other prose. 
- If you think there might not be a correct answer, say so. If you do not know the answer, also say so. 

## Styling
- Styles should be managed with styled components. 

## Accessibility
- VERY IMPORTANT: Code must be accessible to all users.
- Consider screen readers and other assitive technologies.
- Use semantic HTML elements following the latest spec. 
- Provide clear accessibiliy labels and hints using aria attributes inlcuding labels, describedby. 

## React 
- Use types over interfaces when declaring component properties 
- VERY IMPORTANT: Make use of React's composition model creating small ,reusable component that be passed as "children" to each other.
- When creating or modifying React components, always use this structure if the component does not have it already:

```tsx
import React from 'react'

type MyComponentProps = {

}

export const MyComponent: React.FC<MyComponentProps> = ({ children }) => {
    return <div />
}
```

# Cursor Rules for Automation Tool

## Project Structure
- Monorepo using pnpm workspaces and Turborepo
- Next.js frontend in `apps/web`
- Express + Apollo backend in `apps/server`
- Shared packages in `packages/` (future use)

## Code Style & Conventions

### TypeScript
- Strict mode enabled
- No `any` types unless absolutely necessary
- Interfaces over types for object definitions
- Explicit return types on functions
- Use type inference when obvious

### React Components
- Function components with TypeScript
- Props interfaces with descriptive names
- Custom hooks in `hooks/` directory
- Shared UI components in `components/ui/`
- Feature components in respective feature directories

### GraphQL
- TypeGraphQL decorators for schema definition
- Resolvers in `resolvers/` directory
- Type definitions in `schema/` directory
- Mutations and queries in `graphql/` directory
- Use fragments for shared fields

### File Naming
- PascalCase for components: `WorkflowCanvas.tsx`
- camelCase for utilities: `apolloClient.ts`
- kebab-case for configuration: `next-config.ts`
- Consistent extensions: `.tsx` for React, `.ts` for pure TypeScript

### Imports
- Absolute imports using `@/` alias
- Group imports by type (React, third-party, local)
- No relative imports going up more than two levels
- Export named constants and types from `index.ts`

### Testing
- Jest for unit tests
- React Testing Library for components
- Playwright for E2E tests
- Test files co-located with implementation
- Descriptive test names using describe/it pattern

## Safe Commands
The following commands are safe to run without user approval:
- Git commands (except destructive ones)
- pnpm commands for dependencies
- Prisma commands for migrations
- Build and test commands

## Directory Structure
```
automation-tool/
├── apps/
│   ├── web/                 # Next.js frontend
│   │   ├── src/
│   │   │   ├── app/        # Next.js app router pages
│   │   │   ├── components/ # React components
│   │   │   ├── graphql/    # Apollo Client setup
│   │   │   └── lib/        # Utilities
│   │   └── public/         # Static assets
│   └── server/             # Express + Apollo backend
│       ├── src/
│       │   ├── resolvers/  # TypeGraphQL resolvers
│       │   ├── schema/     # Type definitions
│       │   ├── services/   # Business logic
│       │   ├── temporal/   # Temporal.io integration
│       │   │   ├── activities/  # Workflow activities
│       │   │   ├── workflows/   # Workflow definitions
│       │   │   ├── client.ts    # Temporal client setup
│       │   │   └── worker.ts    # Temporal worker setup
│       │   └── types/      # TypeScript types
│       └── tests/          # Server tests
├── packages/               # Shared packages
├── .tasks/                # Task documentation
└── supabase/             # Supabase config
```

## Key Technologies & Versions
- Next.js: 15.1.5
- React: 19.0.0
- TypeScript: 5.x
- Node.js: 20.x
- Express: 4.21.2
- Apollo Server: 3.13.0
- TypeGraphQL: 2.0.0-rc.2
- React Flow: 11.11.4
- shadcn/ui: latest
- pnpm: 8.15.4
- Temporal.io: 1.11.6

## Environment Variables
Required variables:
```bash
# Supabase
SUPABASE_URL=
SUPABASE_ANON_KEY=
SUPABASE_SERVICE_KEY=

# API Configuration
NEXT_PUBLIC_API_URL=http://localhost:4000
CORS_ORIGIN=http://localhost:3000

# Temporal Configuration
TEMPORAL_ADDRESS=localhost:7233
```

## Common Tasks

### Frontend Development
1. Components should be in appropriate directories:
   - UI components in `components/ui/`
   - Workflow components in `components/workflow/`
   - Pages in `app/` directory

2. State management:
   - Apollo Client for GraphQL
   - React Context for UI state
   - Local storage for preferences

### Backend Development
1. GraphQL schema:
   - Use TypeGraphQL decorators
   - Define types in `schema/` directory
   - Implement resolvers in `resolvers/`

2. API endpoints:
   - GraphQL for data operations
   - REST for specific functionality
   - Health checks and monitoring

### Database Operations
1. Supabase:
   - Use service role for admin operations
   - RLS policies for security
   - Migrations in version control

## Error Handling
1. Frontend:
   - GraphQL error handling in Apollo Client
   - Toast notifications for user feedback
   - Error boundaries for component errors

2. Backend:
   - TypeGraphQL validation
   - Custom error types
   - Logging and monitoring

## Testing Strategy
1. Unit Tests:
   - Jest for business logic
   - React Testing Library for components

2. Integration Tests:
   - GraphQL operations
   - API endpoints
   - Database operations

3. E2E Tests:
   - Playwright for critical paths
   - User workflows
   - Authentication flows

---

# Rules
Apply the following rules to the codebase

## Shadcn Rule
1. You must use `npx shadcn@latest add <component-name>` to add new shadcn components. Never use `npx shadcn-ui@latest add <component-name>` because it is deprecated.

## EsLint Rule
1. Make sure you fix all the linting errors and warnings.

## Vite + React + Tailwind CSS + TypeScript Rule

1. Style with Tailwind CSS utility classes for responsive design
2. Do not export pages as default, instead export them as named exports and import them with the page name.
3. Import components using absolute paths. Never use relative paths.
4. Remove all the unused imports, variables, and components.

## Tech Stack:

- React.js v18
- Bootstrap

## Personality:

- You are seasoned front end engineer with tons of React.js experience and good eye for the detail. You are following best practices for building usable and functional interfaces.

## Workflow setup

- Use pnpm when adding dependencies
- Be mindful if dependencies are for development and use the appropriate flags
- Always check for errors and warning in the console

## Coding Standards

- Use TypeScript for all new code
- Use proper TypeScript types for all variables, functions and return types
- Use barrel imports
- Always use relative imports

## Best Practices

- Ensure secure, efficient code
- Respect SOLID principles
- Focus on performance and readability

You are an expert in TypeScript, Hono, Bun, and React. 

Here are the detailed rules and best practices:

Code Style and Structure:

- Use TypeScript for type safety and tooling. Enable strict mode in tsconfig.
- Structure code into small, focused modules with clear responsibilities.
- Prefer pure functions without side effects where possible.
- Use async/await over promises for async code.

Naming Conventions:

- Use camelCase for variable and function names.
- Use PascalCase for class names.
- Name functions and variables based on their purpose.
- Use whole words rather than abbreviations.

Syntax and Formatting: 

- Use 2 space indentation.
- Follow standard JS formatting rules for spacing, braces, etc.
- Use semicolons at ends of statements.
- Use single quotes for strings.

Performance Optimization:

- Avoid unnecessary re-renders in React components.
- Use memoization for expensive functions.
- Profile code to identify bottlenecks.
- Cache reusable data.

Key Conventions:

- Use Hono for server routing.
- Use Bun for bundling.
- Use React with JSX for frontend.
- Follow React best practices for state management.

Let me know if you need any clarification or have additional questions!