webmanager-mvp/project_docs/REMOTE_CLIENT_SHARES_IMPLEMENTATION_PHASES.md

# Remote Client Shares Implementation Phases V1.1

## Status

Per huidige repositorystatus zijn de in dit document beschreven implementatiefases afgerond:

- Phase 1: afgerond
- Phase 2: afgerond
- Phase 3: afgerond

Dit document beschrijft geen Phase 4.

De sectie `Later` hieronder blijft expliciet buiten de beschreven fasering van V1.1 en is geen impliciete volgende fase.

## Doel

Dit document splitst `REMOTE_CLIENT_SHARES_V1_DESIGN.md` op in pragmatische implementatiefases.

Uitgangspunten:

- geen overengineering
- elke fase moet zelfstandig waarde leveren
- WebManager mag nooit blokkeren op remote agents
- bestaande storage-functionaliteit moet intact blijven
- `/Clients` blijft een aparte source, geen uitbreiding van lokale filesystem roots

---

## Overzicht

### Phase 1

Client registry, identiteit en statusmodel.

### Phase 2

Browse van remote client shares via virtuele `Clients` root.

### Phase 3

Info, tekstpreview, eenvoudige image preview en download voor remote shares.

### Later

Alle write-acties, bookmarks/startup paths en cross-source flows.

Opmerking:

- `Later` betekent in dit document: bewust uitgestelde scope, niet een gedefinieerde volgende implementatiefase

---

## Phase 1: Client Registry

## Doel

WebManager moet remote agents kennen, identificeren en hun status betrouwbaar kunnen bijhouden.

## Resultaat

De backend en UI kunnen een lijst van bekende clients tonen, inclusief stabiele identiteit en basisstatus.

## In scope

- remote client registratie
- heartbeat endpoint
- opslag van client metadata
- statusmodel met gescheiden velden
- lijstendpoint voor bekende clients
- registratie-auth
- agent-access-auth contract vastleggen

## Niet in scope

- browsen in shares
- file operations
- download
- rename/delete/mkdir

## Beslissingen

- `client_id` is leidend
- `display_name` is niet leidend
- browse-routing mag niet afhankelijk zijn van alleen displaynaam
- `last_seen`, `status`, `last_error` en `reachable_at` blijven logisch gescheiden

## Backendwerk

Nieuwe onderdelen:

- repository voor remote clients
- service voor registratie en heartbeat
- statusafleiding
- opslag van auth- en endpointmetadata
- routes:
  - `POST /api/clients/register`
  - `POST /api/clients/heartbeat`
  - `GET /api/clients`

Waarschijnlijk te wijzigen:

- [main.py](/workspace/webmanager-mvp/webui/backend/app/main.py)
- [dependencies.py](/workspace/webmanager-mvp/webui/backend/app/dependencies.py)

Waarschijnlijk nieuw:

- `webui/backend/app/api/routes_clients.py`
- `webui/backend/app/services/remote_client_service.py`
- `webui/backend/app/db/remote_client_repository.py`

## Agentwerk

- vaste config inlezen
- `client_id` beheren
- registratie naar WebManager
- periodieke heartbeat
- agent-access-token config toevoegen

## UI-werk

Minimaal:

- geen browse-integratie nodig
- een eenvoudige clientlijst of debug-status is voldoende

## Acceptatiecriteria

- agent kan zich registreren
- client verschijnt in `GET /api/clients`
- `last_seen` wordt bijgewerkt
- `status` wordt afgeleid zonder te flappen
- `last_error` en `reachable_at` bestaan als apart concept
- server blijft normaal werken als er geen agents bestaan

---

## Phase 2: Browse via `/Clients`

## Doel

Remote clients en hun shares moeten zichtbaar worden in dezelfde browse-ervaring als server storage, zonder lokale services te vervormen.

## Resultaat

De gebruiker kan navigeren naar:

- `/Clients`
- `/Clients/<client>`
- `/Clients/<client>/<share>`

## In scope

- virtuele root `/Clients`
- clientlijst als directories
- sharelijst per client als directories
- browse binnen share
- offline foutafhandeling
- agent-auth op browsecalls

## Niet in scope

- view/download
- edit
- rename/delete/mkdir
- bookmarks/startup paths

## Beslissingen

- `/Clients` wordt vroeg in de backend-route afgehandeld
- remote paden mogen niet in gewone lokale `PathGuard` resolution terechtkomen
- lokale browse-services blijven verantwoordelijk voor alleen lokale server sources

