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

docs: reorganize documentation into server/ and web/ directories

Browse Source 
- docs: move server docs to docs/server/ and update all cross-references
- docs: move web-roadmap.md to docs/web/roadmap.md and create
  docs/web/decisions.md
- docs: update AGENTS.md with separate Server and Web sections
This commit is contained in:
Sunday
2026-07-14 17:07:42 +08:00
parent b49bf648be
commit 9f13c0a23a
10 changed files with 109 additions and 60 deletions
Download Patch File Download Diff File Expand all files Collapse all files
AGENTS.md
+72 -35
View File
@@ -1,28 +1,36 @@
# AGENTS.md — MyGO Backend # AGENTS.md — MyGO
## Project Essentials ## Project Layout
- Module: `github.com/dhao2001/mygo`, Go 1.26.2 - Server: Go backend in the repository root, with documentation in `docs/server/`
- WebDisk (cloud drive) backend; roadmap in `docs/roadmap.md` - Web: React client in `web/`, with documentation in `docs/web/`
- CLI framework: `github.com/spf13/cobra` - Documentation index: `docs/README.md`
- Go version pinned in `mise.toml`
## Agent Workflow ## Agent Workflow
1. Read the task 1. Read the task and identify the affected project
2. Read relevant `docs/` files for context 2. Read `docs/README.md` and the relevant project documentation for context
3. Explore existing code before writing new code 3. Explore existing code before writing new code
4. Implement following the conventions below 4. Implement following the relevant project conventions below
5. Verify: `go vet ./... && go test ./...` 5. Run the verification commands for every affected project
6. Update `docs/roadmap.md`, `docs/decisions.md`, or `docs/architecture.md` if anything changed 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. - 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. - 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. - 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 - **Format**: `go fmt ./...` before every commit
- **Imports**: stdlib / third-party / internal, blank-line separated - **Imports**: stdlib / third-party / internal, blank-line separated
@@ -32,19 +40,63 @@
- **`init()`**: only in cobra cmd files for flag registration - **`init()`**: only in cobra cmd files for flag registration
- **`cmd/`** is thin; business logic goes in `internal/` - **`cmd/`** is thin; business logic goes in `internal/`
## Documentation ### Documentation
| File | Read Before | Update After | | File | Read Before | Update After |
|------|-------------|--------------| |------|-------------|--------------|
| `docs/architecture.md` | Adding new packages | Adding new packages | | `docs/server/architecture.md` | Adding new packages | Adding new packages |
| `docs/decisions.md` | Making technical decisions | Making technical decisions | | `docs/server/decisions.md` | Making technical decisions | Making technical decisions |
| `docs/roadmap.md` | Every task | Completing a feature | | `docs/server/roadmap.md` | Every server task | Completing a server feature |
| `docs/development.md` | Build/test/debug setup | Changing workflow | | `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 ## Git Version Control
- DON'T create a commit unless the user explicitly asks for one. - 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. - 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. - 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. - 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. - 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 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 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 ## Debugging Principles
README.md
+2 -2
View File
@@ -39,10 +39,10 @@ MyGO is a WebDisk (cloud drive) server, written in Go.
## Frontend ## 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 ## 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.
docs/README.md
+15 -4
View File
@@ -1,8 +1,19 @@
# Docs # Docs
Documentation is organized by project. Use `server/` for the Go backend and `web/` for the browser client.
## Server
| File | Content | | File | Content |
|------|---------| |------|---------|
| `architecture.md` | Module layout, package boundaries | | `server/architecture.md` | Module layout, package boundaries |
| `decisions.md` | Technical decisions (ADR) | | `server/decisions.md` | Technical decisions (ADR) |
| `roadmap.md` | Feature progress and status | | `server/roadmap.md` | Feature progress and status |
| `development.md` | Build, test, debug workflow | | `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 |
docs/architecture.md → docs/server/architecture.md
View File
docs/decisions.md → docs/server/decisions.md
-18
View File
@@ -106,21 +106,3 @@
- REST remains a handler/API concern, and future protocols can reuse services without HTTP leakage. - 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. - 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. - 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.
docs/development.md → docs/server/development.md
View File
docs/roadmap.md → docs/server/roadmap.md
View File
docs/web/decisions.md
+19
View File
@@ -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.
docs/web-roadmap.md → docs/web/roadmap.md
View File
web/README.md
+1 -1
View File
@@ -15,4 +15,4 @@ npm run dev
npm run check 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.