mygo/docs/web/decisions.md

Technical Decisions

2026-07-14: Client-rendered Web Foundation

Context: MyGO needs a browser client now and native clients later. The Web application must share the versioned REST API instead of introducing browser-only server logic.

Decisions:

Area	Choice	Guidance
Rendering	Pure client-side rendered SPA	Vite emits static assets; do not introduce SSR, React Server Components, or a Node API server.
Application stack	React, strict TypeScript, React Router, and TanStack Query	Keep routing and remote-data state explicit and client-side.
UI system	Ant Design plus Tailwind CSS 4	Ant Design owns reusable controls and theme tokens; Tailwind initially owns layout, spacing, and responsive utilities.
Dependency policy	Install capabilities when their feature starts	Keep API generation, transfer, virtualization, drag-and-drop, test, and preview libraries deferred in docs/web/roadmap.md.

Consequences:

• The Web and future native clients consume the same client-neutral API contracts.
• MyGO or a reverse proxy may host web/dist with an SPA fallback without changing the rendering model.
• MyGO domain components own file-browser behavior and must not depend on Ant Design request behavior for business logic.

2026-07-14: Browser Authentication and Root File Workflow

Context: The first Web milestone needs to exercise the existing login, file list, upload, and download APIs without committing to the later directory, account, admin, or large-transfer designs.

Decisions:

Area	Choice	Guidance
API topology	Same-origin /api/v1	Vite proxies /api to the local Go server. Production uses a same-origin reverse proxy; the milestone does not add CORS or Go static hosting.
Browser session	Token pair in sessionStorage	Reloading the tab preserves the session, while closing the tab clears it. Do not add persistent login until the token transport design is revisited.
Token refresh	Refresh once after a protected request returns 401	Share one in-flight refresh across concurrent failures, store the rotated pair, and retry each request once. Clear the session if refresh or the retry fails.
File scope	Root directory only	List root entries, upload one file to root, and download files. Show directories as non-interactive rows.
Transfer model	Browser FormData upload and authenticated Blob download	This is intentionally limited to the small-file milestone; progress, streaming-to-disk, chunking, resume, and queues remain deferred.

Consequences:

• The API client owns bearer headers, error parsing, refresh coordination, and session invalidation; pages consume operation-specific functions.
• TanStack Query caches are cleared whenever an authenticated session ends so one user cannot see another user's cached file metadata.
• The file picker is independent of Ant Design upload request behavior, keeping transfer policy in MyGO code.
• Handwritten TypeScript wire types remain temporary until an OpenAPI contract is available.

2026-07-14: Project-local Headless Browser Tooling

Context: Browser behavior needs deterministic E2E coverage and interactive agent debugging inside a long-lived headless Debian Incus container. Tooling should remain reproducible without placing browser binaries or generated artifacts in a developer's home directory.

Decisions:

Area	Choice	Guidance
Regression tests	Playwright Test with bundled Chromium	Keep browser E2E tests separate from npm run check because browser installation is an explicit environment setup step.
Agent debugging	Official Playwright MCP over project-scoped STDIO	Codex starts the locked local package from .codex/config.toml; do not use a global install, an @latest npx invocation, or a listening MCP service.
Browser state	Headless, isolated, and sandboxed	Use bundled Chromium, discard the MCP profile after each session, and retain the Chromium sandbox supported by the Incus environment.
Local resources	Repository .cache/ and .artifacts/ directories	mise.toml defines the portable npm and browser cache paths. Generated resources remain ignored by Git.
Browser versions	Install both locked Playwright revisions	The stable test runner and current MCP package require different Chromium revisions; do not force either package onto an unsupported executable.

Consequences:

• Debian browser libraries are installed once in the Incus container root filesystem; npm packages, browsers, traces, screenshots, and MCP output stay project-scoped.
• A fresh environment runs npm ci, the system dependency installer, and both browser install scripts before browser tests or MCP debugging.
• Browser failures can retain traces, screenshots, and video under .artifacts/playwright/ without adding generated files to source control.