mapix/AGENTS.md

Agent Guide

This repository is a browser-first photo mapping prototype.

Goals

• Import public Nextcloud shares through the local server proxy.
• Read EXIF and GPS data client-side whenever possible.
• Show photos on OpenStreetMap with map markers, thumbnails, and fullscreen preview.
• Keep the timeline, map, and import flow visually and behaviorally consistent.

Stack

• TypeScript + Node.js
• Server entry: src/index.ts
• HTTP and HTML rendering: src/server/request-handler.ts
• Shared environment config: src/shared/env.ts
• Docker is supported via Dockerfile

Current Structure

• src/domain/ for core data shapes and route logic
• src/features/ for feature-specific logic
• src/shared/ for reusable helpers
• src/server/ for request handling and HTML output

Working Rules

• Keep all visible UI text in English.
• Keep copy concise and professional.
• Prefer client-side processing; do not store uploaded images on the server.
• Preserve the Nextcloud public-share flow and local proxy behavior.
• Keep the timeline zoomable and tied to the selected date range.
• Keep the code style consistent with the existing TypeScript/DOM approach.
• Keep your output during editing as short as possible.

UI Rules

• Use a restrained, modern palette.
• Prefer square or minimally rounded surfaces.
• Keep the map, import panel, photo list, and timeline visually aligned.
• Maintain thumbnail previews in map markers and photo lists.

Change Process

• Make small, focused changes.
• Use conventional commit messages.
• Verify the result with git diff --check when possible.
• Update the README only when the user-facing setup or features change.

Practical Best Practices

• Prefer incremental changes over large rewrites.
• Keep naming consistent within a feature, especially for UI state and DOM references.
• Separate data handling, rendering, and network access where practical.
• Treat share loading, image parsing, and metadata extraction as failure-prone paths.
• Handle missing EXIF data, empty shares, and partial import results gracefully.
• Keep browser work lightweight; avoid unnecessary re-renders or duplicate downloads.
• Reuse existing helpers and structures before introducing new abstractions.
• Prefer plain, readable TypeScript over clever patterns.
• Add comments only where the code would otherwise be hard to follow.
• Preserve backward compatibility for the public import flow when possible.
• If a change affects user-visible text, keep the tone short, clear, and professional.
• If a change affects the UI, check the result at both desktop and mobile widths.
• If a change affects performance, prefer streaming or progressive rendering over waiting for all items.
• If a change affects deployment, keep the container build simple and reproducible.

Deployment Notes

• The app is designed to run in a container.
• Default host: 0.0.0.0
• Default port: 3000