## Backendwerk

Waarschijnlijk te wijzigen:

- [routes_browse.py](/workspace/webmanager-mvp/webui/backend/app/api/routes_browse.py)

Liever niet verbreden:

- [path_guard.py](/workspace/webmanager-mvp/webui/backend/app/security/path_guard.py)

Nieuwe onderdelen:

- browse-facade voor remote client paden
- agent HTTP client met korte timeouts en auth

## UI-werk

Waarschijnlijk te wijzigen:

- [app.js](/workspace/webmanager-mvp/webui/html/app.js)

Benodigd:

- rootnavigatie voor `/Clients`
- breadcrumbs voor client/share-paden
- render van client/status/share directories
- nette foutmelding bij offline client

## Agentwerk

Nieuwe browse endpoint(s):

- `GET /health`
- `GET /api/list?share=...&path=...`

## Acceptatiecriteria

- `/Clients` toont bekende clients
- `/Clients/<client>` toont alleen toegestane shares
- `/Clients/<client>/<share>` toont directory-inhoud
- offline client geeft een snelle fout, geen hang
- `/Volumes` gedrag blijft intact
- lokale browse-code blijft logisch gescheiden van remote browse-code

---

## Phase 3: Info, Preview, Download

## Doel

Remote shares moeten read-only bruikbaar worden voor dagelijkse taken.

## Resultaat

Gebruiker kan bestanden in remote shares inspecteren, bekijken en downloaden.

## In scope

- file info
- tekstpreview
- eenvoudige image preview
- download van remote bestanden
- expliciete resource-limieten

## Niet in scope

- edit
- rename/delete/mkdir
- upload
- cross-source copy/move

## Beslissingen

- tekstpreview krijgt een harde limiet
- text/binary-detectie moet expliciet zijn
- downloads worden gestreamd
- geen grote in-memory buffering voor download

## Backendwerk

Nieuwe facade of routes voor remote file actions:

- info
- read/view
- download

Belangrijk:

- backend vertaalt WebManager-pad naar agent-call
- timeouts en foutmapping blijven streng
- source-aware afhandeling blijft gescheiden van lokale file ops

Waarschijnlijk geraakt:

- `routes_files.py` of parallelle remote-fileroute
- aparte service-laag voor remote file proxying

## UI-werk

Waarschijnlijk te wijzigen:

- [app.js](/workspace/webmanager-mvp/webui/html/app.js)

Benodigd:

- source-aware afhandeling voor `View`
- downloadknop moet remote paths ondersteunen
- properties/info moet ook werken voor remote paden

## Agentwerk

Nieuwe endpoints:

- `GET /api/info`
- `GET /api/read`
- `GET /api/download`

## Acceptatiecriteria

- file info werkt voor remote paden
- tekstbestand kan bekeken worden binnen limieten
- afbeelding kan bekeken worden als ondersteund
- download van remote bestand werkt via streaming
- foutafhandeling blijft lokaal tot betreffende pane/actie

---

## Later

Deze onderdelen horen niet in V1.1.

Status:

- deze onderdelen blijven expliciet buiten de afgeronde Phase 1 t/m Phase 3 scope
- voor deze onderdelen bestaat in dit document geen aparte vervolgfase

### Write-acties

- mkdir
- rename
- delete
- upload

### UI-integraties

- bookmarks voor `/Clients/...`
- startup paths voor `/Clients/...`

### Cross-source flows

- `/Volumes/...` naar `/Clients/...`
- `/Clients/...` naar `/Volumes/...`

Dit vereist expliciete transfersemantiek en hoort niet in de eerste read-mostly release.

### Zwaardere netwerkmodellen

- reverse-connect
- tunnelmodel
- relay-infrastructuur

### Sterkere pairing

- pair codes
- per-agent secret rotation
- signed registration

---

## Aanbevolen volgorde

1. Phase 1 volledig afronden.
2. Daarna Phase 2 volledig afronden.
3. Daarna Phase 3 read-only afronden.
4. Alles daarna alleen oppakken als een concrete productbehoefte dat rechtvaardigt.

---

## Beslisadvies

Als er snel waarde geleverd moet worden, is de beste minimale keten:

1. registry
2. browse
3. info/preview/download

Daarmee ontstaat een bruikbare remote client bron zonder write-complexiteit, contractbreuk in lokale services of half-afgewerkte transferlogica.