# 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](/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/` - `/Clients//` ## 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/` toont alleen toegestane shares - `/Clients//` 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. ### 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.