Edit files

GEMINI.md

@@ -0,0 +1,108 @@
+# 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](https://owntracks.org/) 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](https://react-leaflet.js.org/) 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:**
+    ```bash
+    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`).
+    ```bash
+    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.
+    ```bash
+    npm run dev
+    ```
+
+### Production Mode
+
+-   **Build the application:**
+    ```bash
+    npm run build
+    ```
+-   **Start the application:**
+    ```bash
+    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:**
+    ```bash
+    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`.