# Cursor Rules - Modular Template 2.0

## 🎯 Project Overview

Full-stack application template with multiple frontend technologies and backend services.

## 📁 Project Structure & Technology Stack

### Frontend Applications

- **frontend**: React 19 + TypeScript + Material-UI + Redux Toolkit + Craco

- **frontend1**: React 19 + TypeScript + Tailwind CSS + DaisyUI + TanStack Query + Vite

- **frontend2**: Astro 5 + TypeScript + Static Site Generation

- **frontend3**: Next.js 15 + React 19 + TypeScript + Tailwind CSS 4 + Turbopack

- **frontend4**: Vue 3 + TypeScript + Vite 7 + Vue Router 4 + Vitest

- **frontend5**: Angular 18 + TypeScript + RxJS

### Backend Services

- **backend**: FastAPI 2.0 + Python + SQLAlchemy 2.0 + PostgreSQL + Alembic

- **b4f**: Express 5 + TypeScript + Node.js + Prisma + PostgreSQL + Stripe

- **b4f1**: NestJS 11 + TypeScript + SWC + Jest + Express

### Utility Tools

- **numpy**: Python + OpenCV + Tesseract (OCR) + Pandas + Matplotlib

## 🚀 Development Workflow

### Before Making Changes

1. **Check containers status**: `docker compose ps` - ensure all services are running

2. **Verify services health**: Use health check commands if needed

3. **No restart needed**: Backend and frontend auto-restart on code changes

### Code Quality Checklist

1. **Check for existing functions** before writing new ones

2. **Place imports at the top** of files (never in the middle)

3. **Refactor after implementation** - test before and after

4. **Reuse existing code** instead of duplicating logic

### Change Analysis (Conditional)

- **Minor changes** (typos, comments, small fixes): Proceed directly

- **Significant changes** (new features, refactoring, architecture): Analyze 3 options

- **Critical changes** (auth, database, API): Always analyze + ask user

### Analysis Steps (When Required)

1. Scan codebase for current implementation

2. Identify affected components (models, services, APIs, frontend)

3. Consider database implications (migrations needed?)

4. Evaluate impact on existing functionality

### Post-Implementation Steps

1. **Test functionality** before refactoring

2. **Search for code duplication** in the codebase

3. **Extract common logic** into reusable functions/components

4. **Refactor to reuse existing code** where possible

5. **Test functionality** after refactoring to ensure nothing broke

6. **Add tests** for new functionality after refactoring

### Implementation Options (When Required)

- **Option 1**: Minimal changes, backward compatible

- **Option 2**: Moderate refactoring, improved architecture

- **Option 3**: Major refactoring, future-proof design

**Evaluation Criteria**: Maintainability | Performance | Scalability | Security | Testing

## 🗄️ Database & Migrations

### Migration Workflow (CRITICAL: Containers must be running)

```bash

# 1. Start containers

docker compose up --build

# 2. Verify database health

docker compose exec db pg_isready -U dev -d postgres

# 3. Create migration

docker compose exec backend uv run alembic revision --autogenerate -m "descriptive name"

# 4. Apply migration

docker compose exec backend uv run alembic upgrade head

# 5. Revert (if needed)

docker compose exec backend uv run alembic downgrade -1

```

### Migration Files

- `backend/alembic/versions/`: All migration files

- `backend/alembic/env.py`: Migration environment configuration

## 🎨 Frontend Development

### Frontend (React + Material-UI + Redux)

#### Component Standards (MANDATORY)

```typescript

interface ComponentNameProps {

requiredProp: string;

optionalProp?: number;

children?: ReactNode;

onAction: (value: string) => void;

}

const ComponentName: FC<ComponentNameProps> = ({

requiredProp,

optionalProp,

children,

onAction

}) => {

return (

<Box>

<Typography variant="h5">{requiredProp}</Typography>

<Button onClick={() => onAction('test')}>

Action

</Button>

</Box>

);

};

export default ComponentName;

```

#### Redux Best Practices

```typescript

// ✅ CORRECT - Redux Toolkit patterns

const userSlice = createSlice({

name: 'user',

initialState: {

data: null,

loading: false,

error: null

},

reducers: {

setLoading: (state, action) => {

state.loading = action.payload;

},

setUser: (state, action) => {

state.data = action.payload;

state.loading = false;

},

setError: (state, action) => {

state.error = action.payload;

state.loading = false;

}

}

});

// Async thunks

export const fetchUser = createAsyncThunk(

'user/fetchUser',

async (userId: string, { rejectWithValue }) => {

try {

const response = await api.get(`/users/${userId}`);

return response.data;

} catch (error) {

return rejectWithValue(error.message);

}

}

);

```

