location-mqtt-tracker-app/GEMINI.md

Gemini Code Assistant Context

This document provides a comprehensive overview of the Location Tracker project, designed to give the Gemini code assistant the necessary context to understand the codebase, its architecture, and its conventions.

1. Project Overview

This is a full-stack web application for real-time location tracking, built with Next.js 14. Its primary purpose is to receive location data from OwnTracks mobile clients via an MQTT broker and display the tracks on an interactive map.

Key Technologies

• Framework: Next.js 14 (App Router)
• Language: TypeScript
• Database: Dual SQLite databases using better-sqlite3.
  • data/database.sqlite: For core application data like users, devices, and settings.
  • data/locations.sqlite: For high-volume, time-series location data.
• Data Ingestion: An MQTT subscriber (lib/mqtt-subscriber.ts) connects to a Mosquitto broker to receive location updates from OwnTracks clients. An HTTP endpoint (/api/locations/ingest) is also available for manual data pushes.
• Authentication: next-auth (v5) with a credentials (username/password) provider. It supports ADMIN and VIEWER roles.
• Frontend: React, React Leaflet for mapping, and Tailwind CSS for styling.
• Deployment: The project includes a Dockerfile and docker-compose.yml for containerized deployment alongside a Mosquitto MQTT broker.

Core Features

• Interactive map displaying real-time location data.
• Filtering by device and time range.
• Admin dashboard for user and device management.
• Secure authentication with role-based access control.
• Database maintenance tasks (cleanup, optimization) via API or scripts.

2. Building and Running the Project

Prerequisites

• Node.js 18+
• npm

Development Mode

1. Install dependencies:

   npm install
   

2. Initialize the databases: This command creates the two SQLite databases in the data/ directory and seeds them with a default admin user (admin / admin123).

   npm run db:init
   

3. Run the development server: This starts the Next.js application on http://localhost:3000. It also starts the MQTT subscriber service.

   npm run dev
   

Production Mode

• Build the application:

  npm run build
  

• Start the application:

  npm run start
  

Docker Compose

The most straightforward way to run the application and its dependent MQTT broker is using Docker Compose.

1. Create an environment file: Copy .env.example to .env and fill in the required secrets, especially AUTH_SECRET.

2. Start the services:

   docker-compose up --build
   

   This will build the Next.js app image and start both the application container and the Mosquitto container. The data directory is mounted as a volume to persist the SQLite databases.

3. Architecture and Data Flow

The application follows a clean, decoupled architecture.

Data Ingestion Flow:

1. An OwnTracks client publishes a location update to a specific MQTT topic (e.g., owntracks/user/device10).
2. The Mosquitto broker receives the message.
3. The Next.js application's MQTT Subscriber (lib/mqtt-subscriber.ts), which is started on server boot via instrumentation.ts, is subscribed to the owntracks/+/+ topic.
4. Upon receiving a message, the subscriber parses the payload, transforms it into the application's Location format, and saves it to data/locations.sqlite using the functions in lib/db.ts.

Data Retrieval Flow:

1. The user's browser, viewing the map page, periodically fetches data from the /api/locations endpoint.
2. This API route queries the data/locations.sqlite database, applying any user-specified filters for device or time.
3. The API returns the location data as a JSON response.
4. The frontend MapView.tsx component renders the received data as markers and polylines on the Leaflet map.

Authentication & Authorization:

• Users log in via the /login page, which uses the NextAuth.js Credentials provider.
• The lib/auth.ts file contains the NextAuth configuration, validating credentials against the User table in data/database.sqlite.
• The middleware.ts file protects the /admin and /map routes, checking for a valid session and enforcing role-based access (ADMIN vs. VIEWER).

4. Development Conventions

• Database Access: All direct database operations are encapsulated within the lib/db.ts file. This provides a single, consistent interface (userDb, deviceDb, locationDb) for interacting with the data layer.
• Authentication: All authentication and session logic is centralized in lib/auth.ts. The auth() object exported from this file is the primary entry point for accessing session data on the server.
• Background Services: Long-running background services, like the MQTT subscriber, should be initialized in lib/startup.ts and triggered from the instrumentation.ts file. This is the standard Next.js way to run code on server startup.
• Configuration: Environment variables are used for configuration (see .env.example).
• Scripts: The scripts/ directory contains Node.js scripts for various administrative tasks, such as database initialization (init-database.js), cleanup (cleanup-old-locations.js), and testing. They should be run using node scripts/<script_name>.js.
• Styling: Utility-first CSS using Tailwind CSS.
• Types: TypeScript types are used throughout. Core application types are defined in files like lib/db.ts and types/location.ts.