# Assets Storage and Sharing

This backend stores metadata for user-owned image and 3D assets and keeps the binary files in S3-compatible object storage.

## Supported asset types

- Images: `jpg`, `jpeg`, `png`, `webp`
- 3D objects: `gltf`, `glb`

## Data model

- Assets are deduplicated per user by `(owner_key, checksum, ext)`.
- Canonical object key: `<publicKey>/<checksum>.<ext>`.
- A single asset can be linked to many features.
- Feature payloads include linked assets under `properties.assets`.

Each `properties.assets` item includes:

- `id`
- `kind`
- `name`
- `description`
- `checksum`
- `ext`
- `isPublic`
- `link` (service-relative path, for example `/v1/assets/{id}/download`)

## API flow

1. Create or reuse an asset record and link it to a feature:
   - `POST /v1/assets`
2. Upload the binary to object storage:
   - `POST /v1/assets/{id}/signed-upload` (returns signed PUT URL)
3. Read linked assets from feature responses:
   - `GET /v1/collections/{id}/features` (`properties.assets`)
4. Download via service-relative link:
   - `GET /v1/assets/{id}/download`
5. Change visibility:
   - `PATCH /v1/assets/{id}` with `{"isPublic": false|true}`

## Visibility rules

- Owner can always download their own asset.
- Other authenticated users can download only when `isPublic=true`.
- Owner can toggle `isPublic` at any time.

## Spatial readiness for 3D search

Feature storage is prepared for future spatial search:

- Features keep GeoJSON `geometry` JSON.
- Postgres migration also maintains a 3D-capable PostGIS column (`geom geometry(PointZ, 4326)`).
- This enables future cube/sphere search without breaking existing API contracts.