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   | Supersedes | Superseded by |
57| ---- | ------------------------------------------------------------ | ---------- | -------- | ---------- | ------------- |
58| 0004 | [Event-Driven Broker Architecture with Firestore](#adr-0004) | 2025-01-27 | Accepted | —          | —             |
59| 0002 | [Monorepo Structure with Frontend and Backend](#adr-0002)    | 2025-01-27 | Accepted | —          | —             |
60| 0001 | [Full-Stack Firebase Template Architecture](#adr-0001)       | 2025-01-27 | Accepted | —          | —             |
61 
62<!-- END:ADR_INDEX -->
63 
64---
65 
66## New ADR Entry Template (copy for each new decision)
67 
68> Replace placeholders, keep section headers. Keep prose concise.
69 
70```
71 
72## ADR-XXXX — \<Short, specific title>
73 
74<a id="adr-XXXX"></a>
75**Date**: YYYY-MM-DD
76**Status**: Proposed | Accepted | Superseded
77**Owner**: <Name>
78 
79### Context
80 
81<1–3 sentences: what changed or what forces drive this decision now>
82 
83### Alternatives
84 
85<Quick bullet list of alternatives considered, and why they were rejected.>
86 
87### Decision
88 
89\<Single clear decision in active voice; make it testable/verifiable>
90 
91### Consequences
92 
93* **Pros**: \<benefit 1>, \<benefit 2>
94* **Cons / risks**: \<cost 1>, \<risk 1>
95* **Supersedes**: ADR-NNNN (if any)
96* **Superseded by**: ADR-MMMM (filled later if replaced)
97 
98### (Optional) Compliance / Verification
99 
100\<How we’ll check this is honored: tests, checks, fitness functions, runbooks>
101 
102```
103 
104---
105 
106## ADR-0001 — Full-Stack Firebase Template Architecture
107 
108<a id="adr-0001"></a>
109**Date**: 2025-01-27 `
110**Status**: Accepted  
111**Owner**: AI Agent
112 
113### Context
114 
115Modern web applications require both frontend and backend components with real-time data synchronization. Firebase provides a comprehensive platform for building full-stack applications, but setting up the architecture with best practices requires significant boilerplate code.
116 
117### Alternatives
118 
119- **Separate repositories**: Frontend and backend in different repos, harder to coordinate changes
120- **Backend-only template**: Covers only server-side concerns, developers must handle frontend integration
121- **Frontend-only template**: Limited to client-side Firebase SDK, missing serverless functions capabilities
122- **Full-stack monorepo template**: Single template with both Next.js frontend and Python Firebase Functions
123 
124### Decision
125 
126Create a comprehensive full-stack Firebase template with:
127 
128- Next.js 14 frontend with TypeScript and Material-UI
129- Python Firebase Functions backend with broker architecture pattern
130- Shared Firebase project configuration
131- Integrated testing strategy for both frontend and backend
132- Single repository with clear separation of concerns
133 
134### Consequences
135 
136- **Pros**: Complete starting point for Firebase projects, coordinated development, shared configuration
137- **Cons / risks**: More complex initial setup, larger template size, requires knowledge of both frontend and backend
138- **Supersedes**: —
139- **Superseded by**: —
140 
141### Compliance / Verification
142 
143Template includes working examples for both frontend and backend. Firebase configuration shared between components. Documentation covers full development workflow.
144 
145---
146 
147## ADR-0002 — Monorepo Structure with Frontend and Backend
148 
149<a id="adr-0002"></a>
150**Date**: 2025-01-27  
151**Status**: Accepted  
152**Owner**: AI Agent
153 
154### Context
155 
156Full-stack Firebase applications need coordinated development between frontend (Next.js) and backend (Firebase Functions). The question was how to organize the code structure to support both independent development and shared configuration.
157 
158### Alternatives
159 
160- **Separate repositories**: Independent versioning but coordination overhead and duplicate configuration
161- **Nested backend in frontend**: Simple structure but mixes concerns and complicates deployment
162- **Side-by-side monorepo**: Clear separation with shared root configuration
163 
164### Decision
165 
166Implement side-by-side monorepo structure:
167 
168- `/front/` - Next.js frontend application with its own package.json and dependencies
169- `/back/` - Python Firebase Functions backend with its own requirements.txt and structure
170- Root-level Firebase configuration (`firebase.json`, `firestore.rules`, `storage.rules`)
171- Shared documentation in root README.md with component-specific READMEs
172 
173### Consequences
174 
175- **Pros**: Clear separation of concerns, independent tooling, shared Firebase configuration, coordinated documentation
176- **Cons / risks**: Slightly more complex initial setup, need to manage two different development environments
177- **Supersedes**: —
178- **Superseded by**: —
179 
180### Compliance / Verification
181 
182Directory structure clearly separates frontend and backend. Firebase CLI recognizes backend functions source in configuration. Both components can be developed independently.
183 
184---
185 
186## ADR-0004 — Event-Driven Broker Architecture with Firestore
187 
188<a id="adr-0004"></a>
189**Date**: 2025-01-27  
190**Status**: Accepted  
191**Owner**: AI Agent
192 
193### Context
194 
195Modern full-stack applications require consistent data state between frontend and backend components. Traditional request-response patterns create tight coupling and require complex state synchronization logic. Real-time applications need immediate UI updates when data changes, regardless of the source of the change.
196 
197### Alternatives
198 
199- **Direct API communication**: Backend returns data directly to frontend, requires manual state management
200- **Event streaming with external broker**: Use services like Redis Pub/Sub or RabbitMQ, adds infrastructure complexity
201- **WebSocket connections**: Real-time but requires connection management and doesn't persist data
202- **Firestore as event-driven broker**: Leverages built-in real-time capabilities and acts as single source of truth
203 
204### Decision
205 
206Implement event-driven broker architecture where Firestore serves as both the data store and event broker:
207 
208- All data mutations flow through Firestore exclusively
209- Backend functions save data to Firestore without returning responses to frontend
210- Frontend subscribes to Firestore collections/documents using hooks for real-time updates
211- Firestore acts as the single source of truth for both backend and frontend
212- UI updates automatically through Firestore real-time listeners
213 
214### Consequences
215 
216- **Pros**: Eliminates data synchronization issues, automatic real-time updates, reduced coupling between frontend and backend, simplified state management, leverages Firebase's built-in capabilities
217- **Cons / risks**: Increased Firestore read operations, requires proper security rules design, potential data consistency challenges with complex operations, network dependency for all data access
218- **Supersedes**: —
219- **Superseded by**: —
220 
221### Compliance / Verification
222 
223Backend functions must only perform Firestore writes without returning data responses. Frontend components must use Firestore hooks (useFirestore, real-time listeners) for all data access. No direct API data responses to frontend. All data mutations trigger UI updates through Firestore change events.
224 
225---
226