# Future Ideas & Optimizations

This document tracks potential architectural improvements and features inspired by other Grepolis alliance coordination scripts (like GrepoData and Noct).

## 1. Timestamp-Based Polling Optimization (`since` parameter)
**Inspired by:** `noct-api.grepo-soft.workers.dev`

**Current State:** 
The Tampermonkey client polls the server every 8-18 seconds and receives the full state/command payload every time, even if nothing has changed.

**Proposed Implementation:**
- Add a `since` timestamp parameter to the client's poll requests.
- The server checks if any commands or state updates have occurred *after* the `since` timestamp.
- **If no new data:** The server returns an empty `HTTP 204 No Content` response.
- **If new data:** The server returns `HTTP 200 OK` with only the data that changed.

**Benefits:**
- Drastically reduces server bandwidth and CPU load.
- Minimizes the size of network requests on the client side, making the script stealthier and less resource-intensive in the browser.

**Concrete Code Example (How Noct does it):**
```javascript
// 1. Client-side polling logic
let lastFetchTime = Date.now();

async function pollCommands() {
    const url = `https://noct-api.grepo-soft.workers.dev/api/alliance/commands` +
                `?alliance=p0PmzsZMo4xZ2o29uvqggy5d` +
                `&world=gr118` +
                `&clientId=848938473` +
                `&since=${lastFetchTime}`; // Ask only for things after this timestamp

    const response = await fetch(url);
    
    // 2. Server returns HTTP 204 (No Content) if nothing new happened
    if (response.status === 204) {
        return; // Empty payload, exit early
    }

    // 3. Server returns HTTP 200 (OK) only if there are NEW commands
    if (response.status === 200) {
        const data = await response.json();
        
        // Process new commands...
        executeCommands(data.commands);
        
        // Update the timestamp so the next poll only asks for things after this moment
        lastFetchTime = Date.now(); 
    }
}
```

```python
# Backend (Python/Flask Equivalent)
@app.route('/api/alliance/commands')
def get_commands():
    # Get the timestamp from the URL query
    since_ts = int(request.args.get('since', 0))
    
    # Query DB for commands created AFTER the 'since' timestamp
    new_commands = db.execute(
        "SELECT * FROM commands WHERE created_at_ts > ?", (since_ts,)
    ).fetchall()
    
    if not new_commands:
        # Return empty body with 204 No Content
        return '', 204 
        
    return jsonify({"commands": new_commands}), 200
```

## 2. WebSocket Architecture for Real-Time Synchronization
**Inspired by:** `grepodata.com` (ReactPHP WebSocket server)

**Current State:** 
Command delivery relies on HTTP polling. If an attack plan requires a launch in 30 seconds, but the client is on an 18-second polling interval, there is a high risk of missing the execution window or executing late.

**Proposed Implementation:**
- Integrate `Flask-SocketIO` (or a standalone async WebSocket server) into the backend.
- The client script establishes a persistent `wss://` connection upon loading the game.
- The client authenticates using its `clan_key` and subscribes to its alliance "topic/room".
- When an admin arms an attack plan or a player updates their town state, the server instantly *pushes* the payload to all connected alliance members.

**Benefits:**
- **Zero Polling Latency:** Commands arrive in ~100ms instead of 8-18 seconds.
- **Perfect Attack Timing:** Ensures clients receive armed plans immediately, maximizing the margin for precise execution.
- **Instant UI Updates:** The dashboard and attack planner can update in real-time as members come online or troop counts change.

## 3. Server-Sent Events (SSE) Lag/Refresh Bug Fix
**Issue:**
When refreshing or hitting the "back" button on the Live Tracker (`tracker.html`), the page occasionally hangs, lags heavily, or completely fails to load.

**Root Cause:**
The Live Tracker uses SSE (`EventSource`) to receive real-time movement updates. Modern browsers strictly limit simultaneous HTTP/1.1 connections to the same server (usually 6 maximum). When the user navigates away or refreshes, the browser drops the frontend page, but the Python/Flask backend (`tracker.py`) does not immediately detect the broken pipe and keeps the socket open, waiting to send data. 
If the user hits refresh multiple times, these "ghost" connections stack up. Upon reaching 6 ghost connections, the browser refuses to load any further requests until the old connections naturally time out (which can take 30+ seconds).

**Proposed Fix:**
1. **Client-side (`tracker.html`)**: Ensure the browser explicitly tells the server the connection is closing exactly as the page unloads.
```javascript
window.addEventListener('beforeunload', () => {
    if (typeof es !== 'undefined' && es !== null) {
        es.close();
    }
});
```

2. **Server-side (`tracker.py`)**: Ensure the generator handles client disconnects gracefully and immediately cleans up the subscriber queue without waiting for a timeout.
```python
# Make sure the generator yields spaces/heartbeats actively so the OS 
# throws an IOError/GeneratorExit the moment the client drops.
```