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

Status: Agent-debugging and browser-version decisions were superseded by the 2026-07-15 Playwright CLI decision below. The Playwright Test and project-local resource decisions remain active.

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.

2026-07-15: Stable Playwright CLI Agent Debugging

Context: The official Playwright MCP package pulled an alpha Playwright core alongside the stable test runner. That required a second Chromium revision and expanded the agent tool surface. Playwright 1.61.1 already provides the same browser-debugging command set through its embedded CLI.

Decisions:

Area	Choice	Guidance
Agent entry point	Stable playwright cli behind the playwright:cli npm script	Run it from web/ with mise exec -- npm run playwright:cli --; do not use a global install, standalone @playwright/cli, playwright-cli, or floating npx.
Version ownership	@playwright/test is the only Playwright dependency	E2E tests and interactive debugging use Playwright 1.61.1 and Chromium revision 1228.
Agent workflow	Repository Skill in .agents/skills/playwright-cli	Start from Playwright's generated Skill, then preserve the MyGO npm wrapper, headless workflow, artifact policy, and debugging principles when updating it.
Browser policy	Bundled Chromium, headless, isolated, and sandboxed	.playwright/cli.config.json is the shared CLI configuration; do not silently disable the Chromium sandbox.
Local resources	Repository .cache/ and .artifacts/ directories	mise.toml redirects XDG, npm, and browser caches; CLI output is limited to 100 MB under .artifacts/playwright-cli/.

Consequences:

• A fresh environment needs one locked npm install, the Debian browser libraries, and the stable Chromium install before E2E or CLI use.
• Changing Playwright's CLI entry point only requires changing the npm script; the repository Skill and operator commands remain stable.
• The official generated references remain available through progressive disclosure, while the main Skill carries only the MyGO-specific workflow.
• The MCP server configuration, alpha Playwright core, and Chromium revision 1232 are no longer required.