MyGO/mygo
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: restructure server and web documentation into ADR files and a

Browse Source 
routing table
This commit is contained in:
Sunday
2026-07-17 22:07:55 +08:00
parent f8494a44ca
commit 519aa35f1f
23 changed files with 710 additions and 654 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/web/decisions.md
+9 -100
View File
@@ -1,102 +1,11 @@
# Technical Decisions
# Web Decisions
## 2026-07-14: Client-rendered Web Foundation
Read the ADRs relevant to the current change. Accepted records define active decisions. Superseded records preserve history and link to current guidance.
**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.
| ADR | Date | Status | Decision |
|-----|------|--------|----------|
| [ADR-0001](decisions/0001-client-rendered-foundation.md) | 2026-07-14 | Accepted | Use a client-rendered Web foundation |
| [ADR-0002](decisions/0002-browser-auth-root-files.md) | 2026-07-14 | Accepted | Implement browser auth and the root file workflow |
| [ADR-0003](decisions/0003-project-local-browser-testing.md) | 2026-07-14 | Accepted | Keep browser testing resources project-local |
| [ADR-0004](decisions/0004-playwright-mcp-debugging.md) | 2026-07-14 | Superseded | Use Playwright MCP for agent debugging |
| [ADR-0005](decisions/0005-playwright-cli-debugging.md) | 2026-07-15 | Accepted | Use the pinned Playwright CLI for agent debugging |