Skip to content

Commit 5332de5

Browse files
jiaxinnnsjiaxinnns
authored
Add AGENTS.md file (#20)
1 parent 48d9d05 commit 5332de5

File tree

1 file changed

+152
-0
lines changed

1 file changed

+152
-0
lines changed

‎AGENTS.md‎

Lines changed: 152 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,152 @@
1+
## Project Overview
2+
3+
A React-based dashboard application that displays user progress for Git Mastery exercises. The app fetches exercise data and user progress from GitHub repositories and renders it in an interactive dashboard.
4+
5+
**Key Features:**
6+
- View user progress for Git Mastery exercises
7+
- Fetch data from GitHub raw content (exercises and user progress)
8+
- Display exercise status with visual indicators
9+
- Real-time data refresh capability
10+
11+
## Tech Stack
12+
13+
### Core Technologies
14+
- **React 19.0.0** - UI library
15+
- **TypeScript 5.7.2** - Type safety
16+
- **Vite 6.2.0** - Build tool and dev server
17+
- **React Router 7.2.0** - Client-side routing (HashRouter)
18+
19+
### State Management & Data Fetching
20+
- **React Query 3.39.3** - Server state management and caching
21+
- All API calls are wrapped in React Query hooks
22+
- Query keys follow pattern: `["query-name", ...dependencies]`
23+
- Queries are invalidated for manual data refresh
24+
25+
### Styling
26+
- **Tailwind CSS 4.0.9** - Utility-first CSS framework
27+
- **@tailwindcss/vite** - Vite integration for Tailwind
28+
- Inline utility classes for all styling (no separate CSS modules)
29+
30+
### Utilities
31+
- **axios 1.8.1** - HTTP client for API calls
32+
- **react-icons 5.5.0** - Icon library (IoArrowBack, MdOutlineRefresh, etc.)
33+
34+
## Project Structure
35+
```
36+
src/
37+
├── api/
38+
│ └── queries/ # React Query hooks and API functions
39+
├── components/
40+
├── constants/ # App-wide constants
41+
├── pages/ # Route-level page components
42+
├── styles/ # Global styles (index.css)
43+
└── types/ # TypeScript type definitions
44+
```
45+
46+
## Common Tasks
47+
48+
### Adding a New Component
49+
1. Create in appropriate folder in `components`, or a new folder in `components` if it does not fit the current folders
50+
2. Use PascalCase for filename
51+
3. Define props interface
52+
4. Export `ui/` components as named export, and other components via an index.ts file within the subfolder
53+
5. Style with Tailwind utilities
54+
Example code:
55+
[src/components/dashboard/DashboardHeader.tsx](src/components/dashboard/DashboardHeader.tsx) - Shows component composition, Tailwind styling, and proper typing
56+
[src/components/dashboard/index.ts](src/components/dashboard/index.ts) - Pattern for clean component exports
57+
58+
### Adding a New Page
59+
1. Create in `pages/` matching URL structure
60+
2. Use folder for route params: `(paramName)`
61+
3. Add route to `main.tsx` Routes
62+
4. Fetch data (if needed) with React Query hooks at page level
63+
64+
### Adding a New Query
65+
1. Create file in `src/api/queries/` with snake_case name
66+
2. Define response interface
67+
3. Create async fetch function with axios
68+
4. Export React Query hook with proper typing
69+
5. Use `enabled` option if query depends on other data
70+
Example code:
71+
[src/api/queries/get_user_progress.ts](src/api/queries/get_user_progress.ts) - Shows proper error handling, typing, and hook structure
72+
[src/api/queries/get_exercises.ts](src/api/queries/get_exercises.ts) - Shows data transformation and sorting logic
73+
74+
## API Documentation
75+
76+
### Data Sources
77+
- **Exercises directory**: `https://git-mastery.org/exercises-directory/exercises.json`
78+
- Returns: `Record<string, ExerciseRaw>` with lesson/detour info
79+
- **User progress**: `https://raw.githubusercontent.com/{username}/{username}-gitmastery-progress/refs/heads/main/progress.json`
80+
- Returns: `UserProgress[]` with exercise_name and status
81+
- **GitHub user API**: Standard GitHub REST API for user information
82+
83+
### API Client
84+
- Use `axios` for all HTTP requests (already configured)
85+
- Always return `null` on error (never throw)
86+
- Wrap in React Query hooks with proper `enabled` conditions
87+
88+
### Error Handling
89+
- API functions return `null` on error (no throws)
90+
- Components handle `null` data gracefully
91+
- Use optional chaining and nullish coalescing
92+
- Loading states managed via React Query's `isLoading` and `isFetching`
93+
94+
### Data Refresh
95+
- Manual refresh via `queryClient.invalidateQueries()`
96+
- Refresh button calls invalidate for specific query keys
97+
98+
## Coding Conventions
99+
100+
### File Naming
101+
- **Components**: PascalCase (`DashboardHeader.tsx`)
102+
- **Utilities/Queries**: snake_case (`get_user_progress.ts`)
103+
- **Types**: snake_case (`exercise.ts`)
104+
- **Constants**: snake_case (`dashboard.ts`)
105+
106+
### Import Aliases
107+
- `@/` maps to `src/` directory
108+
- Always use path alias for src imports: `import { foo } from "@/api/queries/get_foo"`
109+
- Configured in `vite.config.ts`
110+
111+
### Styling Conventions
112+
113+
**Tailwind Usage:**
114+
- All styles via Tailwind utility classes (no custom CSS except global styles)
115+
- Common patterns:
116+
- Flex layouts: `flex flex-row gap-2 items-center`
117+
- Colors: `text-gray-500`, `bg-blue-600`
118+
- Spacing: `mb-8`, `p-4`, `gap-2`
119+
- Text: `text-sm`, `text-xl font-bold`
120+
- Extract repeated className strings to constants for consistency
121+
122+
**Responsive Design:**
123+
- Mobile-first approach
124+
- Use responsive prefixes as needed: `md:`, `lg:`
125+
126+
### Constants
127+
128+
- Centralize all magic strings/numbers in `constants/`
129+
- Use `as const` for const objects to get literal types
130+
- Export from barrel file for clean imports
131+
132+
### Routing
133+
134+
- Uses HashRouter for GitHub Pages compatibility
135+
- Base path configured: `"/progress-dashboard/"`
136+
- Route parameters accessed via `useParams()` hook
137+
- Navigation via `Link` component from `react-router`
138+
139+
## Build & Development
140+
141+
### Commands
142+
143+
```bash
144+
# Full build
145+
npm run build
146+
147+
# Project-wide lint
148+
npm run lint
149+
150+
# Start dev server
151+
npm run dev
152+
```

0 commit comments

Comments
 (0)