Improve developer integration docs and Docker dev workflow.

Add TypeScript frontend integration documentation, repository agent guidance files, Go-served frontend routing, and an advanced Docker Compose setup with watch mode plus BuildKit cache configuration.

Made-with: Cursor

docs/typescript-frontend-integration.md

@@ -0,0 +1,99 @@
+# TypeScript Frontend Integration Guide
+
+This document explains how frontend developers should integrate with the backend through the reusable TypeScript client at `libs/geo-api-client`.
+
+## Goals
+
+- Keep cryptographic signing logic in one place.
+- Avoid duplicating API request code in frontend apps.
+- Use a consistent local key storage format across projects.
+
+## Client package location
+
+- Source: `libs/geo-api-client/src`
+- Entry point: `libs/geo-api-client/src/index.ts`
+- Build output (browser ESM): `libs/geo-api-client/dist/index.js`
+
+## Build and test the client
+
+```bash
+cd libs/geo-api-client
+bun install
+bun test
+bun run build
+```
+
+## Public API (current)
+
+### Class: `GeoApiClient`
+
+Constructor:
+
+- `new GeoApiClient(baseUrl, storage, storageKey?)`
+
+Key methods:
+
+- `ensureKeysInStorage()`
+- `getStoredKeys()`
+- `importKeys(keys)`
+- `exportKeys()`
+- `setAccessToken(token)`
+- `createChallenge(publicKey)`
+- `loginWithSignature(publicKey, privateKey)`
+- `createInvitation(payload, inviterPrivateKey)`
+- `registerWithInvitation(...)`
+- `listCollections()`
+- `createCollection(name)`
+- `listFeatures(collectionId)`
+- `createPointFeature(collectionId, lon, lat, properties)`
+
+## Recommended integration flow
+
+1. Create one `GeoApiClient` instance per backend base URL.
+2. Call `ensureKeysInStorage()` when app initializes.
+3. Use `loginWithSignature()` to obtain and set a bearer token.
+4. Call collection/feature methods after authentication.
+5. Use `importKeys`/`exportKeys` in profile settings UX.
+
+## Example (TypeScript app)
+
+```ts
+import { GeoApiClient } from "../libs/geo-api-client/dist/index.js";
+
+const storage = window.localStorage;
+
+const storageLike = {
+  getItem: (key: string) => storage.getItem(key),
+  setItem: (key: string, value: string) => storage.setItem(key, value),
+  removeItem: (key: string) => storage.removeItem(key),
+};
+
+const client = new GeoApiClient("http://localhost:8080", storageLike);
+
+const keys = await client.ensureKeysInStorage();
+await client.loginWithSignature(keys.publicKey, keys.privateKey);
+
+const created = await client.createCollection("My Places");
+await client.createPointFeature(created.id, -16.6291, 28.4636, { name: "Santa Cruz" });
+const features = await client.listFeatures(created.id);
+console.log(features);
+```
+
+## Security notes
+
+- Private keys are currently stored in browser storage via the selected storage adapter.
+- If your frontend has stronger security requirements, wrap the storage adapter with your own encryption/decryption layer before calling `setItem`/`getItem`.
+- Never send private keys to the backend.
+
+## No-build frontend compatibility
+
+For no-bundler apps, import the built ESM file:
+
+```html
+<script type="module">
+  import { GeoApiClient } from "../libs/geo-api-client/dist/index.js";
+  // use client...
+</script>
+```
+
+The backend itself serves static UI at `/web/`, but this library can be consumed by any frontend runtime that supports `fetch`, `TextEncoder`, and ES modules.