User Guide 📖

0. Introduction: Why this App?

Locomotion Diary is a tool designed to master Retrospective Memory (your past travels).

1. All Features

• Map Visualization: Interactive maps for every journey.
• Data Enhancement: Auto-fetches Weather and Addresses.
• Statistics: Visual charts of your travel habits.
• PDF Export: Creates print-ready E-Books.
• Offline Capable: Works without internet (PWA).

2. Who can use it?

Anyone! You don't need a Google Account to use this diary.

• Google Users: Visualize your existing Location History (Timeline).
• Manual Users: Start a private travel journal from scratch.

It is designed for Travelers, Journalers, Quantified-Self enthusiasts, and digital archivists.

3. How to use it (Workflow)

1. Import: Load your Google Takeout file.
2. Clean: Use the "Places" menu to fix location names.
3. Enhance: Run the scanner to fill in missing addresses.
4. Export: Generate your PDF E-book.

3.5 Startup Guide 🚀

Step 1: Security First (The Master Key)

When you first open the app, you will be asked to create a Master Password.

• Why? This password encrypts EVERYTHING (Diary).
• Constraint: We cannot recover this for you.
• Action: Create a strong password.

Step 1.5: Enable Biometrics (Optional) 👆

If you have a supported device (Windows Hello / TouchID):

• This allows you to unlock the app with a simple fingerprint or face scan next time!
• Note: Requires HTTPS (secure hosting) or Localhost.

Step 2: Choosing Your Path

How do you want to use Locomotion Diary?

🅰️ The Google Migrator (Import History)

If you have years of Google Maps Timeline history:

1. Complete Step 1 (Set Password).
2. Follow the JSON Import Instructions (Section 7).
3. Drag & drop your Google file. The app will encrypt and suck in all your past travels.

🅱️ The Fresh Journalist (Start New)

If you want a private manual journal:

1. Complete Step 1 (Set Password).
2. Click Current Month to start writing today.
3. Use the Date Picker to go back in time and add memories manually.

4. Proximity Radius Setup

Located in Places > Settings.

• Definition: The distance within which two GPS points are considered the "Same Place".
• Small (50m): High precision. Distinguishes neighbors.
• Large (500m): Groups broad areas (e.g., "Airport Complex") into one location.

5. Creating Diary / E-Book

Turn your data into a book.

1. Filter to the desired date range.
2. Click 🖨️ PDF in the header.
3. Crucial: Enable "Background Graphics" in your printer settings to see colors!

6. Data Integration

The app integrates with third-party apis directly from your browser:

• Weather: Connects to Open-Meteo for historical weather data.
• Photos: Generates smart links to your Google Photos library based on timestamps.
• Maps: Uses OpenStreetMap for tiles and geocoding.

7. Importing JSON Data

Once you have the file:

1. Open Locomotion Diary.
2. Drag & Drop the Records.json file onto the center of the screen (or click the folder icon to select it).
3. Wait for the import to finish (it stays offline).

8. Manual Creation (Non-Google Users)

No Google Data? No problem! You can use this app as a pure travel journal from scratch.

Event Types:

• 📍 Stationary: Log a visit to a place (Hotel, Restaurant, Park). You can use the map to pin the exact spot.
• 🚀 Moving: Log a journey. Provide a Start and End point to draw a line on the map.

Tip: Use the "Places" manager to save your favorite spots (Home, Office) for quick auto-complete later.

9. Filtering & Sorting Events

Use the Search Bar to drill down:

• Date: Select Year/Month.
• Location: e.g., "London".
• Activity: e.g., "Cycling" or "Train".
• Text: Search inside your personal notes.

Use the Sort Toggle (⬇️ / ⬆️) in the top toolbar to switch between displaying the Newest events first or Oldest events first.

10. Exporting Data (JSON & PDF)

• PDF: For reading/printing (Visual). Click 🖨️ PDF.
• JSON: For backup. Click 💾 JSON in the header.
  • Smart Export: It saves the entries currently visible on your screen.
  • Backup Mode: If your current view is empty, it will ask if you want to export your entire database as a safety backup.

11. Enhance Scanner

What it does: Scans for "Unknown Locations" and finds their real address.

Why? Google data often only has coordinates. This makes your diary readable (e.g., "Home" instead of "51.50, -0.12").

12. Naming Locations & Place Management

You can rename generic coordinates (e.g., "51.50, -0.12") to meaningful names like "Home" or "Work".

Renaming a Place

1. Find an entry for the location you want to name.
2. Click the Pencil Icon (✎) or "Edit" button next to the location name.
3. Option A: Type the new name (e.g., "My Office").
4. Option B (New): Click "📍 Auto-Detect Name (OSM)" to let the app find the real address map for you!
5. Click Save.
6. Effect: This renames all future and past visits to this spot (within the Proximity Radius).

