folder structure init

Author: Jiache Zhang

.github/workflows/ci.yml

@@ -0,0 +1,39 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  backend:
+    name: Backend (Go) checks
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Setup Go
+        uses: actions/setup-go@v4
+        with:
+          go-version: '1.20'
+      - name: Cache Go modules
+        uses: actions/cache@v4
+        with:
+          path: |-
+            ~/.cache/go-build
+            ${{ github.workspace }}/backend/pkg/mod
+          key: ${{ runner.os }}-go-${{ hashFiles('**/go.sum') }}
+      - name: "Backend: lint & build (template)"
+        run: |
+          echo "Run backend linters and build here (per backend/README.md)"
+
+  frontend:
+    name: Frontend (Node) checks
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: '18'
+      - name: "Frontend: install & build (template)"
+        run: |
+          echo "Run frontend install/build/lint here (per frontend/README.md)"

Makefile

@@ -0,0 +1,19 @@
+.PHONY: help init start-backend start-frontend fmt lint
+
+help:
+	@echo "Targets: init, start-backend, start-frontend, fmt, lint"
+
+init:
+	@echo "Run per-subproject init steps. See frontend/README.md and backend/README.md"
+
+start-backend:
+	@echo "Start backend: cd backend && go run ./... (after you init go module and implement server)"
+
+start-frontend:
+	@echo "Start frontend: cd frontend && npm install && npm run dev (after you scaffold the Vue app)"
+
+fmt:
+	@echo "Run formatters in each subproject (go fmt, npm format etc.)"
+
+lint:
+	@echo "Run linters in each subproject (go vet/staticcheck, eslint etc.)"

README.md

@@ -1 +1,30 @@
-# minesweeper
+# minesweeper
+
+This repository is a monorepo skeleton for practicing full-stack development with a Minesweeper game. The project separates frontend and backend but keeps them in one repository and includes example CI and documentation templates.
+
+Initial directory layout:
+
+- `frontend/` — Frontend code and instructions (Vue + Vite). Responsible only for UI and user interaction.
+- `backend/` — Backend code and instructions (Go). Responsible for game logic and state computation, communicating with the frontend over HTTP.
+- `docs/` — Architecture, API design, and CI/CD guidance.
+- `.github/workflows/` — Example CI workflow files.
+
+Quick start (recommended flow):
+
+1. Initialize the backend module:
+
+   - Change to `backend/` and run `go mod init github.com/<your-username>/minesweeper/backend` (or follow `backend/README.md`).
+
+2. Initialize the frontend development project:
+
+   - Change to `frontend/` and create a Vite + Vue project:
+
+     `npm create vite@latest` or `pnpm create vite` and follow `frontend/README.md` for options.
+
+3. Run locally: start the backend from the command line first, then run the frontend development server and open it in your browser.
+
+See the README files inside each subdirectory and `docs/` for more detailed guidance and CI/CD examples.
+
+---
+
+Next step: the repository now contains scaffold files (README, docs, CI template, .gitignore, Makefile, and subproject READMEs). Follow those instructions to initialize each subproject.

backend/README.md

@@ -0,0 +1,22 @@
+# backend (Go) — README
+
+Goal: Implement all game logic and state computation in Go and expose a simple HTTP REST API for the frontend to call.
+
+Recommended local initialization steps:
+
+1. Change into `backend/` and initialize the module:
+
+   go mod init github.com/<your-username>/minesweeper/backend
+
+2. Suggested code organization:
+
+- `cmd/server/` — executable entrypoint (e.g. `main.go`)
+- `internal/` or `pkg/` — game logic, models, and services
+  - `game/` — core algorithms: mine placement, reveal expansion, win/loss detection
+  - `http/` — HTTP handler layer responsible for JSON serialization and routing
+
+3. Run (example):
+
+   go run ./cmd/server
+
+Note: This repository currently contains only documentation and a skeleton. After implementing the backend logic you can run the service from the command line.

docs/ARCHITECTURE.md

