From a0e050e8901763347802faabea8fe3c28eea1cea Mon Sep 17 00:00:00 2001 From: Flatlogic Bot Date: Fri, 19 Sep 2025 13:31:11 +0000 Subject: [PATCH] Create coding guideline for laravel + react --- agent-tasks.md | 32 ++++++++++++++ agent.md | 116 ++++++++++++++++++++++++++++++++++++++----------- 2 files changed, 123 insertions(+), 25 deletions(-) create mode 100644 agent-tasks.md diff --git a/agent-tasks.md b/agent-tasks.md new file mode 100644 index 0000000..5b2fda7 --- /dev/null +++ b/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. \ No newline at end of file diff --git a/agent.md b/agent.md index f1d4630..dda2bc6 100644 --- a/agent.md +++ b/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. \ No newline at end of file +## 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
Failed to load
; + if (!data) return
Loading...
; + + const handleEdit = (player) => { + setEditingPlayer(player); + openModal(); + }; + + return ( + + ); +} +```