memories/README.md

Memories: Location-Based Travel Memory Application

Overview

Memories is a full-stack web application that transforms your Google Takeout location history data into interactive travel narratives. It detects visits (stationary periods), trips (movements between places), and visualizes them on an interactive map using open-source Leaflet + OpenStreetMap (no API keys required).

Key Features

• Data Import: Upload Google Takeout JSON/CSV location files.
• Spatial Analysis: Automatically detects visits (50m radius, 10min min) and trips using clustering.
• Interactive Map: View visits (blue circles) and trips (red lines) with popups for details.
• Dashboard: Stats on locations, visits, and trips.
• Export: Generate PDF reports of your travel summary.
• PWA-Ready: Installable on mobile for offline access.
• Scalable: Redis caching, RabbitMQ for async processing (placeholder worker).

Tech Stack

• Backend: FastAPI (Python), PostgreSQL with PostGIS (spatial DB), SQLAlchemy, NumPy/SciPy.
• Frontend: React 18, Material-UI, Leaflet + OpenStreetMap.
• Infrastructure: Docker Compose (includes DB, Redis, RabbitMQ, backend, frontend).
• No External APIs: Fully self-contained (free maps via OSM).

Quick Start

Prerequisites

• Docker & Docker Compose
• Node.js (v16+) & npm (for frontend)
• Python 3.10+ & pip (for backend dev)

1. Clone & Setup

git clone http://your-gitea-server:3000/maq/memories.git
cd memories

2. Environment Configuration

Copy the example env file:

cp .env.example .env
# Edit .env with your values (e.g., passwords)

3. Install Dependencies

• Backend:

  cd backend
  pip install -r requirements.txt
  cd ..
  

• Frontend:

  cd frontend
  npm install
  cd ..
  

4. Run with Docker (Recommended)

docker-compose up --build

• Backend: http://localhost:8000 (API docs at /docs)
• Frontend: http://localhost:3000
• DB: localhost:5432 (user/pass from .env)

5. Local Development (Without Docker)

• Backend: cd backend && uvicorn main:app --reload --port 8000
• DB: Run PostgreSQL with PostGIS extension manually.
• Frontend: cd frontend && npm start

6. Testing

• Upload a sample Google Takeout file (from takeout.google.com > Location History > JSON).
• Navigate to /dashboard, /map, /export.
• Backend tests: cd backend && pytest
• Frontend tests: cd frontend && npm test

Usage

1. Login/Register: Basic auth (expandable with JWT).
2. Upload: Go to /upload, select your location JSON file.
3. View Map: /map shows visits/trips overlaid on OSM.
4. Dashboard: Stats and quick insights.
5. Export: Download PDF report from /export.

Sample Google Takeout Data

For testing, download a sample from Google Takeout or use this mock JSON structure:

{
  "locations": [
    {
      "timestampMs": "1699123200000",
      "latitudeE7": 377749000,
      "longitudeE7": -1224194000,
      "accuracy": 50
    }
  ]
}

Upload via the form – app parses timestamps, converts E7 to degrees.

Deployment

• Production: Use docker-compose.prod.yml (create by removing dev ports/volumes). Add NGINX reverse proxy.
• Cloud: Deploy to Heroku/Vercel (frontend) + Railway (backend/DB). Use Railway for full Docker stack.
• HTTPS: Essential for PWA; use Let's Encrypt with Docker.
• Scaling: Enable RabbitMQ worker for large files: docker-compose up worker.

Development

• Backend: Edit in backend/; restart uvicorn.
• Frontend: Edit in frontend/src/; hot-reload on npm start.
• Database: Use pgAdmin or psql to query spatial data (e.g., SELECT ST_AsText(centroid_geom) FROM visits;).
• Adding Features: Auth (JWT), user profiles, narrative generation (NLP), sharing.

Troubleshooting

• Map Not Loading: Ensure Leaflet CSS/JS imported; check console for CORS.
• DB Errors: Verify PostGIS extension: CREATE EXTENSION postgis;.
• Upload Fails: Check file size (<10MB); ensure JSON has 'locations' array.
• No Data: Upload first, then refresh dashboard/map.

Contributing

Fork the repo, create a feature branch, and submit a PR. Focus on efficiency and spatial accuracy.

License

MIT License – feel free to use/modify.

---

Built with ❤️ by ProjectForge AI Agent.