158 lines
10 KiB
Plaintext
158 lines
10 KiB
Plaintext
# 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.
|
||
|
||
|
||
────────────────────────────────────────
|
||
Group 6 – Accessibility, UI, and Styling Guidelines (Updated)
|
||
────────────────────────────────────────
|
||
1. Sidebar Styling:
|
||
• The sidebar is implemented in the authenticated layout via the AsideMenu component, with the actual element defined in AsideMenuLayer (located at frontend/src/components/AsideMenuLayer.tsx) as an <aside> element with id="asideMenu".
|
||
• When modifying sidebar styles, target #asideMenu and its child elements rather than generic selectors (e.g., avoid .app-sidebar) to ensure that the changes affect the actual rendered sidebar.
|
||
• Remove or override any conflicting background utilities (such as an unwanted bg-white) so our desired background color (#F8F4E1) is fully visible. Use a highly specific selector if necessary, e.g.,
|
||
#asideMenu {
|
||
background-color: #F8F4E1 !important;
|
||
}
|
||
• Adjust spacing (padding/margins) at both the container (#asideMenu) and the individual menu item level to maintain a consistent, compact design.
|
||
|
||
2. General Project Styling and Tailwind CSS Usage:
|
||
• The application leverages Tailwind CSS extensively, with core styling defined in _theme.css using the @apply directive. Any new modifications should follow this pattern to ensure consistency.
|
||
• The themed blocks (like .theme-pink and .theme-green) standardize the UI’s appearance. When applying custom overrides, ensure they integrate cleanly into these structures and avoid conflicts or circular dependency errors (e.g., issues when redefining utilities such as text-blue-600).
|
||
• Adjustments via Tailwind CSS generally require modifying class names in the components and ensuring that global overrides are applied in the correct order. Consistent use of design tokens and custom color codes (e.g., #F8F4E1) throughout the app is crucial to a cohesive design.
|
||
• Specificity is key. If a change isn’t visually reflected as expected, inspect the rendered HTML to identify which classes are taking precedence.
|