@@ -0,0 +1,35 @@
+# Architecture and API (draft)
+
+This project is a local, single-player Minesweeper game. The frontend (Vue) is responsible for UI and user interaction. The backend (Go) is responsible for all game logic and state computation. The frontend and backend communicate via HTTP APIs. This project assumes a trusted local user and does not require authentication or encryption.
+
+High-level contract (illustrative):
+
+- Data shape (GameState) example:
+  - width: int
+  - height: int
+  - mines: int
+  - cells: [[Cell]] — each Cell contains coordinates, isMine, isRevealed, isFlagged, adjacentMines (returned by backend)
+  - status: one of {playing, won, lost}
+
+- Suggested HTTP endpoints (illustrative, not an implementation):
+  - POST /game/new — create a new game; request includes width/height/mines; returns GameState (initially unrevealed)
+  - POST /game/reveal — reveal a cell; parameters: game_id (optional if the backend keeps single in-memory game) / x / y; returns updated GameState
+  - POST /game/flag — flag/unflag a cell; parameters: x / y; returns updated GameState
+  - GET /game — get current GameState (optional)
+
+Error modes and edge cases:
+
+- Invalid coordinates: return 400 Bad Request
+- Operations on a finished game (e.g., revealing after lost/won): return 409 Conflict or return the current state unchanged
+- Very large board sizes (memory/performance): the client should limit max width/height and the server should guard against extreme values that could cause OOM
+
+Success criteria (minimum):
+
+- Frontend can create/reveal/flag cells and correctly render the returned GameState
+- Backend logic correctly implements reveal expansion (when revealing a cell with 0 adjacent mines, automatically reveal neighbors)
+
+Future extensions:
+
+- Persist multiple games (in-memory -> file/DB)
+- User accounts and authentication
+- Packaging and deployment scripts

docs/CI_CD.md

@@ -0,0 +1,13 @@
+# CI / CD Recommendations (example)
+
+Goal: On each push or pull request automatically verify that the backend builds and passes basic static checks, and that the frontend can install dependencies and build (or at least run basic linters).
+
+Recommended steps:
+
+1. Checkout the repository
+2. Setup Go (pin a version, e.g. 1.20+), run `go vet` / `go test` / `go build` (based on the backend implementation)
+3. Setup Node (pin a version, e.g. 18+), in `frontend/` run `npm ci` and `npm run build` or `npm run lint`
+4. Optional: cache dependencies (Go modules, npm cache) to speed up runs
+5. Optional: deploy built frontend to static hosting (e.g., GitHub Pages) or build and release backend binaries
+
+This repository contains an example GitHub Actions workflow at `.github/workflows/ci.yml` as a starting point.

docs/OPERATIONS.md

@@ -0,0 +1,8 @@
+# Operations and Local Development (notes)
+
+This repository is intended for local, single-developer learning and development. Recommended workflow:
+
+- Implement and run the backend in `backend/` first with `go run` and have it listen on a port such as `http://localhost:8080`.
+- Then run the frontend development server from `frontend/` using Vite (default `http://localhost:5173`) and point the frontend API base URL to the backend address.
+
+This repository currently provides documentation and CI templates only. The next step is to initialize the subprojects following the instructions in `backend/README.md` and `frontend/README.md`.

frontend/README.md

@@ -0,0 +1,23 @@
+# frontend (Vue) — README
+
+Goal: Use Vue + Vite to implement only the UI and user interactions for the Minesweeper game. The frontend should call the backend HTTP API to create and update game state.
+
+Recommended local initialization steps (example):
+
+1. In the `frontend/` directory scaffold a Vite project:
+
+   npm create vite@latest .    # choose Vue / JavaScript or TypeScript when prompted
+
+2. Install dependencies and start the development server:
+
+   npm install
+   npm run dev
+
+Suggested project structure:
+
+- `src/` — Vue source files
+  - `components/` — components like Board, Cell, Controls
+  - `services/api.ts` — a small wrapper for HTTP calls to the backend
+  - `App.vue` / `main.ts`
+
+Note: This repository currently contains only documentation and a skeleton. Initialize the real frontend code with Vite as described above.