docs: restructure server and web documentation into ADR files and a
routing table
This commit is contained in:
+9
-100
@@ -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 |
|
||||
|
||||
@@ -0,0 +1,24 @@
|
||||
# ADR-0001: Use a Client-Rendered Web Foundation
|
||||
|
||||
Status: Accepted
|
||||
Date: 2026-07-14
|
||||
|
||||
## Context
|
||||
|
||||
MyGO needs a browser client and expects native clients to consume the same application API.
|
||||
|
||||
## Decision
|
||||
|
||||
- Build a client-side application with Vite, React, and strict TypeScript.
|
||||
- Use React Router for navigation and TanStack Query for remote state.
|
||||
- Use Ant Design for reusable controls and theme tokens.
|
||||
- Use Tailwind CSS for layout, spacing, and responsive utilities.
|
||||
- Keep business API contracts client-neutral.
|
||||
- Select additional dependencies when their feature is designed.
|
||||
|
||||
## Consequences
|
||||
|
||||
- Vite emits static assets for same-origin deployment.
|
||||
- The Web project contains no SSR, React Server Components, or Node application server.
|
||||
- Browser and native clients share the versioned REST API.
|
||||
- MyGO components own file-browser and transfer behavior; Ant Design supplies presentation controls.
|
||||
@@ -0,0 +1,26 @@
|
||||
# ADR-0002: Implement Browser Auth and the Root File Workflow
|
||||
|
||||
Status: Accepted
|
||||
Date: 2026-07-14
|
||||
|
||||
## Context
|
||||
|
||||
The first Web milestone needed an authenticated workflow over the existing login, file listing, upload, and download APIs.
|
||||
|
||||
## Decision
|
||||
|
||||
- Use same-origin `/api/v1` requests.
|
||||
- Store the access and refresh token pair in `sessionStorage`.
|
||||
- Coordinate one refresh request across concurrent `401` responses.
|
||||
- Retry each failed protected request once after refresh.
|
||||
- Clear the session when refresh or the retry fails.
|
||||
- List root entries and upload one file at a time to the root directory.
|
||||
- Download authenticated file responses as browser blobs.
|
||||
|
||||
## Consequences
|
||||
|
||||
- Reloading the tab preserves the session; closing the tab clears it.
|
||||
- Query caches clear when the authenticated session ends.
|
||||
- Directories appear as non-interactive root rows in the first milestone.
|
||||
- Handwritten wire types remain until a shared OpenAPI contract is available.
|
||||
- Directory management and large-transfer workflows require later feature decisions.
|
||||
@@ -0,0 +1,22 @@
|
||||
# ADR-0003: Keep Browser Testing Resources Project-Local
|
||||
|
||||
Status: Accepted
|
||||
Date: 2026-07-14
|
||||
|
||||
## Context
|
||||
|
||||
Browser tests and diagnostics run in a headless Debian development container. The toolchain needs repeatable versions and repository-scoped resources.
|
||||
|
||||
## Decision
|
||||
|
||||
- Use Playwright Test with bundled Chromium for repeatable E2E tests.
|
||||
- Keep E2E tests separate from `npm run check` because browser installation is an explicit setup step.
|
||||
- Run Chromium headlessly with profile isolation and sandboxing.
|
||||
- Store npm and browser caches under `.cache/`.
|
||||
- Store traces, screenshots, videos, and CLI output under `.artifacts/`.
|
||||
|
||||
## Consequences
|
||||
|
||||
- A fresh environment installs npm dependencies, browser libraries, and the pinned Chromium revision before browser work.
|
||||
- Browser failures can retain diagnostics without adding generated files to source control.
|
||||
- Repository configuration controls browser versions and artifact locations.
|
||||
@@ -0,0 +1,12 @@
|
||||
# ADR-0004: Use Playwright MCP for Agent Debugging
|
||||
|
||||
Status: Superseded by [ADR-0005](0005-playwright-cli-debugging.md)
|
||||
Date: 2026-07-14
|
||||
|
||||
## Historical Decision
|
||||
|
||||
The project initially selected a repository-scoped Playwright MCP process for interactive agent debugging.
|
||||
|
||||
## Current Guidance
|
||||
|
||||
[ADR-0005](0005-playwright-cli-debugging.md) defines the current browser-debugging entry point. [ADR-0003](0003-project-local-browser-testing.md) defines the browser test and resource policy that remains active.
|
||||
@@ -0,0 +1,23 @@
|
||||
# ADR-0005: Use the Pinned Playwright CLI for Agent Debugging
|
||||
|
||||
Status: Accepted
|
||||
Date: 2026-07-15
|
||||
|
||||
## Context
|
||||
|
||||
The Playwright MCP package introduced a second Playwright core, a second Chromium revision, and a larger agent tool surface. The pinned test runner provides the required interactive commands through its CLI.
|
||||
|
||||
## Decision
|
||||
|
||||
- Use the `playwright:cli` npm script as the browser-debugging entry point.
|
||||
- Use `@playwright/test` as the Playwright dependency for tests and diagnostics.
|
||||
- Use the bundled Chromium revision selected by the pinned package.
|
||||
- Load `.playwright/cli.config.json` for headless, isolated, and sandboxed execution.
|
||||
- Use the repository-scoped `$playwright-cli` skill for agent browser work.
|
||||
- Limit CLI output under `.artifacts/playwright-cli/`.
|
||||
|
||||
## Consequences
|
||||
|
||||
- E2E tests and interactive diagnostics share one Playwright core and Chromium revision.
|
||||
- The npm script isolates operators and agents from upstream CLI entry-point changes.
|
||||
- The repository skill keeps the main workflow concise and exposes detailed references on demand.
|
||||
+26
-51
@@ -1,65 +1,40 @@
|
||||
# Web Roadmap
|
||||
|
||||
## Product Boundary
|
||||
## Product Model
|
||||
|
||||
- The Web client is a pure client-side rendered single-page application.
|
||||
- Vite produces static assets only. The project does not use SSR, React Server Components, a Node API server, or a browser-specific business backend.
|
||||
- The Web client consumes the same versioned REST API as future Android and other native clients.
|
||||
- Production may serve `web/dist` from MyGO or a reverse proxy.
|
||||
- Shared API contracts should remain client-neutral and eventually be described by OpenAPI.
|
||||
MyGO Web is a client-side application built by Vite. It consumes the same `/api/v1` REST API as native clients. Production can serve `web/dist` from MyGO or a same-origin reverse proxy.
|
||||
|
||||
## Current Milestone
|
||||
## Available Capabilities
|
||||
|
||||
The browser client now provides the first authenticated file workflow:
|
||||
- Email and password login
|
||||
- Access and refresh tokens stored for the browser session
|
||||
- One coordinated refresh retry after an authenticated request returns `401`
|
||||
- Protected application shell
|
||||
- Root file listing with 50 items per page
|
||||
- Single-file upload to the root directory
|
||||
- Authenticated file download
|
||||
- Responsive Ant Design interface with Tailwind layout utilities
|
||||
- Unit tests for the API client and session behavior
|
||||
- Playwright smoke tests and repository-scoped browser diagnostics
|
||||
|
||||
- Email/password login through the shared REST API
|
||||
- Session-scoped access and refresh tokens with one automatic refresh retry
|
||||
- Protected application shell and root file list
|
||||
- Single-file upload to the root directory and authenticated download
|
||||
- Server-side pagination with 50 items per page
|
||||
|
||||
Directory navigation and management, multi-file queues, transfer progress,
|
||||
resumable or chunked transfers, account/profile/settings screens, and admin
|
||||
screens remain deferred.
|
||||
|
||||
## Foundation
|
||||
|
||||
The project foundation contains:
|
||||
|
||||
- Node.js 24 and npm
|
||||
- Vite
|
||||
- React
|
||||
- TypeScript in strict mode
|
||||
- TanStack Query provider
|
||||
- Tailwind CSS 4 through its Vite plugin
|
||||
- Ant Design provider and components
|
||||
- Ant Design icons for application and file actions
|
||||
- Oxlint from the Vite template
|
||||
- Vitest for framework-independent client and session tests
|
||||
- Playwright Test with a headless Chromium smoke test
|
||||
- Project-scoped Playwright CLI and repository Skill for interactive browser debugging
|
||||
|
||||
Ant Design owns reusable UI components and theme tokens. Tailwind CSS is initially limited to application layout, spacing, and responsive utilities.
|
||||
|
||||
## Planned Structure
|
||||
## Current Structure
|
||||
|
||||
```text
|
||||
web/src/
|
||||
├── app/ # Router, providers, and application composition
|
||||
├── api/ # API client and generated contracts
|
||||
├── api/ # API client, session storage, and wire types
|
||||
├── app/ # Router, providers, and authentication guard
|
||||
├── components/ # Shared presentation components
|
||||
├── features/ # Auth, files, account, and admin features
|
||||
├── pages/ # Route entry points
|
||||
├── lib/ # Framework-independent utilities
|
||||
└── test/ # Shared test setup and fixtures
|
||||
├── features/ # Feature hooks and state
|
||||
└── pages/ # Route entry points
|
||||
```
|
||||
|
||||
## Deferred Dependencies
|
||||
## Planned Capabilities
|
||||
|
||||
Some dependencies are suggested for future implementation. Refer these only when the corresponding feature is implemented and propose better choices if any:
|
||||
- Directory navigation and management
|
||||
- Account, settings, and administrator screens
|
||||
- Shared OpenAPI contracts and generated client types
|
||||
- Multi-file transfer queues and progress reporting
|
||||
- Resumable large-file transfers
|
||||
- Document preview
|
||||
|
||||
- `openapi-typescript`: Generate TypeScript API types from the shared OpenAPI document.
|
||||
- `openapi-fetch`: Provide a small type-safe Fetch client based on generated OpenAPI types.
|
||||
- `openapi-react-query`: Connect generated OpenAPI operations to TanStack Query if handwritten query adapters become repetitive.
|
||||
- `zustand`: Manage a cross-route upload queue, bulk selection, or other complex client-only state if React state is insufficient.
|
||||
- `pdfjs-dist`: Preview PDF files in the browser when document preview is implemented.
|
||||
Select dependencies when designing the capability that requires them. Record significant choices in the Web decision log.
|
||||
|
||||
Reference in New Issue
Block a user