first commit

CLAUDE.md

@@ -0,0 +1,94 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Overview
+
+This repository contains an n8n workflow configuration (`tracker.json`) that implements a Telegram-based location tracking system without a database. The workflow stores location data in a simple JSON file (`/tmp/n8n-locations.json`) on the n8n server.
+
+## Workflow Architecture
+
+The workflow has two main execution paths:
+
+### 1. Location Capture Flow (Telegram Trigger → Storage)
+- **Telegram Trigger**: Receives incoming Telegram messages
+- **Hat Location?**: Filters messages containing location data
+- **Location verarbeiten**: Extracts and formats location data (lat/lon, user info, timestamp)
+- **Lade existierende Daten**: Reads existing locations from `/tmp/n8n-locations.json`
+- **Merge mit History**: Combines new location with existing data (keeps last 100 entries)
+- **Speichere in File**: Writes updated JSON back to `/tmp/n8n-locations.json`
+- **Telegram Bestätigung**: Sends confirmation message with location details and map link
+
+### 2. Location API Flow (Webhook → JSON Response)
+- **Webhook - Location API**: Exposes `/location` endpoint with CORS enabled
+- **Lade Daten für API**: Reads location data from file
+- **Format API Response**: Formats data into structured JSON (current location, history, metadata)
+- **JSON Response**: Returns JSON with CORS headers
+
+## Key Technical Details
+
+### Data Storage
+- Storage location: `/tmp/n8n-locations.json`
+- Format: JSON array of location objects
+- Max retention: 100 most recent locations (oldest automatically removed)
+- Data persistence: File-based (survives n8n restarts but may be lost on system restart due to `/tmp` location)
+
+### Location Object Structure
+```json
+{
+  "latitude": number,
+  "longitude": number,
+  "timestamp": "ISO 8601 string",
+  "user_id": number,
+  "first_name": string,
+  "last_name": string,
+  "username": string,
+  "marker_label": string,
+  "display_time": "de-DE locale string",
+  "chat_id": number
+}
+```
+
+### API Response Structure
+```json
+{
+  "success": true,
+  "current": <most recent location object>,
+  "history": [<array of all location objects>],
+  "total_points": number,
+  "last_updated": "ISO 8601 string"
+}
+```
+
+### Web Interface
+The workflow sends users a link to `https://web.unixweb.home64.de/tracker/index.html` for viewing locations on a map. This frontend is hosted separately and not included in this repository.
+
+## Workflow Configuration
+
+- **Telegram Credentials**: Uses "Telegram account n8n-munich-bot" (ID: dRHgVQKqowQHIait)
+- **Webhook IDs**:
+  - Telegram trigger: `telegram-location-webhook`
+  - Location API: `location-api-endpoint`
+- **Error Workflow**: ID `PhwIkaqyXRasTXDH` (configured but not included in this export)
+- **Execution Order**: v1
+- **Caller Policy**: workflowsFromSameOwner
+
+## Modifying the Workflow
+
+When editing this workflow:
+1. The workflow is active by default - test changes carefully to avoid disrupting live tracking
+2. JavaScript code nodes use n8n's code execution environment (not vanilla Node.js)
+3. Shell commands execute in n8n's runtime environment - ensure `/tmp` is writable
+4. CORS is configured for `*` (all origins) - restrict if needed for security
+5. Date formatting uses `de-DE` locale - adjust if different locale needed
+6. The 100-entry limit prevents unbounded growth - increase if more history is needed
+
+## Deployment
+
+To use this workflow:
+1. Import `tracker.json` into n8n instance
+2. Configure Telegram bot credentials
+3. Ensure n8n has write permissions to `/tmp/n8n-locations.json`
+4. Activate the workflow
+5. Send a location via Telegram to test the capture flow
+6. Access the webhook endpoint to verify API functionality