Ready2Blob/.planning/PROJECT.md

Ready2Blob

What This Is

Ready2Blob is a pure-frontend web app that helps IT professionals deploy rclone onto end-user Windows PCs. A step-by-step wizard collects backend credentials (Azure Blob, S3, S3-compatible, OneDrive, SFTP, Google Cloud Storage, Backblaze B2) and deployment preferences, then generates rclone config files and PowerShell scripts ready to push via Intune or any RMM tool — all client-side, no server required.

Core Value

An IT pro can go from zero to a deployable rclone setup in minutes — without needing to know rclone's config syntax or PowerShell deployment conventions.

Current State

Shipped: v1.1 — 2026-03-31 Backends: 7 (Azure Blob, S3, S3-compatible, OneDrive, SFTP, GCS, Backblaze B2) Tech stack: Vite 6, React 18, TypeScript 5, Tailwind v4, react-hook-form 7, Zod 4, Vitest 4, JSZip Test coverage: 159 tests across all test files — all GREEN Total milestones: 2 shipped (v1.0 + v1.1), 7 phases, 29 plans

Next Milestone Goals

(Not yet defined — run /gsd:new-milestone to start next milestone)

Constraints

• Architecture: Pure static frontend — no backend, no server required
• Target OS: Windows endpoints only (scripts are PowerShell)
• Secrets: Plain text in generated files — UI must display a clear security warning before download

Out of Scope

• User accounts / saved templates — no backend, no persistence
• Server-side generation — everything runs in the browser
• Test connection / validate credentials — requires backend proxy (CORS blocks direct cloud API calls)
• rclone version management / auto-update on endpoints — separate lifecycle problem
• Non-Windows targets — scripts target Windows endpoints only
• Auto-push to Intune via Graph API — requires Azure AD app registration, massive scope increase
• Config credential encryption — rclone encrypted configs require interactive unlock, incompatible with unattended deployment
• Multiple remotes in one config — significant wizard UX complexity, defer to v2
• OAuth flow in browser (OneDrive) — requires backend proxy; paste pre-obtained token instead

Key Decisions

Decision	Rationale	Outcome
Pure frontend (no backend)	Simpler hosting, no data retention risk with credentials	✓ Good — static site deployable anywhere
BACKEND_REGISTRY as single source of truth	Drives form rendering, Zod schemas, and config generation from one definition	✓ Good — zero duplication across phases
useReducer + Context API (no external state lib)	Zero dependencies, sufficient for 4-step wizard	✓ Good — kept bundle lean
Wave 0 TDD (stubs RED before implementation)	Forces API contract before code, catches integration mismatches early	✓ Good — caught several issues upfront
Support all rclone backends (not Azure-only)	Broader utility despite "Blob" in project name	✓ Good — 7 backends and growing
Optional rclone install in scripts	Different orgs have different baseline images	✓ Good — no friction for orgs that pre-install
Tailwind v4 via @tailwindcss/vite plugin	No postcss.config.js, no tailwind.config.js needed	✓ Good — cleaner config
Zod v4 + @hookform/resolvers v5 together	v5 resolvers required for Zod v4 compatibility	✓ Good — noted for future upgrades
AzureAuthToggle / SftpAuthToggle CSS hidden pattern	Preserves both auth fields in react-hook-form state when toggling	✓ Good — avoids field reset on toggle
FieldDef.validate + tooltipText extension	Additive interface change, non-breaking to existing backends	✓ Good — clean composition
Registry-loop rendering in RemoteConfigStep	Three-branch ternary (azureblob/sftp/else) — custom logic minimal	✓ Good — scales with new backends

Previous milestone context (v1.0 → v1.1)

v1.0 shipped: 2026-03-27, 4 phases, 18 plans, ~2,746 LOC v1.1 shipped: 2026-03-31, 3 phases, 11 plans, +7,311 lines

v1.0 tech debt resolved in v1.1:

• scriptTargets filtering in ReviewStep (TECH-01)
• ReviewStep Back button (TECH-02)
• Registry-driven BackendSelectionStep (TECH-03)
• Dead export removal (TECH-04)
• act() warnings fix (TECH-05)

v1.1 remaining tech debt:

• 7 browser UI verifications pending (confirmatory)
• FieldRenderer aria inconsistency (cosmetic)
• Phase 7 Nyquist compliance partial

---

Last updated: 2026-03-31 after v1.1 milestone completed