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

{
  "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

{
  "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:

The workflow is active by default - test changes carefully to avoid disrupting live tracking
JavaScript code nodes use n8n's code execution environment (not vanilla Node.js)
Shell commands execute in n8n's runtime environment - ensure /tmp is writable
CORS is configured for * (all origins) - restrict if needed for security
Date formatting uses de-DE locale - adjust if different locale needed
The 100-entry limit prevents unbounded growth - increase if more history is needed

Deployment

To use this workflow:

Import tracker.json into n8n instance
Configure Telegram bot credentials
Ensure n8n has write permissions to /tmp/n8n-locations.json
Activate the workflow
Send a location via Telegram to test the capture flow
Access the webhook endpoint to verify API functionality

3.6 KiB Raw Blame History