Cursor rule

1---
2description: Architectural Decision Records
3globs:
4alwaysApply: false
5---
6 
7# Architecture Decision Log
8 
9<!--
10ADR_AGENT_PROTOCOL v1.0
11 
12You (the agent) manage this file as the single source of truth for all ADRs.
13 
14INVARIANTS
15- Keep this exact file structure and headings.
16- All ADR entries use H2 headings: "## ADR-XXXX — <Title>" (4-digit zero-padded ID).
17- Allowed Status values: Proposed | Accepted | Superseded
18- Date format: YYYY-MM-DD
19- New entries must be appended to the END of the file.
20- The Index table between the INDEX markers must always reflect the latest state and be sorted by ID desc (newest on top).
21- Each ADR MUST contain: Date, Status, Owner, Context, Decision, Consequences.
22- Each ADR must include an explicit anchor `<a id="adr-XXXX"></a>` so links remain stable.
23 
24HOW TO ADD A NEW ADR
251) Read the whole file.
262) Compute next ID:
27   - Scan for headings matching: ^## ADR-(\d{4}) — .+$
28   - next_id = (max captured number) + 1, left-pad to 4 digits.
293) Create a new ADR section using the “New ADR Entry Template” below.
30   - Place it AFTER the last ADR section in the file.
31   - Add an `<a id="adr-XXXX"></a>` line immediately below the heading.
324) Update the Index (between the INDEX markers):
33   - Insert/replace the row for this ADR keeping the table sorted by ID descending.
34   - Title in the Index MUST link to the anchor: [<Title>](#adr-XXXX)
35   - If this ADR supersedes another: set “Supersedes” in this row, and update that older ADR:
36       a) Change its Status to “Superseded”
37       b) Add “Superseded by: ADR-XXXX” in its Consequences block
38       c) Update the older ADR’s Index row “Superseded by” column to ADR-XXXX
395) Validate before saving:
40   - Exactly one heading exists for ADR-XXXX
41   - All required fields are present and non-empty
42   - Index contains a row for ADR-XXXX and remains properly sorted
436) Concurrency resolution:
44   - If a merge conflict or duplicate ID is detected after reading: recompute next_id from the current file state, rename your heading, anchor, and Index row accordingly, and retry once.
45 
46COMMIT MESSAGE SUGGESTION
47- "ADR-XXXX: <Short Title> — <Status>"
48 
49END ADR_AGENT_PROTOCOL
50-->
51 
52## Index
53 
54<!-- BEGIN:ADR_INDEX -->
55 
56| ID  | Title                                        | Date       | Status   |
57| --- | -------------------------------------------- | ---------- | -------- |
58| 009 | Testing Strategy - Firebase Emulator Support | 2024-08-23 | Accepted |
59| 008 | TypeScript Configuration                     | 2024-08-23 | Accepted |
60| 007 | Project Structure - Essential Files Only     | 2024-08-23 | Accepted |
61| 006 | Hook Patterns - Status Enum Approach         | 2024-08-23 | Accepted |
62| 005 | Firebase Initialization Strategy             | 2024-08-23 | Accepted |
63| 004 | Form Handling - React Hook Form + Yup        | 2024-08-23 | Accepted |
64| 003 | Firebase Security - Remove App Check         | 2024-08-23 | Accepted |
65| 002 | State Management - React Context over Jotai  | 2024-08-23 | Accepted |
66 
67<!-- END:ADR_INDEX -->
68 
69## ADR-002: State Management - React Context over Jotai
70 
71**Status:** Accepted  
72**Date:** 2024-08-23
73 
74### Context
75 
76The original codebase used Jotai for state management, but we needed to simplify the template for broader adoption.
77 
78### Decision
79 
80Use React Context API instead of Jotai atoms for authentication state management.
81 
82### Rationale
83 
84- Reduces external dependencies
85- Built into React - no additional learning curve
86- Sufficient for authentication state needs
87- Easier to understand for developers new to the codebase
88- Maintains compatibility with existing patterns
89 
90### Consequences
91 
92- Less performant than Jotai for complex state scenarios
93- More boilerplate code required
94- Limited to simple state management patterns
95 
96---
97 
98## ADR-003: Firebase Security - Remove App Check
99 
100**Status:** Accepted  
101**Date:** 2024-08-23
102 
103### Context
104 
105App Check with reCAPTCHA was included in the original setup but adds complexity to the template.
106 
107### Decision
108 
109Remove Firebase App Check and reCAPTCHA integration from the template.
110 
111### Rationale
112 
113- Simplifies initial setup and development
114- Reduces dependencies
115- App Check can be added later when needed for production
116- Template focuses on core functionality
117- Easier testing during development
118 
119### Consequences
120 
121- Less security protection out of the box
122- Users need to implement App Check separately for production
123- Potential for abuse during development phase
124 
125---
126 
127## ADR-004: Form Handling - React Hook Form + Yup
128 
129**Status:** Accepted  
130**Date:** 2024-08-23
131 
132### Context
133 
134Forms are essential for authentication and data input in web applications.
135 
136### Decision
137 
138Use React Hook Form with Yup for validation.
139 
140### Rationale
141 
142- Performance benefits from uncontrolled components
143- Built-in validation support
144- TypeScript integration
145- Minimal re-renders
146- Yup provides comprehensive validation schemas
147- Industry standard approach
148 
149### Consequences
150 
151- Additional dependencies to manage
152- Learning curve for form-specific patterns
153- More setup required for complex forms
154 
155---
156 
157## ADR-005: Firebase Initialization Strategy
158 
159**Status:** Accepted  
160**Date:** 2024-08-23
161 
162### Context
163 
164Firebase initialization needed to handle server-side rendering and missing credentials gracefully.
165 
166### Decision
167 
168Implement conditional Firebase initialization with fallback empty objects.
169 
170### Rationale
171 
172- Prevents SSR errors during build time
173- Graceful handling of missing credentials
174- Allows template to build successfully without Firebase setup
175- Clear error messages when credentials are missing
176 
177### Implementation
178 
179```typescript
180let firebaseApp: FirebaseApp | undefined;
181if (FIREBASE_CONFIG.apiKey) {
182  firebaseApp = initializeApp(FIREBASE_CONFIG);
183}
184export const auth = firebaseApp ? getAuth(firebaseApp) : ({} as Auth);
185```
186 
187### Consequences
188 
189- Additional conditional checks required
190- Potential runtime errors if Firebase methods are called without proper initialization
191- More complex initialization logic
192 
193---
194 
195## ADR-006: Hook Patterns - Status Enum Approach
196 
197**Status:** Accepted  
198**Date:** 2024-08-23
199 
200### Context
201 
202Needed consistent patterns for data fetching hooks across the application.
203 
204### Decision
205 
206Use status enum (`"loading" | "error" | "success"`) pattern instead of separate boolean states.
207 
208### Rationale
209 
210- Matches existing codebase patterns
211- Prevents impossible states (loading + error)
212- More maintainable than multiple boolean flags
213- Clear state transitions
214- Better TypeScript inference
215 
216### Implementation
217 
218```typescript
219const [status, setStatus] = useState<"loading" | "error" | "success">(
220  "loading"
221);
222```
223 
224### Consequences
225 
226- Consistent with existing codebase
227- Easier state management
228- Clear separation of loading states
229 
230---
231 
232## ADR-007: Project Structure - Essential Files Only
233 
234**Status:** Accepted  
235**Date:** 2024-08-23
236 
237### Context
238 
239Template needed to be minimal while providing complete Firebase integration.
240 
241### Decision
242 
243Include only essential files for Firebase integration and authentication.
244 
245### Included Components
246 
247- Firebase services (auth, firestore, storage, functions)
248- Authentication system with React Context
249- Basic pages (home, signin, signup, dashboard)
250- Essential hooks for data fetching
251- Material-UI theme configuration
252 
253### Excluded Components
254 
255- Complex state management solutions
256- Advanced routing patterns
257- Non-essential UI components
258- Advanced Firebase features (Analytics, Remote Config, etc.)
259 
260### Rationale
261 
262- Faster onboarding for new projects
263- Easier to understand and modify
264- Reduces maintenance burden
265- Clear separation of concerns
266 
267### Consequences
268 
269- May require additional setup for complex applications
270- Users need to add advanced features themselves
271- More opinionated structure
272 
273---
274 
275## ADR-008: TypeScript Configuration
276 
277**Status:** Accepted  
278**Date:** 2024-08-23
279 
280### Context
281 
282Template needed strong typing for Firebase operations and React components.
283 
284### Decision
285 
286Use strict TypeScript configuration with comprehensive type definitions.
287 
288### Features
289 
290- Strict mode enabled
291- Custom type definitions for Firebase documents
292- Proper interface definitions for hooks
293- Type-safe Firebase operations
294 
295### Rationale
296 
297- Better developer experience
298- Compile-time error catching
299- Self-documenting code
300- Industry best practices
301 
302### Consequences
303 
304- Steeper learning curve for JavaScript developers
305- More verbose code in some cases
306- Additional type maintenance required
307 
308---
309 
310## ADR-009: Testing Strategy - Firebase Emulator Support
311 
312**Status:** Accepted  
313**Date:** 2024-08-23
314 
315### Context
316 
317Development and testing needed to work without affecting production Firebase resources.
318 
319### Decision
320 
321Include Firebase emulator configuration for local development.
322 
323### Implementation
324 
325- Emulator configuration in firebase.json
326- Environment-based Firebase initialization
327- Test mode Firestore rules
328 
329### Rationale
330 
331- Safe local development
332- Faster iteration cycles
333- Cost-effective testing
334- Offline development capability
335 
336### Consequences
337 
338- Additional setup required
339- Emulator-specific behaviors may differ from production
340- Need to manage emulator lifecycle
341 
342---
343 
344## Future ADRs
345 
346The following decisions may be documented in future ADRs:
347 
348- Authentication provider selection
349- Deployment strategy
350- Error handling patterns
351- Performance optimization approaches
352- Security rule implementations
353- Monitoring and analytics integration
354