webmanager-mvp/project_docs/REMOTE_CLIENT_SHARES_IMPLEMENTATION_PHASES.md

Remote Client Shares Implementation Phases V1.1

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.

---

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
• 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

Liever niet verbreden:

• 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

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

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.

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.