#### Material-UI Best Practices

```typescript

// ✅ CORRECT - Theme usage

const useStyles = makeStyles((theme) => ({

root: {

padding: theme.spacing(2),

[theme.breakpoints.down('sm')]: {

padding: theme.spacing(1),

},

},

}));

// ✅ CORRECT - Responsive design

<Grid container spacing={2}>

<Grid item xs={12} sm={6} md={4}>

<Card>Content</Card>

</Grid>

</Grid>

```

#### State Management

- **Global State**: Redux Toolkit

- **Local State**: React useState/useReducer

- **Server State**: Redux thunks + caching

### Frontend1 (React + Tailwind + DaisyUI + TanStack Query)

#### Component Standards (MANDATORY)

```typescript

interface ComponentNameProps {

requiredProp: string;

optionalProp?: number;

children?: ReactNode;

onAction: (value: string) => void;

}

const ComponentName: FC<ComponentNameProps> = ({

requiredProp,

optionalProp,

children,

onAction

}) => {

return (

<div className="card bg-base-100 shadow-lg">

<div className="card-body">

<h2 className="card-title">{requiredProp}</h2>

<button className="btn btn-primary" onClick={() => onAction('test')}>

Action

</button>

</div>

</div>

);

};

export default ComponentName;

```

#### TanStack Query Best Practices

```typescript

// Query key function

export const dataQueryKey = (filters?: DataFilters) => [

...QUERY_KEYS.DATA_ALL,

"data",

"endpoint",

{ filters: filters ?? {} },

] as const;

// Query hook

export function useDataQuery(

filters?: DataFilters,

options?: UseQueryOptions<DataResponse, Error, DataResponse>

) {

return useQuery<DataResponse>({

queryKey: dataQueryKey(filters),

queryFn: () => apiClient.post<DataResponse>(API_ENDPOINTS.DATA_ENDPOINT, {

...(filters ?? {}),

}),

staleTime: 60_000,

...options,

});

}

```

#### Tailwind CSS + DaisyUI Best Practices

```typescript

// ✅ CORRECT - DaisyUI components

<div className="card bg-base-100 shadow-xl">

<div className="card-body">

<h2 className="card-title">Card title</h2>

<p>Card description</p>

<div className="card-actions justify-end">

<button className="btn btn-primary">Action</button>

</div>

</div>

</div>

// ✅ CORRECT - Responsive design

<div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-4">

<div className="card">Content</div>

</div>

```

#### State Management

- **Server State**: TanStack Query

- **Local State**: React useState/useReducer

- **Global State**: Context API when needed

### Common Frontend Standards

#### TypeScript Code Standards

```typescript

// ✅ CORRECT - All imports at the top

import { FC, useState, useEffect } from "react";

import { useQuery } from "@tanstack/react-query";

import { apiClient } from "@/api/client";

import { API_ENDPOINTS } from "@/api/endpoints";

// ❌ WRONG - Imports in the middle of code

const Component: FC = () => {

import { useToast } from "@/hooks/useToast"; // Don't do this

return <div>Content</div>;

};

```

#### Internationalization

```typescript

const { t } = useTranslation("namespace");

// In JSX: <h1>{t("title")}</h1>

```

#### Code Reuse

- **Before writing new function**: Search existing components/hooks for similar functionality

- **Extract common logic**: Create custom hooks for repeated patterns

- **Refactor after implementation**: Test before and after refactoring

- **Component composition**: Reuse existing components instead of duplicating

## 🔧 Backend Development

### Backend (FastAPI + Python + SQLAlchemy)

#### API Endpoint Standards (MANDATORY)

```python

@router.get("/endpoint")

async def endpoint_name(

db: AsyncSession = Depends(get_async_db),

token: HTTPAuthorizationCredentials = Depends(security),

):

"""Endpoint description."""

await validate_token(token)

# Implementation

```

#### Authentication Patterns

- **User Endpoints**: `validate_token(token)` - validates JWT

- **Admin Endpoints**: `validate_token(token, permission_check=True)` - requires admin permission

- **Internal Endpoints**: `validate_internal_token(credentials)` - uses internal API token

#### Database Patterns

```python

# Always use async sessions

async def service_function(db: AsyncSession):

result = await db.execute(select(Model).where(Model.id == id))

return result.scalar_one_or_none()

# Always handle exceptions

try:

result = await some_operation()

except Exception as e:

logger.error(f"Operation failed: {e}")

raise HTTPException(status_code=500, detail="Operation failed")

```

