INOWYA/README.md

INOWYA - Location History Analyzer

A self-contained, deploy-anywhere Location-History Analyzer that ingests GPS/location artifacts and provides advanced analysis capabilities.

🚀 Quick Start

# Clone and run
$ git clone https://github.com/your-org/inowya.git
$ cd inowya
$ cp .env.example .env
$ docker compose up -d

# Wait ~30 seconds, then open:
$ open http://localhost:8080

Drag your Google Takeout ZIP file onto the web UI and start exploring your location history!

📋 Features

Universal Format Support

• Google Takeout: Semantic Location History JSON, Records.json
• GPS Formats: GPX 1.0/1.1, KML/KMZ, NMEA-0183, IGC
• GIS Formats: GeoJSON, CSV with lat/lon/time
• Phone Exports: Samsung, Huawei, Apple iOS
• Fitness/Social: Strava, OSMAND, Life360, Garmin, Polar

Advanced Analysis

• Automatic Trip Detection: Segment continuous movement into trips
• Stop Detection: Identify dwell locations with adaptive DBSCAN
• Transport Mode Inference: Rule-based + ML classification
• Speed & Elevation: Calculate profiles and elevation gain
• Heat Maps: Calendar-based visualization of movement patterns

Interactive Visualization

• Timeline Scrubber: Drag to navigate through time
• 3D Replay: Three.js powered trip replays
• Calendar Heat Map: GitHub-style activity visualization
• Investigation Notebooks: Tag locations and add notes
• Photo Integration: Match EXIF GPS data to stops

Forensic Tools

• Data Comparison: Diff between datasets
• Geo-fence Analysis: Entrance/exit time detection
• Spoofing Detection: Identify GPS manipulation
• Chain of Custody: Export forensic reports
• Bulk Processing: CLI tools for analysis

🏗 Architecture

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   React Frontend │ ←→ │   FastAPI Server │ ←→ │   PostGIS + Redis │
│  (MapLibre GL)   │    │                 │    │                 │
└─────────────────┘    └─────────────────┘    └─────────────────┘
                                │
                        ┌─────────────────┐
                        │  Celery Workers  │
                        │ (Async Processing)│
                        └─────────────────┘

📁 Project Structure

inowya/
├── docker-compose.yml          # Main deployment
├── server/                     # FastAPI backend
│   ├── app/
│   │   ├── api/               # REST endpoints
│   │   ├── models/            # Database models
│   │   └── core/              # Configuration
│   └── requirements.txt
├── worker/                     # Celery workers
│   ├── tasks/                 # Processing tasks
│   ├── parsers/               # Format parsers
│   └── requirements.txt
├── frontend/                   # React application
│   ├── src/
│   │   ├── components/        # UI components
│   │   ├── map/               # Map integration
│   │   └── panels/            # Analysis panels
│   └── package.json
├── cli/                       # Command-line tools
│   ├── lha-dedup
│   ├── lha-geofence
│   └── lha-compare
└── docs/                      # Documentation

🔧 Configuration

Environment Variables

# Database
POSTGRES_DB=inowya
POSTGRES_USER=inowya
POSTGRES_PASSWORD=your_password

# Redis
REDIS_URL=redis://redis:6379

# Server
SECRET_KEY=your_secret_key
ALLOWED_HOSTS=localhost,127.0.0.1

# Map Tiles
MAP_TILE_URL=http://tiles:8080

📊 Data Model

Core Tables

• raw_point: Individual GPS points with metadata
• stop: Detected dwell locations
• trip: Movement segments between stops
• file: Imported file metadata
• notebook: Investigation workspaces
• note: Annotations and findings

🛠 API Endpoints

Data Import

• POST /imports - Upload location data
• GET /imports/{id}/status - Check processing status

Analysis

• GET /calendar - Daily activity heat map
• GET /timeline/{date} - Complete day data
• GET /trips - Filterable trip list
• GET /stops - Geo-fence search

Investigation

• POST /notebooks - Create investigation workspace
• GET /diff - Compare datasets
• GET /export - Export reports

🔍 CLI Tools

# Merge overlapping imports
$ lha-dedup --user-id 123

# Analyze geo-fence entries/exits
$ lha-geofence --geojson fences.json

# Compare two datasets
$ lha-compare --dataset-a file1.zip --dataset-b file2.zip

# Detect GPS spoofing
$ lha-detect-spoof --user-id 123

# Export chain of custody
$ lha-export-chain --user-id 123 --output report.zip

🚀 Deployment Options

Personal / Offline

• Single machine deployment
• 4-core CPU, 8GB RAM minimum
• Self-contained with Docker Compose

LAN Server

• Multi-user support
• Traefik reverse proxy
• Automated backups

Cloud Deployment

• AWS/Azure/GCP ready
• Managed databases
• Auto-scaling workers

🔒 Security & Privacy

• Row-Level Security: Multi-tenant data isolation
• No Phone Home: Completely self-hosted
• GDPR Compliant: Right to be forgotten
• Encryption: Optional full-disk encryption
• Non-Root Containers: Secure container execution

📈 Performance

• 5M+ Points: Handles large datasets efficiently
• Sub-second Queries: Optimized PostGIS indexes
• Real-time Updates: WebSocket live progress
• Offline Capable: PWA with service workers

🎯 Use Cases

Personal Analytics

• Understand daily movement patterns
• Track fitness activities
• Photo location correlation

Digital Forensics

• Legal investigations
• Asset tracking
• Incident reconstruction

Research

• Urban mobility studies
• Transportation planning
• Behavioral analysis

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Adding New Formats

1. Create parser in worker/parsers/
2. Inherit from BaseParser
3. Register in entry points

Custom Analysis

1. Add task to worker/tasks/
2. Update API endpoints
3. Create frontend panel

📄 License

MIT License - Free for commercial and personal use.

🆘 Support

• Documentation
• Issues
• Discussions

---

Happy investigating! 🗺️🔍