Cursor rule

1---
2globs: back/**
3alwaysApply: false
4---
5 
6# Backend Development Workflow
7 
8## Architecture
9 
10This project uses the event driven broker architecture pattern with Firebase Functions. All business logic is organized into brokers that handle different types of requests and events. The data is saved in firestore and updated on the front end automatically through firestore hooks.
11 
12## Testing
13 
14You must always start from tests. We primarily use integration tests that test the user flow from start to finish. For example, for testing item management flow, you would test: creating item -> updating item -> archiving item -> deleting item -> etc. Inside each test case you must check the results in firestore. Test is considered passed, when all document properties are as expected.
15 
16**Important**: We check real documents in firestore after running each firebase function. The same with external services. Never create useless unit tests that just test properties of the class. Instead, test the actual functionality of the class.
17 
18Emulator is started automatically when executing `back/run_tests.py` file. Only run tests by running this file, otherwise, they will not work.
19 
20# Development Principles
21 
22All code must be clearly readable and maintainable. It must read like a story. Everything should be self-explanatory. You should not need tons of comments to understand what it does. The key idea is to make sure I can understand what the code does in 5 seconds. If I can't, you should refactor the code. Below is a list of principles that you must follow to achieve this:
23 
24- 🪟 **No broken windows**: Keep code clean from the start. Don't leave anything for later.
25- 🔄 **DRY**: Don't repeat yourself. If you are about to write the same code twice, stop, reconsider your approach and refactor.
26- 🌐 **Leave it better than you found it**: Improve bad code as you encounter it. Your code should clearly communicate its purpose.
27- 🔁 **Write code once**: Don't repeat yourself. Make code modular and extract components when needed. Prefer types over obvious comments.
28- 🧪 **Test First**: Do not start integrating any front-end features until they have been fully tested on the back end.
29- 👨‍💻 **SOLID**: Follow SOLID principles. Write single purpose short self-contained functions.
30 
31## Development Rules
32 
33Below are the rules that you must follow when developing backend functionality:
34 
35- All firestore documents must be modified **strictly** within `DocumentBase` classes located in `src/documents/DocumentBase.py`. You must **never** modify documents outside of these classes.
36- All third party APIs/clients must be wrapped in API wrapper classes located in `src/apis/`.
37- Never make calls to firestore directly. Always use `Db` class located in `src/apis/Db.py`.
38- All firestore document types should always be updated in `src/models/firestore_types.py`.
39- If you are creating multiple documents from an event (like creating items from CSV file) - create a Factory class with a method `.from_csv(csv_path)` - this method should return an array of Document classes.
40- Rules for new firestore and storage types must **always** be up to date in `firestore.rules` or `storage.rules`. Define them as soon as possible.
41- All third party APIs must be wrapped in APIWrapperBase class located in `src/apis/APIWrapperBase.py`.
42- All firestore function request and response types must be in `src/models/function_types.py`.
43- Functions should be named as `{action}_{resource}_callable` or `on_{resource}_{event}`.
44- All complex functionality that involves multiple documents, other APIBase classes, or complex logic should be wrapped in a Service class, located in `src/services/`.
45 
46## Workflow
47 
48When building new features, you must always start from creating new test files or modifying existing test files. Follow the workflow below:
49 
500. Before starting, create a to-do list for yourself, following this exact process.
511. Navigate to the `tests` directory and find the most relevant test files that contain a similar user flow.
52   - If you cannot find any relevant test files, ask clarification from the user.
53   - If it's a new feature, create a new test file.
542. Incorporate new functionality into the test files. Make sure to check types from the `models` folder or add new types as necessary.
553. Build the new feature following our broker architecture and development principles.
564. Run the affected tests and check the results in terminal.
575. Keep iterating until all tests are passing. Do not stop until all tests are passing.
586. Export any new brokers from the `main.py` file for deployment.
597. Document any key architecture decisions (if any)in the `back/.cursor/rules/ADR.mdc` file.
608. Ensure firestore rules and storage rules are updated to reflect the new functionality in the `firestore.rules` and `storage.rules` files.
61 
62## Common Patterns
63 
64### Creating a Callable Function
65 
66```python
67@https_fn.on_call(
68    cors=options.CorsOptions(cors_origins=["*"]),
69    ingress=options.IngressSetting.ALLOW_ALL,
70)
71def function_name(req: https_fn.CallableRequest):
72    uid = db_auth_wrapper(req)
73    # Implementation
74```
75 
76### Creating a Document Class
77 
78```python
79class MyDocument(ProjectDocumentBase[MyDocType]):
80    pydantic_model = MyDocType
81 
82    def __init__(self, id: str, doc: Optional[dict] = None):
83        self.collection_ref = self.db.collections["my_collection"]
84        super().__init__(id, doc)
85```
86 
87### Creating a Service
88 
89```python
90class MyService:
91    def __init__(self, doc: MyDocument):
92        self.document = doc
93 
94    def complex_operation(self):
95        # Orchestrate multiple documents
96```
97 
98## Guardrails
99 
100- NEVER run any deploy commands.
101