#### Python Code Standards

```python

# ✅ CORRECT - All imports at the top

from fastapi import APIRouter, Depends

from sqlalchemy.orm import Session

from app.models import User

from app.schemas import UserCreate

# ❌ WRONG - Imports in the middle of code

def some_function():

from app.utils import helper # Don't do this

return helper()

```

#### Import Patterns (MANDATORY)

```python

# For non-__init__.py files:

from core import security, validate_token, get_async_db

from services import data_service, user_service

from utils import logger, format_filters

# For __init__.py files:

from models.users import User

from models.groups import Group

```

### B4F (Express + TypeScript + Node.js + Prisma)

#### Express Best Practices

```typescript

// ✅ CORRECT - Router structure

import { Router, Request, Response } from 'express';

import { body, validationResult } from 'express-validator';

const router = Router();

router.get('/users', async (req: Request, res: Response) => {

try {

const users = await prisma.user.findMany();

res.json(users);

} catch (error) {

res.status(500).json({ error: 'Internal server error' });

}

});

export default router;

```

#### TypeScript Standards

```typescript

// ✅ CORRECT - Interface definitions

interface User {

id: string;

email: string;

name: string;

createdAt: Date;

}

interface CreateUserRequest {

email: string;

name: string;

password: string;

}

// ✅ CORRECT - Type guards

function isUser(obj: any): obj is User {

return obj && typeof obj.id === 'string' && typeof obj.email === 'string';

}

```

#### Prisma Best Practices

```typescript

// ✅ CORRECT - Database operations

const user = await prisma.user.create({

data: {

email: '[email protected]',

name: 'John Doe',

},

select: {

id: true,

email: true,

name: true,

},

});

// ✅ CORRECT - Error handling

try {

const result = await prisma.user.findUnique({

where: { id: userId },

});

if (!result) {

throw new Error('User not found');

}

return result;

} catch (error) {

logger.error('Database error:', error);

throw error;

}

```

#### Middleware Patterns

```typescript

// ✅ CORRECT - Authentication middleware

export const authenticateToken = (req: Request, res: Response, next: NextFunction) => {

const authHeader = req.headers['authorization'];

const token = authHeader && authHeader.split(' ')[1];

if (!token) {

return res.status(401).json({ error: 'Access token required' });

}

jwt.verify(token, process.env.JWT_SECRET!, (err, user) => {

if (err) {

return res.status(403).json({ error: 'Invalid token' });

}

req.user = user;

next();

});

};

```

#### Error Handling

```typescript

// ✅ CORRECT - Global error handler

export const errorHandler = (

error: Error,

req: Request,

res: Response,

next: NextFunction

) => {

logger.error('Unhandled error:', error);

if (error instanceof ValidationError) {

return res.status(400).json({ error: error.message });

}

res.status(500).json({ error: 'Internal server error' });

};

```

### Common Backend Standards

#### Code Reuse Guidelines

- **Before writing new function**: Search existing codebase for similar functionality

- **Extract common logic**: Create utility functions for repeated patterns

- **Refactor after implementation**: Test before and after refactoring

- **DRY principle**: Don't Repeat Yourself - reuse existing code

### Frontend2 (Astro 5 + TypeScript)

#### Component Standards (MANDATORY)

```astro

---

// Component script (runs at build time)

interface Props {

title: string;

description?: string;

}

const { title, description = "Default description" } = Astro.props;

---

<div class="card">

<h2>{title}</h2>

{description && <p>{description}</p>}

</div>

<style>

.card {

@apply bg-white shadow-lg rounded-lg p-6;

}

</style>

```

#### Astro Best Practices

- **Static Generation**: Use Astro components for static content

- **Framework Components**: Use React/Vue/Svelte only when interactivity is needed

- **Zero JavaScript**: Default to no JS, add only when necessary

- **TypeScript**: Full TypeScript support with proper typing

- **CSS Scoping**: Component-scoped styles with `<style>`

- **Performance**: Optimize images and assets

### Frontend3 (Next.js 15 + React 19 + Turbopack)

#### Component Standards (MANDATORY)

