Back to MusePages

Historical Place Archive

The original prompt, shown in full as plain text.

Prompt

# avarc-server — Specification

A web-based application to record, manage and display locations of
historical importance, each with a description.

This is the main global spec. Requirements for a specific area of
responsibility live in `spec/SPEC-<area>.md`.

## Goals

- Record locations of historical importance with descriptions.
- Manage (create, edit, delete) those records.
- Display them, in particular on a map.

## Non-goals (for now)

- Anything beyond point locations; richer geometry is deferred to the
  locations spec.
- The MCP server; planned for after the MVP (see the architecture overview).
- Public self-registration policy, moderation and import/export; to be
  specified when needed.

## Architecture overview

- **Frontend:** Next.js web application.
- **Backend:** Java Spring Boot service exposing an API consumed by the
  frontend.
- **Web server:** a web server in front of all partial applications
  (frontend, backend, Keycloak) is the single entry point for clients. It is
  nginx, serving one host with path prefixes (see the ingress spec).
- **Identity:** self-hosted Keycloak handles authentication, user
  management and roles; the backend and frontend delegate to it rather than
  implementing their own.
- **Public map server (after the MVP):** a separate read-only server exposes
  data intended for the public. The application itself requires login (see
  the auth spec).
- **MCP server (after the MVP):** an MCP server will be added after the MVP
  so that AI assistants can use the application. It sits behind the web
  server, uses the backend API rather than the database, and authenticates
  through Keycloak. It is not part of the MVP and is specified when it is taken
  up.

The [architecture diagram](spec/architecture-diagram.md) shows these
components and their connections.

## Global decisions

- **Time:** all timestamps are stored in UTC. Conversion to a local time zone
  happens only when presenting to a user.
- **Languages:** the application is multi-language. The first languages are
  English and German; further languages can be added later.

## Area specs

- [Locations](spec/SPEC-locations.md): data model for historical locations.
- [Auth](spec/SPEC-auth.md): authentication, user management and authorization with Keycloak.
- [Users](spec/SPEC-users.md): the application's record of a person, with preferences.
- [Backend](spec/SPEC-backend.md): Java Spring Boot API service.
- [Frontend](spec/SPEC-frontend.md): Next.js web application.
- [Ingress](spec/SPEC-ingress.md): web server in front of the partial applications.
- [Deployment](spec/SPEC-deployment.md): Docker Compose project, developer deployment.
- [Observability](spec/SPEC-observability.md): logs, metrics, health and the monitoring stack.
- [Dependency updates](spec/SPEC-dependency-updates.md): Renovate setup.
- [Code scanning](spec/SPEC-code-scanning.md): CodeQL setup.
- [Releases](spec/SPEC-releases.md): version tags and release notes.
- [Work tracking](spec/SPEC-work-tracking.md): file-based tracking of work items.
- [Architecture diagram](spec/SPEC-architecture-diagram.md): diagram of the system.
- [Data model diagram](spec/SPEC-datamodel-diagram.md): diagram of the database tables.

## Open questions

- Deployment target and environments beyond the developer deployment.