# Cursor Rules - Group 1: Development Philosophy & Coding Conventions

1. Overall Architecture & Structure:
   - Enforce a clear separation of concerns between the backend (Express, Passport, Swagger-documented API routes, service layers, and configuration files) and the frontend (Next.js with React and TypeScript, using functional components, hooks, and proper layouts).
   - Ensure that backend modules (routes, services, helpers) and frontend components (pages, components, layouts) are organized for reusability and maintainability.

2. Coding Style & Formatting:
   - For the backend (JavaScript):
       • Use ES6+ features (const/let, arrow functions) consistently.
       • Follow Prettier and ESLint configurations (e.g., consistent 2-space indentation, semicolons, and single quotes).
       • Maintain clear asynchronous patterns with helper wrappers (e.g., wrapAsync) for error handling.
       • Document API endpoints with inline Swagger comments to ensure API clarity and consistency.
   - For the frontend (TypeScript/React):
       • Use functional components with strict typing and separation of concerns.
       • Follow naming conventions: PascalCase for components and types/interfaces, camelCase for variables, hooks, and function names.
       • Utilize hooks (useEffect, useState) to manage state and lifecycle in a clear and concise manner.

3. Code Quality & Best Practices:
   - Ensure code modularity by splitting complex logic into smaller, testable units (e.g., dedicated route handlers, service functions, and reusable UI components).
   - Write self-documenting code and add comments where the logic is non-trivial, especially for asynchronous operations.
   - Embrace declarative programming and adhere to SOLID principles, making sure that responsibilities are clearly delineated between layers.

4. Consistency & Tools Integration:
   - Leverage existing tools like Prettier and ESLint to automatically enforce style and formatting rules in both backend and frontend codebases.
   - Use TypeScript in the frontend to ensure type safety and catch errors early in the development cycle.
   - Maintain uniformity in API design and error handling strategies (e.g., consistent use of passport for authentication and common error handling middleware).
## Group 2 – Naming Conventions

1. File Naming and Structure:
   • Frontend:
     - Page Files: Use lower-case filenames (e.g., index.tsx) as prescribed by Next.js conventions.
     - Component Files: Use PascalCase for React component files (e.g., WebSiteHeader.tsx, NavBar.tsx).
     - Directories: Use clear, descriptive names (e.g., 'pages', 'components', 'WebPageComponents').
   • Backend:
     - Use lower-case filenames for modules (e.g., index.js, auth.js, projects.js).
     - When needed, use hyphenation for clarity, but maintain consistency.

2. Component and Module Naming:
   • Frontend:
     - React Components: Define components in PascalCase.
     - TypeScript Interfaces/Types: Use PascalCase (e.g., WebSiteHeaderProps).
   • Backend:
     - Classes (if any) and constructors should be in PascalCase; most helper functions and modules use camelCase.

3. Variable, Function, and Hook Naming:
   • Use camelCase for variables and function names in both frontend and backend (e.g., useAppSelector, handleMenuNavBarToggleClick, wrapAsync).
   • Custom Hooks: Prefix with ‘use’ (e.g., useAuth, useForm).

4. Consistency and Readability:
   • Maintain uniform naming across the project to ensure clarity and ease of maintenance.
## Group 3 – Frontend & React Best Practices

1. Use of Functional Components & TypeScript:
   • Build all components as functional components.
   • Leverage TypeScript for static type checking and enforce strict prop and state types.
   • Name components using PascalCase and define clear prop interfaces (e.g., WebSiteHeaderProps).

2. Effective Use of React Hooks:
   • Utilize useState and useEffect appropriately with proper dependency arrays.
   • Create custom hooks to encapsulate shared logic (e.g., useAppSelector).
   • Optimize performance with useCallback and useMemo where necessary.

3. Component Composition & Separation of Concerns:
   • Separate presentational (stateless) components from container components managing logic.
   • Use layout components (e.g., LayoutGuest) to encapsulate common page structures.
   • Keep components small, focused, and reusable.

4. Code Quality & Readability:
   • Maintain consistent formatting and adhere to Prettier and ESLint rules.
   • Use descriptive names for variables, functions, and components.
   • Document non-trivial logic with inline comments and consider implementing error boundaries where needed.
   • New code must adhere to these conventions to avoid ambiguity.
   • Use descriptive names that reflect the purpose and domain, avoiding abbreviations unless standard in the project.

## Group 4 – Backend & API Guidelines

1. API Endpoint Design & Documentation:
   • Follow RESTful naming conventions; all route handlers should be named clearly and consistently.
   • Document endpoints with Swagger annotations to provide descriptions, expected request bodies, and response codes.
   • Examples (for Auth endpoints):
       - POST /api/auth/signin/local
           • Description: Logs the user into the system.
           • Request Body (application/json):
               { "email": "admin@flatlogic.com", "password": "password" }
           • Responses:
               - 200: Successful login (returns token and user data).
               - 400: Invalid username/password supplied.
       - GET /api/auth/me
           • Description: Retrieves current authorized user information.
           • Secured via Passport JWT; uses req.currentUser.
           • Responses:
               - 200: Returns current user info.
               - 400: Invalid credentials or missing user data.
       - POST /api/auth/signup
           • Description: Registers a new user.
           • Request Body (application/json):
               { "email": "admin@flatlogic.com", "password": "password" }
           • Responses:
               - 200: New user signed up successfully.
               - 400: Invalid input supplied.
               - 500: Server error.

## Group 5 – Testing, Quality Assurance & Error Handling

1. Testing Guidelines:
   • Write unit tests for critical backend and frontend components using frameworks such as Jest, React Testing Library, and Mocha/Chai.
   • Practice test-driven development and maintain high test coverage.
   • Regularly update tests following changes in business logic.

2. Quality Assurance:
   • Enforce code quality with ESLint, Prettier, and static analysis tools.
   • Integrate continuous testing workflows (CI/CD) to catch issues early.
   • Ensure documentation is kept up-to-date with the implemented code.

3. Error Handling:
   • Back-end:
       - Wrap asynchronous route handlers with a helper (e.g., wrapAsync) to capture errors.
       - Use centralized error handling middleware (e.g., commonErrorHandler) for uniform error responses.
       - Verify the existence of req.currentUser in protected routes and return clear errors if authentication fails.
   • Front-end:
       - Implement error boundaries in React to gracefully handle runtime errors.
       - Display user-friendly error messages and log errors for further analysis.

2. Authentication & Security:
   • Protect endpoints by using Passport.js with JWT (e.g., passport.authenticate('jwt', { session: false })).
   • Ensure that secure routes check for existence of req.currentUser. If absent, return a ForbiddenError.

3. Consistent Error Handling & Middleware Usage:
   • Wrap asynchronous route handlers with helpers like wrapAsync for error propagation.
   • Use centralized error handling middleware (e.g., commonErrorHandler) to capture and format errors uniformly.

4. Modular Code Organization:
   • Organize backend code into separate files for routes, services, and database access (e.g., auth.js, projects.js, tasks.js).
   • Use descriptive, lowercase filenames for modules and routes.

5. Endpoint Security Best Practices:
   • Validate input data and sanitize requests where necessary.
   • Restrict sensitive operations to authenticated users with proper role-based permissions.