Cursor rule

1---
2description: Log of all the key backend architectural decisions.
3alwaysApply: false
4---
5 
6# Architecture Decision Log
7 
8<!--
9ADR_AGENT_PROTOCOL v1.0
10 
11You (the agent) manage this file as the single source of truth for all ADRs.
12 
13INVARIANTS
14- Keep this exact file structure and headings.
15- All ADR entries use H2 headings: "## ADR-XXXX — <Title>" (4-digit zero-padded ID).
16- Allowed Status values: Proposed | Accepted | Superseded
17- Date format: YYYY-MM-DD
18- New entries must be appended to the END of the file.
19- The Index table between the INDEX markers must always reflect the latest state and be sorted by ID desc (newest on top).
20- Each ADR MUST contain: Date, Status, Owner, Context, Decision, Consequences.
21- Each ADR must include an explicit anchor `<a id="adr-XXXX"></a>` so links remain stable.
22 
23HOW TO ADD A NEW ADR
241) Read the whole file.
252) Compute next ID:
26   - Scan for headings matching: ^## ADR-(\d{4}) — .+$
27   - next_id = (max captured number) + 1, left-pad to 4 digits.
283) Create a new ADR section using the “New ADR Entry Template” below.
29   - Place it AFTER the last ADR section in the file.
30   - Add an `<a id="adr-XXXX"></a>` line immediately below the heading.
314) Update the Index (between the INDEX markers):
32   - Insert/replace the row for this ADR keeping the table sorted by ID descending.
33   - Title in the Index MUST link to the anchor: [<Title>](#adr-XXXX)
34   - If this ADR supersedes another: set “Supersedes” in this row, and update that older ADR:
35       a) Change its Status to “Superseded”
36       b) Add “Superseded by: ADR-XXXX” in its Consequences block
37       c) Update the older ADR’s Index row “Superseded by” column to ADR-XXXX
385) Validate before saving:
39   - Exactly one heading exists for ADR-XXXX
40   - All required fields are present and non-empty
41   - Index contains a row for ADR-XXXX and remains properly sorted
426) Concurrency resolution:
43   - 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.
44 
45COMMIT MESSAGE SUGGESTION
46- "ADR-XXXX: <Short Title> — <Status>"
47 
48END ADR_AGENT_PROTOCOL
49-->
50 
51## Index
52 
53<!-- BEGIN:ADR_INDEX -->
54 
55| ID   | Title                                                     | Date       | Status   | Supersedes | Superseded by |
56| ---- | --------------------------------------------------------- | ---------- | -------- | ---------- | ------------- |
57| 0007 | [Test Fixture Cleanup Strategy](#adr-0007)                | 2025-01-27 | Accepted | —          | —             |
58| 0006 | [Automated Test Runner Implementation](#adr-0006)         | 2025-01-27 | Accepted | —          | —             |
59| 0005 | [Database Class Consolidation](#adr-0005)                 | 2025-01-27 | Accepted | —          | —             |
60| 0004 | [Real Firebase Emulators Over Mocked Services](#adr-0004) | 2025-01-27 | Accepted | —          | —             |
61| 0003 | [Test Utilities Organization in util/ Folder](#adr-0003)  | 2025-01-27 | Accepted | —          | —             |
62| 0002 | [Firebase Emulator Integration Pattern](#adr-0002)        | 2025-01-27 | Accepted | —          | —             |
63| 0001 | [Template Testing Strategy](#adr-0001)                    | 2025-01-27 | Accepted | —          | —             |
64 
65<!-- END:ADR_INDEX -->
66 
67---
68 
69## ADR-0001 — Template Testing Strategy
70 
71<a id="adr-0001"></a>
72**Date**: 2025-01-27  
73**Status**: Accepted  
74**Owner**: AI Agent
75 
76### Context
77 
78The Python Firebase template needed a robust testing strategy that supports both rapid development and comprehensive integration testing. Tests needed to work with and without Firebase emulators running.
79 
80### Alternatives
81 
82- **All tests require emulators**: Simple but slow for basic function logic testing
83- **Mock all Firebase services**: Fast but doesn't test real Firebase behavior
84- **Mixed approach with clear categorization**: Support both scenarios with proper documentation
85 
86### Decision
87 
88Implement a mixed testing strategy where tests are categorized by emulator requirements:
89 
90- Tests that only validate function logic can run without emulators
91- Integration tests that require database operations use real Firebase emulators
92- Clear documentation distinguishes between test types
93- Environment variable `SKIP_EMULATORS=true` allows bypassing emulator startup
94 
95### Consequences
96 
97- **Pros**: Fast feedback for logic tests, comprehensive integration testing, flexible CI/CD options
98- **Cons / risks**: Developers need to understand test categories, some complexity in setup
99- **Supersedes**: —
100- **Superseded by**: —
101 
102### Compliance / Verification
103 
104Tests documented in `tests/README.md` with clear examples. CI can run both modes: quick logic tests and full integration tests.
105 
106---
107 
108## ADR-0002 — Firebase Emulator Integration Pattern
109 
110<a id="adr-0002"></a>
111**Date**: 2025-01-27  
112**Status**: Accepted  
113**Owner**: AI Agent
114 
115### Context
116 
117The template needed reliable Firebase emulator management for integration testing. The existing github-app project had a proven pattern for emulator lifecycle management that should be adapted.
118 
119### Alternatives
120 
121- **Manual emulator management**: Developers start/stop emulators manually
122- **Test-level emulator fixtures**: Each test manages its own emulator instance
123- **Session-level emulator management**: Emulators start once per test session (github-app pattern)
124 
125### Decision
126 
127Adopt the github-app emulator pattern with session-level management:
128 
129- `tests/util/firebase_emulator.py` handles emulator lifecycle
130- Automatic port cleanup and process management
131- Configurable emulator services (functions, firestore, storage)
132- Robust timeout and error handling
133- Optional automatic startup with `setup_emulators` fixture
134 
135### Consequences
136 
137- **Pros**: Proven pattern, reliable cleanup, supports multiple emulator services, good error handling
138- **Cons / risks**: More complex than manual setup, requires Firebase CLI installation
139- **Supersedes**: —
140- **Superseded by**: —
141 
142### Compliance / Verification
143 
144Tests use `firebase_emulator` fixture. Emulator utilities must handle port conflicts and process cleanup. Pattern consistency with github-app project.
145 
146---
147 
148## ADR-0003 — Test Utilities Organization in util/ Folder
149 
150<a id="adr-0003"></a>
151**Date**: 2025-01-27  
152**Status**: Accepted  
153**Owner**: AI Agent
154 
155### Context
156 
157Test fixtures and utilities were mixed in `conftest.py`, making them harder to reuse and maintain. The `ItemFlowSetup` class and Firebase emulator utilities needed better organization for template users.
158 
159### Alternatives
160 
161- **Keep everything in conftest.py**: Simple but becomes unwieldy
162- **Split by functionality**: Separate files for different utilities
163- **Move to tests/util/**: Follow common Python testing patterns
164 
165### Decision
166 
167Move shared test utilities to `tests/util/` folder:
168 
169- `tests/util/firebase_emulator.py`: Emulator management and fixtures
170- `tests/util/item_flow_setup.py`: Database setup fixtures for integration tests
171- Import utilities in `conftest.py` for backwards compatibility
172- Clear separation of concerns
173 
174### Consequences
175 
176- **Pros**: Better organization, easier to find and maintain utilities, follows Python conventions
177- **Cons / risks**: Minor refactoring needed for imports, slightly more complex structure
178- **Supersedes**: —
179- **Superseded by**: —
180 
181### Compliance / Verification
182 
183All test utilities under `tests/util/` with proper imports. New utilities should follow this pattern.
184 
185---
186 
187## ADR-0004 — Real Firebase Emulators Over Mocked Services
188 
189<a id="adr-0004"></a>
190**Date**: 2025-01-27  
191**Status**: Accepted  
192**Owner**: AI Agent
193 
194### Context
195 
196Integration tests needed to validate Firebase Functions behavior including database operations, triggers, and Firebase service interactions. The choice was between mocking Firebase services or using real emulators.
197 
198### Alternatives
199 
200- **Mock Firebase services**: Fast but doesn't test real Firebase behavior or edge cases
201- **Use production Firebase**: Real but expensive, slow, and affects live data
202- **Use Firebase emulators**: Real Firebase behavior in isolated environment
203 
204### Decision
205 
206Use real Firebase emulators for all integration testing:
207 
208- Tests connect to actual Firestore emulator (localhost:8080)
209- Real Firebase Functions emulator (localhost:5001) for function execution
210- Real document operations in emulator database
211- Only mock Firestore trigger events (event object creation, not database operations)
212 
213### Consequences
214 
215- **Pros**: Tests real Firebase behavior, catches Firebase-specific issues, validates complete workflows
216- **Cons / risks**: Requires Firebase CLI, slower than mocks, more complex setup
217- **Supersedes**: —
218- **Superseded by**: —
219 
220### Compliance / Verification
221 
222Integration tests must use emulator connections. No mocking of Firebase database operations. Trigger events can be mocked for testing purposes.
223 
224---
225 
226## ADR-0005 — Database Class Consolidation
227 
228<a id="adr-0005"></a>
229**Date**: 2025-01-27  
230**Status**: Accepted  
231**Owner**: AI Agent
232 
233### Context
234 
235The template had two database classes: `Db` (base class) and `ProjectDb` (project-specific subclass). This created unnecessary inheritance complexity and indirection for a template that serves as a starting point for new projects.
236 
237### Alternatives
238 
239- **Keep ProjectDb inheritance**: Maintains separation but adds complexity for template users
240- **Multiple database singletons**: Each with different collections but more confusing
241- **Consolidate into single Db class**: Simplify by merging ProjectDb functionality into base Db class
242 
243### Decision
244 
245Consolidate ProjectDb functionality directly into the base Db class:
246 
247- Merge project-specific collections (items, categories, itemActivities) into base `_init_collections()` method
248- Replace all `ProjectDb.get_instance()` calls with `Db.get_instance()`
249- Remove ProjectDb class entirely
250- Update all imports and type hints across the codebase
251 
252### Consequences
253 
254- **Pros**: Simpler codebase for template users, fewer concepts to understand, easier to extend
255- **Cons / risks**: Less separation of concerns, template users may need to modify collections directly
256- **Supersedes**: —
257- **Superseded by**: —
258 
259### Compliance / Verification
260 
261All references to ProjectDb removed from codebase. Single Db class used throughout with project collections included by default.
262 
263---
264 
265## ADR-0006 — Automated Test Runner Implementation
266 
267<a id="adr-0006"></a>
268**Date**: 2025-01-27  
269**Status**: Accepted  
270**Owner**: AI Agent
271 
272### Context
273 
274Developers needed an easy way to run tests with proper Firebase emulator management. Manual emulator startup/shutdown was error-prone and the existing pytest commands required knowledge of emulator setup.
275 
276### Alternatives
277 
278- **Manual emulator management**: Simple but error-prone, requires developer to remember setup steps
279- **Docker-based testing**: Isolated but complex setup, requires Docker knowledge
280- **Automated test runner script**: Single command handles emulator lifecycle and test execution
281 
282### Decision
283 
284Implement `run_tests.py` script with automated emulator management:
285 
286- Automatic Firebase emulator startup/shutdown with proper cleanup
287- Command-line options for test types (unit, integration, all)
288- Support for existing emulators via `--no-emulator` flag
289- Optional emulator log viewing with `--show-logs`
290- Graceful error handling and forced cleanup on failures
291 
292### Consequences
293 
294- **Pros**: Better developer experience, reliable emulator cleanup, flexible test execution options
295- **Cons / risks**: Additional script to maintain, requires Firebase CLI installation
296- **Supersedes**: —
297- **Superseded by**: —
298 
299### Compliance / Verification
300 
301Test runner documented in README with examples. Script handles all emulator lifecycle automatically. Command-line help available via `--help`.
302 
303---
304 
305## ADR-0007 — Test Fixture Cleanup Strategy
306 
307<a id="adr-0007"></a>
308**Date**: 2025-01-27  
309**Status**: Accepted  
310**Owner**: AI Agent
311 
312### Context
313 
314The `conftest.py` file contained unused test fixtures (`test_category`, `test_item`, `mock_callable_request`) that were not referenced anywhere in the test suite. These created confusion and maintenance overhead.
315 
316### Alternatives
317 
318- **Keep all fixtures**: Simple but maintains dead code and confusion
319- **Move to test utilities**: Relocate unused fixtures to utils for potential future use
320- **Remove unused fixtures**: Clean up conftest.py to only contain actively used fixtures
321 
322### Decision
323 
324Remove unused test fixtures from conftest.py:
325 
326- Remove `test_category`, `test_item`, and `mock_callable_request` fixtures
327- Keep only `firebase_app`, `db`, and `test_user_id` fixtures that are actively used
328- Move complex test setup logic to dedicated utility modules when needed
329- Clean up any broken import references
330 
331### Consequences
332 
333- **Pros**: Cleaner conftest.py, reduces confusion for new developers, easier maintenance
334- **Cons / risks**: Fixtures need to be recreated if later needed, requires verification that nothing uses them
335- **Supersedes**: —
336- **Superseded by**: —
337 
338### Compliance / Verification
339 
340No references to removed fixtures exist in codebase. Tests continue to pass without the removed fixtures. New test fixtures should only be added when actively used.
341