Cursor rule

1---
2alwaysApply: true
3---
4 
5# Next.js Firebase Template - Project Structure
6 
7This project follows a modular architecture pattern for Next.js applications with Firebase integration and Material-UI components.
8 
9## Folder Structure
10 
11### `src/` - Source Code
12 
13#### Core Directories
14 
15- **app/** - Next.js App Router
16  - **layout.tsx** - Root layout with providers
17  - **page.tsx** - Home page
18  - **(authenticated)/** - Protected routes (requires auth)
19  - **(public)/** - Public routes (signin, signup, etc.)
20  - **api/** - API routes (if needed)
21 
22- **components/** - Reusable UI Components
23  - **common/** - Shared components (LoadingScreen, SplashScreen, EmptyContent)
24  - **forms/** - Form components (LoadingButton, etc.)
25  - **guards/** - Authorization guards
26    - **AuthGuard/** - Protected route wrapper
27    - **GuestGuard/** - Public route wrapper
28  - **layouts/** - Layout components
29  - **ui/** - Basic UI components
30 
31- **sections/** - Page-specific sections
32  - Each page gets its own folder
33  - Complex components that are page-specific
34 
35- **lib/** - Core Libraries & Services
36  - **firebase.ts** - Firebase initialization
37  - **firestore.ts** - Firestore operations & collections
38  - **storage.ts** - Firebase Storage operations
39  - **functions.ts** - Firebase Functions calls
40 
41- **auth/** - Authentication System
42  - **AuthProvider.tsx** - Auth context provider
43  - **authContext.ts** - Context definition
44  - **authOperations.ts** - Auth functions (login, signup, etc.)
45  - **useAuth.ts** - Auth hook
46  - **types.ts** - Auth-related types
47 
48- **theme/** - MUI Theme Configuration
49  - **ThemeProvider.tsx** - Theme context provider
50  - **palette.ts** - Color definitions
51  - **typography.ts** - Font settings
52  - **components/** - Component overrides
53  - **customColors.ts** - Custom color definitions
54 
55- **hooks/** - Custom React Hooks
56  - **useFirestore.ts** - Firestore real-time subscriptions
57  - **useStorage.ts** - File upload/download hooks
58  - **useSnackbar.ts** - Notification hook
59  - **useResponsive.ts** - Responsive breakpoints
60 
61- **utils/** - Utility Functions
62  - **format.ts** - Data formatting
63  - **validation.ts** - Form validation
64  - **constants.ts** - App constants
65 
66- **types/** - TypeScript Definitions
67  - **firestore.ts** - Firestore document types
68  - **api.ts** - API response types
69  - **common.ts** - Shared types
70 
71### `public/` - Static Assets
72 
73- **images/** - Static images
74- **fonts/** - Custom fonts
75- **icons/** - Icon files
76 
77## Development Rules
78 
79### 1. Component Organization
80 
81- Keep components small and focused
82- Use composition over inheritance
83- Separate presentational and container components
84- Always export from index files for clean imports
85 
86### 2. State Management
87 
88- Use React Context for global state (auth, theme, settings)
89- Avoid Redux unless absolutely necessary
90- Use local state for component-specific data
91- Leverage Firebase real-time listeners for live data
92 
93### 3. Firebase Integration
94 
95- All Firestore operations through lib/firestore.ts
96- Define collection references as constants
97- Use TypeScript interfaces for document types
98- Implement proper error handling for all Firebase operations
99 
100### 4. Routing & Navigation
101 
102- Use Next.js App Router conventions
103- Group routes by authentication status
104- Implement proper loading states
105- Use Link component with href attribute
106- For MUI Link, use router.push
107 
108### 5. Theme & Styling
109 
110- Use MUI theme variables for all styling
111- Define custom colors in theme configuration
112- Use sx prop for component-specific styles
113- Maintain consistent spacing with theme.spacing()
114 
115### 6. Type Safety
116 
117- Define all data types in types/ directory
118- Use strict TypeScript configuration
119- Avoid 'any' type - use 'unknown' if necessary
120- Create proper interfaces for all Firebase documents
121 
122## Common Patterns
123 
124### Protected Route
125 
126```tsx
127// app/(authenticated)/layout.tsx
128export default function AuthenticatedLayout({ children }) {
129  return <AuthGuard>{children}</AuthGuard>;
130}
131```
132 
133### Firestore Collection Hook
134 
135```tsx
136// hooks/useCollection.ts
137export function useCollection(collectionName: string) {
138  const [data, setData] = useState([]);
139  const [loading, setLoading] = useState(true);
140 
141  useEffect(() => {
142    const unsubscribe = onSnapshot(
143      collection(db, collectionName),
144      (snapshot) => {
145        setData(
146          snapshot.docs.map((doc) => ({
147            id: doc.id,
148            ...doc.data(),
149          }))
150        );
151        setLoading(false);
152      }
153    );
154    return unsubscribe;
155  }, [collectionName]);
156 
157  return { data, loading };
158}
159```
160 
161## File Naming Conventions
162 
163- Components: PascalCase (e.g., `UserProfile.tsx`)
164- Hooks: camelCase with 'use' prefix (e.g., `useAuth.ts`)
165- Utils: camelCase (e.g., `formatDate.ts`)
166- Types: PascalCase for interfaces/types (e.g., `UserDoc`)
167- Constants: UPPER_SNAKE_CASE (e.g., `MAX_FILE_SIZE`)
168 
169## Import Order
170 
1711. React/Next.js imports
1722. Third-party libraries (MUI, Firebase, etc.)
1733. Absolute imports (@/ paths)
1744. Relative imports
1755. Type imports
176 
177Example:
178 
179```tsx
180import { useState, useEffect } from "react";
181import { Box, Button } from "@mui/material";
182import { collection, onSnapshot } from "firebase/firestore";
183import { useAuth } from "@/auth/useAuth";
184import { LoadingScreen } from "../components/LoadingScreen";
185import type { UserDoc } from "@/types/firestore";
186```
187