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.

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.

Deployment Notes

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