```typescript

// app/components/ComponentName.tsx

import { type FC } from 'react';

interface ComponentNameProps {

title: string;

description?: string;

onAction: () => void;

}

const ComponentName: FC<ComponentNameProps> = ({

title,

description,

onAction

}) => {

return (

<div className="card bg-white shadow-lg rounded-lg p-6">

<h2 className="text-xl font-bold">{title}</h2>

{description && <p className="text-gray-600">{description}</p>}

<button

className="btn btn-primary"

onClick={onAction}

>

Action

</button>

</div>

);

};

export default ComponentName;

```

#### Next.js 15 Best Practices

- **App Router**: Use `app/` directory structure

- **Server Components**: Default to server components

- **Client Components**: Use `"use client"` only when needed

- **Turbopack**: Leverage for faster development builds

- **TypeScript**: Strict mode with proper typing

- **Tailwind CSS**: Utility-first styling approach

### Frontend4 (Vue 3 + Vite 7 + TypeScript)

#### Component Standards (MANDATORY)

```vue

<template>

<div class="card bg-white shadow-lg rounded-lg p-6">

<h2 class="text-xl font-bold">{{ title }}</h2>

<p v-if="description" class="text-gray-600">{{ description }}</p>

<button

class="btn btn-primary"

@click="onAction"

>

Action

</button>

</div>

</template>

<script setup lang="ts">

interface Props {

title: string;

description?: string;

onAction: () => void;

}

defineProps<Props>();

</script>

<style scoped>

.card {

@apply bg-white shadow-lg rounded-lg p-6;

}

</style>

```

#### Vue 3 Best Practices

- **Composition API**: Use `<script setup>` syntax

- **TypeScript**: Full TypeScript support with proper interfaces

- **Vite**: Leverage Vite 7 for fast development and building

- **Vue Router**: Use Vue Router 4 for client-side routing

- **Vitest**: Use Vitest for unit testing

- **Scoped Styles**: Use scoped styles for component isolation

### B4F1 (NestJS 11 + TypeScript + SWC)

#### Controller Standards (MANDATORY)

```typescript

import { Controller, Get, Post, Body, Param } from '@nestjs/common';

import { ApiTags, ApiOperation, ApiResponse } from '@nestjs/swagger';

import { DataService } from './data.service';

import { CreateDataDto } from './dto/create-data.dto';

@ApiTags('data')

@Controller('data')

export class DataController {

constructor(private readonly dataService: DataService) {}

@Get()

@ApiOperation({ summary: 'Get all data' })

@ApiResponse({ status: 200, description: 'Data retrieved successfully' })

async findAll() {

return this.dataService.findAll();

}

@Post()

@ApiOperation({ summary: 'Create new data' })

@ApiResponse({ status: 201, description: 'Data created successfully' })

async create(@Body() createDataDto: CreateDataDto) {

return this.dataService.create(createDataDto);

}

}

```

#### NestJS Best Practices

- **Modules**: Organize code into feature modules

- **Services**: Business logic in injectable services

- **Controllers**: Handle HTTP requests and responses

- **DTOs**: Use DTOs for data validation

- **Guards**: Authentication and authorization

- **Interceptors**: Transform data and handle side effects

- **Pipes**: Validation and transformation

- **Filters**: Exception handling

- **SWC**: Use SWC for faster compilation

## 🧪 Testing Guidelines

### Backend Testing (CRITICAL)

```python

# ✅ CORRECT - Test pure functions without auth

def test_calculation_function():

result = calculate_value(data)

assert result == expected

# ❌ WRONG - Don't test API endpoints without proper token

def test_api_endpoint():

response = client.get("/api/v1/endpoint") # Will fail without token

```

**For API endpoint testing, ask user to provide valid token or implement mock authentication.**

### Test Structure

- `backend/test/`: Backend tests

- `frontend/src/__tests__/`: Frontend tests

### Test Implementation Pattern

```python

# test/test_my_feature.py

import unittest

import sys

import os

# Add /app to Python path

sys.path.insert(0, '/app')

from app.my_module import my_function

class TestMyFeature(unittest.TestCase):

def test_my_function(self):

result = my_function("test")

self.assertEqual(result, "expected")

if __name__ == '__main__':

unittest.main()

```

### Test Execution Commands

```bash

# Run all tests

docker compose exec backend bash -c "cd /app && uv run python -m unittest discover test -v"

# Run specific test

docker compose exec backend bash -c "cd /app && uv run python test/test_my_feature.py"

# Run with coverage

docker compose exec backend bash -c "cd /app && uv run coverage run -m unittest discover test -v && uv run coverage report"

```

### Test Requirements

- **After implementing new functionality**: Always add corresponding tests

- **Use unittest**: More stable than pytest for this project

- **Test pure functions**: Focus on functions without external dependencies

