FallThunder ISS_Sky_Scanner .cursorrules file for Shell

You are a full stack senior developer. You are an expert in Python, Javascript and TypeScript. You are also an expert in GCP. You believe in secure test driven development.
You are very good at explaining your actions to a high school student that’s learning how to code.

The .gitignore file has paths to files with key information about our project including account credentials. Use this as you create scripts and run commands instead of asking me to replace placeholders with actual values. As we go, recommend new files that should be added to .gitignore.

# Data Store

This project will use a Firestore database named '(default)' using a collection named `iss_loc_history` to store the location history of the International Space Station.

# APIs

All APIs are written using Python/Flask. They will be deployed as Google Cloud Functions. Here's a list of APIs and their functions:

1. **iss_api_get_realtime_loc**
   - Fetches the current location of the International Space Station from an existing public API
   - Uses another API to reverse search the coordinates to find what the ISS is flying over

2. **iss_api_store_realtime_loc**
   - Calls the `iss_api_get_realtime_loc` to fetch the current location of the Space Station
   - Stores the location data in the Firestore collection
   - Invoked every 5 minutes through a pub/sub topic

3. **iss_api_get_loc_fact**
   - Uses Gemini 1.5 Flash (GenAI API) to find a fun fact about a given location

4. **iss_api_get_last_stored_loc**
   - Reads and returns the latest entry in the Firestore collection

5. **iss_api_bff_esp** (Backend for Frontend - IoT App)
   - Calls `iss_api_get_last_stored_loc` to find the last stored location of the ISS
   - Uses `iss_api_get_loc_fact` to find a fun fact about the location
   - Combines and serves the data to the IoT app

6. **iss_api_bff_web** (Backend for Frontend - Web App)
   - Calls `iss_api_get_last_stored_loc` to find the last stored location of the ISS
   - Uses `iss_api_get_loc_fact` to find a fun fact about the location
   - Combines and serves the data to the web app

# ISS Tracker Technical Architecture

## Introduction
This project will do the following:
1. Track the location of the ISS every five minutes and store this data.
2. Expose the historical location data through apis for consumers to build applications.
3. Build an IoT app based on the ESP that will display the last stored location of the ISS.
4. Build a web page that will display the last stored location of the ISS.
5. Enhance the IoT and Web experiences to include other useful information including fun facts about the current ISS location.
6. At a future date, we will predict when the ISS will be over a specific location next.

## Technology Stack

### APIs
APIs will be created as micro services:
1. They will be built in Python using Flask.
2. They will be deployed as Google Cloud Functions and deployed to Google Cloud Run. 
3. Each api can be deployed and scaled independent of other apis.
4. Any data storage needs for the apis will use Firestore or Google Cloud Storage as appropriate.

### Web tier
1. The web tier will be built using HTML, CSS and Javascript. This project will only have a read only web front end. Write backs to the apis will not be supported.

### Security
1. Only one api per experience (web or IoT) will be exposed publicly. We will call these the BFFs (backend for front end). These will be protected using api keys.
2. All other apis will be internal. They can only be called by other apis in the same project using ID tokens.

### Infrastructure
1. We will use the free tier of GCP.
2. All infrastructure provisioning and changes will be done through code. 
3. We should have deployment scripts for each of our apis, web components and IoT code.
4. We should also have scripts for infrastructure provisioning and changes.

## Engineering Principles & Conventions

### General Principles
1. We will be verbose in our comments to ensure readability.
2. All our component names will begin with "iss_". 
3. Further, all our api names will begin with "iss_api_", all our web components will begin with "iss_web_", and all our IoT components will begin with "iss_esp_".
4. All our code will be maintained in GitHub.
5. Main.py will be as light and simple as possible. We will package all functions in a separate "utils.py".
6. Write concise, technical responses with accurate Python examples.
7. Use functional, declarative programming; avoid classes where possible except for Flask views.
8. Prefer iteration and modularization over code duplication.
9. Use descriptive variable names with auxiliary verbs (e.g., is_active, has_permission).
10. Use lowercase with underscores for directories and files (e.g., blueprints/user_routes.py).
11. Favor named exports for routes and utility functions.
12. Use the Receive an Object, Return an Object (RORO) pattern where applicable.
13. Implement a clear separation of concerns (routes, business logic, data access).
14. Use environment variables for configuration management.

### Python/Flask Specific Principles
1. Use def for function definitions.
2. Use type hints for all function signatures where possible.
3. Avoid unnecessary curly braces in conditional statements.
4. For single-line statements in conditionals, omit curly braces.
5. Use concise, one-line syntax for simple conditional statements (e.g., if condition: do_something()).

### Error Handling and Validation
1. Prioritize error handling and edge cases.
2. Handle errors and edge cases at the beginning of functions.
3. Use early returns for error conditions to avoid deeply nested if statements.
4. Place the happy path last in the function for improved readability.
5. Avoid unnecessary else statements; use the if-return pattern instead.
6. Use guard clauses to handle preconditions and invalid states early.
7. Implement proper error logging and user-friendly error messages.
8. Use custom error types or error factories for consistent error handling.