Andriy Oblivantsev
e981a334ea
CI / test (push) Successful in 5s
This introduces a MapLibre GL + Three.js web demo for object placement and sharing, and changes asset upload flow to use backend upload endpoints so clients no longer receive direct MinIO URLs. Made-with: Cursor
98 lines
3.5 KiB
Markdown
98 lines
3.5 KiB
Markdown
# 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
|
|
|
|
```text
|
|
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:
|
|
```bash
|
|
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
|
|
- 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.
|
|
|
|
```bash
|
|
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](typescript-frontend-integration.md) | API client usage and integration flow |
|
|
| [Assets Storage and Sharing](assets-storage-and-sharing.md) | Asset lifecycle, deduplication, visibility, API endpoints |
|
|
| [Docker MinIO Local Development](docker-minio-local-dev.md) | Local object storage topology and verification |
|
|
| [Ed25519 Security Use Cases](ed25519-security-use-cases.md) | Auth and signature behavior |
|
|
| [Geo Auth Backend Plan](geo-auth-backend-plan.md) | Architecture and planning history |
|