diff --git a/AGENTS.md b/AGENTS.md index f95616f..901c008 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,28 +1,36 @@ -# AGENTS.md — MyGO Backend +# AGENTS.md — MyGO -## Project Essentials +## Project Layout -- Module: `github.com/dhao2001/mygo`, Go 1.26.2 -- WebDisk (cloud drive) backend; roadmap in `docs/roadmap.md` -- CLI framework: `github.com/spf13/cobra` -- Go version pinned in `mise.toml` +- Server: Go backend in the repository root, with documentation in `docs/server/` +- Web: React client in `web/`, with documentation in `docs/web/` +- Documentation index: `docs/README.md` ## Agent Workflow -1. Read the task -2. Read relevant `docs/` files for context +1. Read the task and identify the affected project +2. Read `docs/README.md` and the relevant project documentation for context 3. Explore existing code before writing new code -4. Implement following the conventions below -5. Verify: `go vet ./... && go test ./...` -6. Update `docs/roadmap.md`, `docs/decisions.md`, or `docs/architecture.md` if anything changed +4. Implement following the relevant project conventions below +5. Run the verification commands for every affected project +6. Update the relevant project roadmap, decisions, architecture, or development documentation if anything changed -## Repository Review +## Server — Go Backend + +### Project Essentials + +- Module: `github.com/dhao2001/mygo`, Go 1.26.2 +- WebDisk (cloud drive) backend; roadmap in `docs/server/roadmap.md` +- CLI framework: `github.com/spf13/cobra` +- Go version pinned in `mise.toml` + +### Repository Review - Explicitly invoke `$mygo-api-repo-review` for repository-wide or scoped architecture, design, security, resilience, data-consistency, performance, and implementation audits. - Repository reviews are read-only unless the user separately requests fixes. - Use `diff`, `main`, or `full` review mode and optionally limit any mode with a target path, Go package, or logical component. -## Go Conventions +### Go Conventions - **Format**: `go fmt ./...` before every commit - **Imports**: stdlib / third-party / internal, blank-line separated @@ -32,19 +40,63 @@ - **`init()`**: only in cobra cmd files for flag registration - **`cmd/`** is thin; business logic goes in `internal/` -## Documentation +### Documentation | File | Read Before | Update After | |------|-------------|--------------| -| `docs/architecture.md` | Adding new packages | Adding new packages | -| `docs/decisions.md` | Making technical decisions | Making technical decisions | -| `docs/roadmap.md` | Every task | Completing a feature | -| `docs/development.md` | Build/test/debug setup | Changing workflow | +| `docs/server/architecture.md` | Adding new packages | Adding new packages | +| `docs/server/decisions.md` | Making technical decisions | Making technical decisions | +| `docs/server/roadmap.md` | Every server task | Completing a server feature | +| `docs/server/development.md` | Build/test/debug setup | Changing server workflow | + +### Commands + +```bash +go build ./... # build all packages +go test ./... # all tests +go vet ./... # static analysis +go fmt ./... # format +go mod tidy # clean deps after add/remove +``` + +### Server DO / DON'T + +- DO put business logic in `internal/`, keep `cmd/` thin +- DO add all Go module dependencies **before** writing code that uses them +- DON'T read `go.sum` entirely into context — use `grep` or other tools to search specific patterns if needed +- DON'T skip `go vet ./...` before finishing server work +- DON'T add, remove, or change Go module dependencies after debugging has started — ask for explicit permission first + +## Web — React Client + +### Project Essentials + +- Source: `web/` +- Pure client-side rendered application; roadmap in `docs/web/roadmap.md` +- Stack: Node.js 24, Vite, React, TypeScript, React Router, TanStack Query, Tailwind CSS 4, and Ant Design +- Node.js version pinned in `mise.toml` + +### Documentation + +| File | Read Before | Update After | +|------|-------------|--------------| +| `docs/web/decisions.md` | Making Web technical decisions | Making Web technical decisions | +| `docs/web/roadmap.md` | Every Web task | Completing a Web feature or changing the Web plan | + +### Commands + +Run from `web/`: + +```bash +npm ci # install locked dependencies +npm run dev # start the development server +npm run check # lint, type-check, and build +``` ## Git Version Control - DON'T create a commit unless the user explicitly asks for one. -- Before any commit, verify the work with the required project checks. For code changes, run `go vet ./... && go test ./...`; for docs-only changes, run the most relevant non-mutating checks if available. +- Before any commit, verify the work with the required project checks. For code changes, run the checks for every affected project; for docs-only changes, run the most relevant non-mutating checks if available. - Create a commit only when all required checks pass and the current implementation area has no unresolved issues. - If a known failing check or unresolved issue belongs to another module and is outside the current task, report it clearly before asking for commit approval. - Before running `git commit`, write the complete commit message first, show it to the user, and ask for explicit approval. DON'T commit until the user approves that exact message. @@ -78,25 +130,10 @@ feat(middleware): add AdminRequired authorization middleware - test: admin passes, non-admin forbidden, soft-deleted admin rejected, missing user ID. ``` -## Commands +## Shared DO / DON'T -```bash -go build ./... # build all packages -go test ./... # all tests -go vet ./... # static analysis -go fmt ./... # format -go mod tidy # clean deps after add/remove -``` - -## DO / DON'T - -- DO put business logic in `internal/`, keep `cmd/` thin - DO write all code, comments, and documentation in English -- DO add all Go module dependencies **before** writing code that uses them -- DON'T read `go.sum` entirely into context — use `grep` or other tools to search specific patterns if needed -- DON'T skip `go vet ./...` before finishing work - DON'T commit without following the Git Version Control rules above -- DON'T add, remove, or change Go module dependencies after debugging has started — ask for explicit permission first ## Debugging Principles diff --git a/README.md b/README.md index f064a81..ab514f6 100644 --- a/README.md +++ b/README.md @@ -39,10 +39,10 @@ MyGO is a WebDisk (cloud drive) server, written in Go. ## Frontend -The frontend uses React + TypeScript and communicates with the backend via HTTP API. Frontend source is maintained in a separate repository. +The frontend uses React + TypeScript and communicates with the backend via HTTP API. Frontend source is maintained in `web/`. --- ## Development -See `docs/development.md` for build and test workflows. See `AGENTS.md` for behavioral conventions. +See `docs/README.md` for the server and Web documentation index. See `AGENTS.md` for behavioral conventions. diff --git a/docs/README.md b/docs/README.md index 6c6e586..54851e4 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,8 +1,19 @@ # Docs +Documentation is organized by project. Use `server/` for the Go backend and `web/` for the browser client. + +## Server + | File | Content | |------|---------| -| `architecture.md` | Module layout, package boundaries | -| `decisions.md` | Technical decisions (ADR) | -| `roadmap.md` | Feature progress and status | -| `development.md` | Build, test, debug workflow | +| `server/architecture.md` | Module layout, package boundaries | +| `server/decisions.md` | Technical decisions (ADR) | +| `server/roadmap.md` | Feature progress and status | +| `server/development.md` | Build, test, debug workflow | + +## Web + +| File | Content | +|------|---------| +| `web/decisions.md` | Technical decisions (ADR) | +| `web/roadmap.md` | Product boundary, foundation, planned structure, and deferred dependencies | diff --git a/docs/architecture.md b/docs/server/architecture.md similarity index 100% rename from docs/architecture.md rename to docs/server/architecture.md diff --git a/docs/decisions.md b/docs/server/decisions.md similarity index 87% rename from docs/decisions.md rename to docs/server/decisions.md index 726276c..99ea246 100644 --- a/docs/decisions.md +++ b/docs/server/decisions.md @@ -106,21 +106,3 @@ - REST remains a handler/API concern, and future protocols can reuse services without HTTP leakage. - Error responses keep the same top-level shape, with optional `log_id` instead of embedding log references in the message. - Admin and auth middleware behavior is testable through service contracts rather than database access. - -## 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. diff --git a/docs/development.md b/docs/server/development.md similarity index 100% rename from docs/development.md rename to docs/server/development.md diff --git a/docs/roadmap.md b/docs/server/roadmap.md similarity index 100% rename from docs/roadmap.md rename to docs/server/roadmap.md diff --git a/docs/web/decisions.md b/docs/web/decisions.md new file mode 100644 index 0000000..1be9098 --- /dev/null +++ b/docs/web/decisions.md @@ -0,0 +1,19 @@ +# 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. diff --git a/docs/web-roadmap.md b/docs/web/roadmap.md similarity index 100% rename from docs/web-roadmap.md rename to docs/web/roadmap.md diff --git a/web/README.md b/web/README.md index 7d065ce..1514b1e 100644 --- a/web/README.md +++ b/web/README.md @@ -15,4 +15,4 @@ npm run dev npm run check ``` -The production build is emitted to `dist/` as static assets. See `docs/web-roadmap.md` at the repository root for architecture boundaries and planned dependencies. +The production build is emitted to `dist/` as static assets. See `docs/web/roadmap.md` at the repository root for architecture boundaries and planned dependencies.