Managing & Backing Up Places

Your saved places are stored in your browser. To keep them safe or move them to another device:

1. Click the **Location Manager** button (📍 Places) in the main menu.
2. **backup:** Click **📤 Export Places** to download a `locomotion_places_backup.json` file to your computer.
3. **Restore:** Click **📥 Import Places** and select your backup file to restore your list of named places.
4. Tip: Do this before clearing your browser history!

13. How the App Works?

It is a Single Page Application (SPA). It loads entirely into your browser's memory and uses IndexedDB to store your data locally. There is NO "Cloud" storage.

14. Download & Install

• Chrome/Edge: Look for the "Install" icon in the address bar.
• Mobile: Use "Add to Home Screen" in your browser menu.

15. Privacy and Safety

1.5 Interface Customization

You can personalize your reading experience:

• 🌙 Dark Mode: Click the moon icon in the header to switch to a dark theme, perfect for night reading. Default is Light.
• 🌍 Languages: Use the language dropdown (e.g., 🇺🇸 EN) to switch the interface to Spanish, Hindi, or Malayalam.

16. Embedded Photos 📷

See your memories in context without uploading them anywhere.

1. Click the 🖼️ Photos button in the header.
2. Select the folder on your computer where your photos are stored (e.g., "2024 Photos").
3. **Grant Permission:** Your browser will ask if you want to allow access. Click "View Files".
4. Scroll through your diary! The app will automatically find photos that match the date of the diary entry and display them.

Note: This works best in Chrome/Edge on Desktop.

17. AI Summaries 🤖

Get a quick recap of your day.

• Find the ✨ Summarize Day button inside any diary entry.
• Click it to generate a narrative (e.g., "You visited 3 places mostly by car...").
• IT runs completely offline on your device properly respecting your data privacy.

18. How to Update App 🔄

When a new version is available:

1. Go to Settings ⚙️ > Check for Updates.
2. If found, click Download to get the new ZIP file.
3. Extract the ZIP file on your device.
4. Replace your existing app folder/files with the new ones.
5. Reload the page in your browser to load the new version.

19. Interactive Maps 🗺️

Every journey in your diary comes alive with maps.

• Show Map: Click the "Show Map" button or the Map Icon (🗺️) on any diary entry to see the exact location or start point.
• Daily Routes: In the header of every day, click the "🗺️ Route" button to open a large map view. This displays:
  • The full path of your day's travels (Blue Lines).
  • Markers for everywhere you stopped (Pins).
  • Stats for each leg of the journey.

21. Security, Encryption & Recovery 🔐

App Lock Screen

You can lock the entire application to prevent unauthorized access on a shared device.

• Auto-Lock: The app locks automatically when you close the tab.

👆 Biometric Unlock (Windows Hello / TouchID)

Enjoy password-free access while keeping your data encrypted.

• How it works: We use your device's security chip (TPM) to safely store your encryption key.
• Requirements:
  • A device with Windows Hello (Face/Fingerprint) or TouchID.
  • The app must be served over a Secure Connection (HTTPS) or localhost.
  • It will NOT work if you just open the index.html file directly (file://).

🚑 Emergency Access Kit

Because there is no email reset, you MUST handle your own "Plan B" by creating an Emergency Kit.

1. Download Emergency Kit

Once logged in, go to the Data 🗄️ menu and click Download Emergency Kit.

• This downloads a special HTML file (`Locomotion_Emergency_Kit.html`) to your computer.
• This file securely contains your encrypted Master Password.
• Store it safely: Keep it on a USB drive or a secure cloud folder. Do not share it!

2. Login with Key File

If you forget your password or switch devices, use your Emergency Kit to regain access.

• On the Lock Screen, click the "🔑 Login with Key File" button.
• Select the `Locomotion_Emergency_Kit.html` you previously saved.
• The app will extract your password and securely unlock your diary.

🗑️ Reset App (I Forgot My Password!)

If you completely lose your password and have no Emergency Kit, your data is inaccessible. To make the app usable again, you must wipe the slate clean.

1. On the Lock Screen, click "🗑️ Reset App".
2. Accept the warnings to DELETE ALL CURRENT DIARY DATA.
3. You will be asked to confirm. Since you forgot your password, type RESET exactly into the Master Password field to authorize the wipe.
4. This destroys the encrypted database so you can start fresh.
5. Recovery Tip: If you originally had a plain JSON backup of your diary entries, you can import it after resetting to restore your events.

22. Troubleshooting 🔧

If the app ever feels "stuck", looks weird, or doesn't update:

1. Go to Settings ⚙️.
2. Click 🔄 Force Reload App.