backend/docs/frontend-development.md

Frontend Development

Development guide for the demo frontend in web/ and the reusable TypeScript client in libs/geo-api-client.

Architecture

• web/ is a no-bundler Vue + Vuetify app served directly by the Go backend at /web/.
• libs/geo-api-client contains signed auth and API request logic reused by frontend code.
• Asset binaries are stored in S3-compatible storage, while frontend works with metadata and service-relative links returned by the API.

Demo app (web/)

File map

web/
├── index.html    # Entry page, loads Vue/Vuetify from CDN
├── app.js        # Main app state and handlers
├── api.js        # GeoApiClient wrapper for browser usage
├── qr.js         # QR code generation for key sharing/backup
└── scanner.js    # Camera QR scanner for key import

Local run

1. Start backend:

   go run ./cmd/api
   # or
   docker compose up -d
   

2. Open:
   • http://localhost:8122/web/
   • http://localhost:8122/web/leaflet-demo.html (Leaflet map demo for 3D/image placement + sharing)
   • http://localhost:8122/web/maplibre-demo.html (MapLibre GL vector tiles + Three.js object rendering/placement)

Runtime dependencies

• Vue 3 and Vuetify 3 from CDN (no package manager in web/)
• libs/geo-api-client/dist/index.js (ESM build artifact)
• qrcode via esm.sh in qr.js
• jsQR via esm.sh in scanner.js

Supported UI flows

• Connection and identity:
  • API URL configuration
  • key generation
  • pk/pb display and QR export
  • restore/import keypair from QR
  • register and login
• Collection management:
  • create, select, rename, delete
• Feature management:
  • add/list/delete points
  • lon/lat validation (-180..180, -90..90)
• Asset-ready feature rendering:
  • read linked media from feature.properties.assets
  • use relative link value (for example /v1/assets/{id}/download) for fetch/open
• Leaflet map example:
  • click map to place object coordinates
  • create feature + upload/link gltf/glb/image asset
  • upload via backend endpoint (/v1/assets/{id}/upload)
  • copy/open share link and toggle public/private visibility
• MapLibre GL + Three.js example:
  • vector tile basemap via MapLibre style
  • map click to place object position
  • 3D marker rendering in custom Three.js layer
  • asset upload/link and share/visibility controls backed by API

TypeScript client (libs/geo-api-client)

The TypeScript client centralizes auth signatures and API requests.

cd libs/geo-api-client
bun install
bun test
bun run build

After client changes, rebuild before loading the demo app. Docker image builds handle this automatically.

Frontend implementation notes for assets

• Treat properties.assets as backend-owned metadata. Do not derive URLs in frontend from S3 config.
• Always use backend-provided relative link for downloads so permission checks remain server-side.
• When asset visibility changes (isPublic), refresh affected feature list to keep UI in sync.

Related docs

Document	Description
TypeScript Frontend Integration	API client usage and integration flow
Assets Storage and Sharing	Asset lifecycle, deduplication, visibility, API endpoints
Docker MinIO Local Development	Local object storage topology and verification
Ed25519 Security Use Cases	Auth and signature behavior
Geo Auth Backend Plan	Architecture and planning history