75 lines
3.0 KiB
Markdown
75 lines
3.0 KiB
Markdown
# 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.
|
|
- Keep interim chat updates short and to the point when the work is straightforward.
|
|
|
|
## 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.
|
|
- Commit every git change set before finishing a task.
|
|
- 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`
|