Create coding guideline for laravel + react

agent-tasks.md

@@ -0,0 +1,32 @@
+# Project Tasks
+
+This file tracks the progress of the project.
+
+## Completed
+
+- [x] **Leaderboard UI**: Create a static, visually-styled leaderboard page with a podium for top players and a table for others.
+- [x] **Member Profile Modal**: Display player profiles in a modal dialog instead of a separate page.
+- [x] **Refine Profile Modal**: Update the profile modal to remove the bio and include `joined_date`, `matches_played`, `wins`, and `losses`.
+- [x] **Implement Register/Login**: Build user registration and login functionality. This will be a prerequisite for features that require user authentication.
+- [x] **Backend for Player Data**: Create a backend endpoint to serve the list of players, replacing the mock data in `index.php`.
+- [x] **Refactor Team Handling (Many-to-Many)**
+    - [x] **DB Schema:** Drop `team_a`/`team_b` from `matches` table.
+    - [x] **DB Schema:** Create `teams` table.
+    - [x] **DB Schema:** Create `match_teams` join table.
+    - [x] **Refactor UI:** Update "Create Match" form for multiple teams.
+    - [x] **Refactor Backend:** Update `api/matches.php` to handle multiple teams.
+    - [x] **Refactor UI:** Update match card to display a list of teams.
+- [x] **Story: Training Game Interest and Scheduling**
+    - [x] **Matches Table**: Create a `matches` table in the database to store event details, including date, time, and location.
+    - [x] **`match_votes` Table**: Create a join table between `users` and `matches` to store individual votes.
+    - [x] **Admin Match Management**: Develop a UI for admins to create, update, and delete matches.
+
+## Backlog
+
+- [ ] **Match Interest and Voting**
+    - [ ] **Match Interest Form**: For each match, create a unique interest form for users to vote on their availability.
+    - [ ] **Voting Logic**: Implement the backend functionality to record and manage user votes for each match.
+    - [ ] **Voter Display**: On each match\'s page, display the users who have voted, along with their responses.
+
+- [ ] **Player Dashboard**: Build a personalized dashboard for logged-in players to see their own detailed stats, track progress over time, and manage their information.
+- [ ] **Branded Landing Page**: Develop a more formal, public-facing homepage for the application that explains its purpose and value.

agent.md

@@ -1,30 +1,96 @@
-# Project Tasks
+# Agent Coding Guide: Laravel + React SPA with SWR & Zustand
 
-This file tracks the progress of the project.
+Use this for coding guide and use agent-tasks.md for backlog and tracking progress.
 
-## Completed
+## 1. Project Structure
 
-- [x] **Leaderboard UI**: Create a static, visually-styled leaderboard page with a podium for top players and a table for others.
-- [x] **Member Profile Modal**: Display player profiles in a modal dialog instead of a separate page.
-- [x] **Refine Profile Modal**: Update the profile modal to remove the bio and include `joined_date`, `matches_played`, `wins`, and `losses`.
-- [x] **Implement Register/Login**: Build user registration and login functionality. This will be a prerequisite for features that require user authentication.
-- [x] **Backend for Player Data**: Create a backend endpoint to serve the list of players, replacing the mock data in `index.php`.
-- [x] **Refactor Team Handling (Many-to-Many)**
-    - [x] **DB Schema:** Drop `team_a`/`team_b` from `matches` table.
-    - [x] **DB Schema:** Create `teams` table.
-    - [x] **DB Schema:** Create `match_teams` join table.
-    - [x] **Refactor UI:** Update "Create Match" form for multiple teams.
-    - [x] **Refactor Backend:** Update `api/matches.php` to handle multiple teams.
-    - [x] **Refactor UI:** Update match card to display a list of teams.
-- [x] **Story: Training Game Interest and Scheduling**
-    - [x] **Matches Table**: Create a `matches` table in the database to store event details, including date, time, and location.
-    - [x] **`match_votes` Table**: Create a join table between `users` and `matches` to store individual votes.
-    - [x] **Admin Match Management**: Develop a UI for admins to create, update, and delete matches.
-    - [x] **Match Interest Form**: For each match, create a unique interest form for users to vote on their availability.
-    - [x] **Voting Logic**: Implement the backend functionality to record and manage user votes for each match.
-    - [x] **Voter Display**: On each match's page, display the users who have voted, along with their responses.
+**Backend (Laravel):**
+- Standard folders:
+  - `app/Http/Controllers` (thin, validate, call services)
+  - `app/Services` (business logic)
+  - `routes/api.php` (API endpoints, RESTful JSON)
+  - `app/Models` (Eloquent ORM)
+  - `app/Http/Resources` (format API responses)
+- Use Laravel Sanctum for SPA authentication.
 
-## Backlog
+**Frontend (React):**
+- React app inside `/resources/js/react` for seamless Laravel integration.
+- Functional components with hooks.
+- React Router for client-side routing.
+- **Zustand** for global state management.
+- **SWR** for all server data fetching and caching.
+- Axios as HTTP client used within SWR fetcher function.
 
-- [ ] **Player Dashboard**: Build a personalized dashboard for logged-in players to see their own detailed stats, track progress over time, and manage their information.
-- [ ] **Branded Landing Page**: Develop a more formal, public-facing homepage for the application that explains its purpose and value.
+## 2. Code & Style
+
+**Backend (Laravel/PHP):**
+- PSR-12 standard.
+- Controllers handle request, validation, call service methods, return API Resources.
+- Services contain business logic.
+- Use JSON responses throughout.
+
+**Frontend (React/JS):**
+- Functional components with hooks and JSX.
+- Manage UI state (modals, forms) locally or via Zustand.
+- Use Axios inside SWR for API calls to leverage SWR caching and revalidation.
+- Leverage SWR hooks (`useSWR`) for data fetching with automatic caching, re-fetching, and error handling—avoid manual state for server data.
+- Use Zustand only for client state that doesn’t come from API (e.g., UI toggles, theme, user session info).
+- Use React Router for SPA navigation, avoiding full page reloads.
+
+## 3. Example Usage
+
+### Zustand Store (Client UI State)
+```js
+// store/useStore.js
+import create from 'zustand';
+
+export const useStore = create(set => ({
+  isModalOpen: false,
+  openModal: () => set({ isModalOpen: true }),
+  closeModal: () => set({ isModalOpen: false }),
+  editingPlayer: null,
+  setEditingPlayer: (player) => set({ editingPlayer: player }),
+}));
+```
+
+### SWR Data Fetching with Axios
+```js
+// utils/api.js
+import axios from 'axios';
+
+export const apiClient = axios.create({
+  baseURL: '/api',
+  withCredentials: true,
+});
+
+export const fetcher = url => apiClient.get(url).then(res => res.data);
+
+// components/PlayerList.js
+import useSWR from 'swr';
+import { fetcher } from '../utils/api';
+import { useStore } from '../store/useStore';
+
+function PlayerList() {
+  const { data, error } = useSWR('/players', fetcher);
+  const { openModal, setEditingPlayer } = useStore();
+
+  if (error) return <div>Failed to load</div>;
+  if (!data) return <div>Loading...</div>;
+
+  const handleEdit = (player) => {
+    setEditingPlayer(player);
+    openModal();
+  };
+
+  return (
+    <ul>
+      {data.players.map(player => (
+        <li key={player.id}>
+          {player.name}
+          <button onClick={() => handleEdit(player)}>Edit</button>
+        </li>
+      ))}
+    </ul>
+  );
+}
+```