- **Mock external dependencies**: Use unittest.mock when needed

- **One test per function**: Clear, focused test cases

## 🐳 Docker & Infrastructure

### Development Commands

```bash

# Check if containers are running first

docker compose ps

# Start all services (only if not running)

docker compose up --build

# Start specific service

docker compose up backend

# View logs

docker compose logs -f backend

# Execute commands

docker compose exec backend uv run python script.py

docker compose exec frontend yarn test

```

### Auto-Restart Behavior

- **Backend**: Auto-restarts on code changes (hot reload)

- **Frontend**: Auto-restarts on code changes (Vite dev server)

- **No manual restart needed** for development changes

- **Only rebuild** when changing dependencies or Docker configuration

### Health Checks

```bash

# Database

docker compose exec db pg_isready -U dev -d postgres

# Backend

curl http://localhost:8000/health

# Frontend

curl http://localhost:3000

```

## 🔐 Security Guidelines

### Authentication

- Never hardcode tokens in code

- Use environment variables for all secrets

- Validate all inputs with Pydantic models

- Implement proper CORS configuration

### Data Protection

- Sanitize user inputs before database operations

- Use parameterized queries (SQLAlchemy ORM handles this)

- Implement rate limiting for API endpoints

- Log security events appropriately

## 🚀 Performance Guidelines

### Frontend

- **Code Splitting**: Use React.lazy for route-based splitting

- **Memoization**: Use React.memo, useMemo, useCallback appropriately

- **Query Optimization**: Set appropriate staleTime and cacheTime

### Backend

- **Database Queries**: Use proper indexing and query optimization

- **Async Operations**: Use async/await throughout

- **Connection Pooling**: Configure database connection pools

## 📝 Code Quality Standards

### TypeScript

- **Strict Mode**: Always use strict TypeScript configuration

- **Type Definitions**: Define interfaces for all data structures

- **No Any Types**: Avoid `any` type, use proper typing

### Python

- **Type Hints**: Use type hints for all function parameters and returns

- **Pydantic**: Use Pydantic models for data validation

- **Async/Await**: Use async patterns consistently

## 🔄 Git Workflow

### Branch Naming

- `feature/description`: New features

- `fix/description`: Bug fixes

- `refactor/description`: Code refactoring

- `docs/description`: Documentation updates

### Commit Messages

```

type(scope): description

feat(api): add new endpoint

fix(frontend): resolve layout issue

refactor(backend): optimize database queries

```

## 🚨 Common Pitfalls to Avoid

### Frontend

- ❌ **Never use direct fetch** - always use React Query hooks

- ❌ **Don't bypass authentication** - always use proper auth flow

- ❌ **Avoid inline styles** - use CSS framework classes

- ❌ **Don't ignore TypeScript errors** - fix all type issues

### Backend

- ❌ **Never skip authentication** - all endpoints need auth

- ❌ **Don't ignore database migrations** - always create proper migrations

- ❌ **Avoid blocking operations** - use async/await

- ❌ **Don't hardcode configuration** - use environment variables

### Database

- ❌ **Never run migrations without containers running**

- ❌ **Don't ignore foreign key constraints**

- ❌ **Avoid N+1 queries** - use proper joins

- ❌ **Don't skip data validation** - validate all inputs

## 📊 Data Processing Guidelines

### File Processing

- **Supported Formats**: Define based on project needs

- **Validation**: Comprehensive data quality checks

- **Storage**: Use appropriate storage solution

### Job Management

- **Background Processing**: Use FastAPI BackgroundTasks

- **Status Tracking**: Implement job status tracking

- **Notifications**: Use appropriate notification system

- **Error Handling**: Comprehensive error logging

## 🎯 Project-Specific Patterns

### Data Visualization

- **Consistent Charts**: Use standardized chart components

- **Filter System**: Implement reusable filtering patterns

- **Real-time Updates**: Use appropriate real-time technology

- **Caching Strategy**: Implement appropriate caching

### User Interface

- **Component Library**: Use consistent component patterns

- **Responsive Design**: Mobile-first approach

- **Accessibility**: Follow accessibility guidelines

- **Internationalization**: Support multiple languages

### API Design

- **RESTful Patterns**: Follow REST conventions

- **Error Handling**: Consistent error response format

- **Documentation**: Auto-generate API documentation

- **Versioning**: Implement API versioning strategy

---

**Remember**: When in doubt, ask the user for clarification. Each project has specific business requirements and patterns that may not be immediately obvious from the code alone.