diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md new file mode 100644 index 0000000..0da54db --- /dev/null +++ b/.github/copilot-instructions.md @@ -0,0 +1,292 @@ +# AlgoNodeRewards - GitHub Copilot Instructions + +## General Guidelines + +### Code Organization + +- Never create README or documentation files unless specifically asked +- Split large files into smaller, focused modules +- Break down complex files into separate files with specific functions to improve readability and maintainability +- Keep functions small and single-purpose +- Extract reusable logic into separate utilities or hooks + +### Development Practices + +- Implement changes directly rather than just suggesting them +- Write tests for new functionality +- Ensure TypeScript types are properly defined +- Follow existing code patterns and conventions in the codebase +- **Always run `npm run ci` after big changes** to check for errors, lint files, type-check, build, and run tests + +### Loading States + +- **Use Skeleton components for loading states** - NOT Spinner components +- Skeleton component is located at `src/components/ui/skeleton.tsx` +- Create custom fallback components that match the structure of the content being loaded +- Examples in `src/components/address/address-view.tsx`: + - `StatsFallback` - Mimics stats panel layout with skeleton placeholders + - `HeatmapFallback` - Shows skeleton grid matching heatmap structure + - `ChartFallback` - Displays skeleton for chart containers +- Use `` with specific height/width classes +- Wrap skeletons in the same container structure as actual content for seamless transitions + +### Communication + +- Keep responses concise and to the point +- Focus on implementation over explanation +- Only provide detailed explanations when explicitly requested + +--- + +## Project Overview + +AlgoNodeRewards is a React-based web application for tracking and visualizing rewards from running an Algorand node. It provides comprehensive statistics, charts, and analytics for node operators using the Nodely API. + +**Website**: [algonoderewards.com](https://algonoderewards.com) +**Repository**: github.com/cryptomalgo/algonoderewards +**License**: MIT + +## Tech Stack + +### Core Framework & Build Tools + +- **React 19.2.0** - UI framework +- **TypeScript 5.9.3** - Type-safe JavaScript +- **Vite 7.1.10** - Build tool and dev server +- **Vitest 3.2.4** - Unit testing framework + +### Routing & State Management + +- **TanStack Router 1.133.3** - File-based routing with type safety + - Routes are in `src/routes/` folder + - Auto-generated route tree in `src/routeTree.gen.ts` + - Uses `createFileRoute` for route components +- **TanStack Query 5.90.5** - Server state management and data fetching + - Queries are organized in `src/hooks/` and `src/queries/` + +### UI & Styling + +- **Tailwind CSS 4.1.14** - Utility-first CSS framework + - Configuration in `@tailwindcss/vite` plugin + - Custom CSS in `src/App.css` with CSS variables for theming + - Dark/light/system theme support via `next-themes` +- **shadcn/ui** - Component library (New York style) + - Components in `src/components/ui/` + - Configuration in `components.json` + - Uses Radix UI primitives + - Lucide React for icons + - `class-variance-authority` for component variants + - `tailwind-merge` and `clsx` for className composition + +### Radix UI Components + +- Dialog, Dropdown Menu, Checkbox, Label, Popover, Select, Slider, Toggle, Toggle Group, Tooltip + +### Data Visualization + +- **Recharts 3.3.0** - Charts and graphs +- **@uiw/react-heat-map 2.3.3** - Heatmap visualization +- **react-gauge-component 1.2.64** - Gauge displays + +### Algorand Integration + +- **algosdk 3.5.2** - Algorand JavaScript SDK +- **@algorandfoundation/algokit-utils 9.1.2** - Algorand utilities +- Uses Nodely API (mainnet-idx.4160.nodely.dev) for indexer access + +### Additional Libraries + +- **motion 12.23.24** - Animation library (Framer Motion successor) +- **date-fns 4.1.0** - Date manipulation +- **sonner 2.0.7** - Toast notifications +- **react-error-boundary 6.0.0** - Error handling +- **react-day-picker 9.11** - Calendar/date picker + +## Project Structure + +``` +src/ +├── routes/ # TanStack Router file-based routes +│ ├── __root.tsx # Root layout with header, footer, devtools +│ ├── index.tsx # Landing page with search +│ ├── $addresses.tsx # Address rewards view (dynamic route) +│ └── privacy-policy.tsx +│ +├── components/ # React components +│ ├── ui/ # shadcn/ui components (Button, Dialog, etc.) +│ ├── address/ # Address-specific components +│ │ ├── charts/ # Reward/block charts and visualizations +│ │ └── stats/ # Statistics panels and boxes +│ ├── heatmap/ # Heatmap components +│ └── [other components] +│ +├── hooks/ # Custom React hooks & queries +│ ├── useRewardTransactions.ts # Fetch block/reward data +│ ├── useAlgoPrice.ts # Binance price feed +│ ├── useStakeInfo.ts # Algorand staking info +│ └── [other hooks] +│ +├── queries/ # TanStack Query functions +│ ├── getAccountsBlockHeaders.ts +│ └── getResolvedNFD.ts +│ +├── lib/ # Utility functions +│ ├── indexer-client.ts # Algorand indexer client +│ ├── utils.ts # General utilities (cn, etc.) +│ ├── date-utils.ts # Date formatting/manipulation +│ └── csv-export.ts # CSV export functionality +│ +├── constants.ts # App constants +├── main.tsx # App entry point +└── App.css # Global styles & Tailwind config +``` + +## Key Features + +### Rewards & Statistics + +- Estimated APY (Annual Percentage Yield) +- Total rewards, blocks, and USD value +- No block probability gauge +- Min/max/average reward calculations +- Daily/weekly/monthly aggregations +- Percentage change indicators + +### Visualizations + +- Monthly heatmap of rewards/blocks +- Rewards history chart (line chart) +- Blocks history chart (line chart) +- Block distribution by day and hour (bar chart) +- Block reward intervals chart + +### User Experience + +- Multi-address support (comma or space-separated) +- NFD (Name/Filename Domain) resolution +- Dark/light/system theme modes +- Responsive design (desktop & mobile) +- Real-time ALGO/USD exchange rate +- CSV export with customizable columns +- Address breadcrumb navigation +- Search and filter capabilities + +## Coding Guidelines + +### Component Patterns + +- Use functional components with TypeScript +- Prefer named exports for regular components +- Use `createFileRoute` for route components +- Implement error boundaries for robustness +- Use `@/` alias for imports (configured in Vite) + +### Styling Conventions + +- Use Tailwind utility classes +- Follow shadcn/ui patterns for components +- Use `cn()` utility from `lib/utils` for conditional classes +- Leverage CSS variables for theming +- Support both light and dark modes + +### State Management + +- Use TanStack Query for server state +- Custom hooks for complex data fetching logic +- React context for theme management +- URL search params for shareable state (TanStack Router) + +### Data Fetching + +- Centralize queries in `hooks/` or `queries/` +- Use Algorand indexer client from `lib/indexer-client.ts` +- Handle loading, error, and success states +- Implement proper error boundaries + +### Testing + +- Use Vitest for unit tests +- Testing Library for React components +- Test files with `.test.ts` or `.test.tsx` extension +- Run tests with `npm test` or `npm run test:watch` + +### Code Quality + +- ESLint for linting (`npm run lint`) +- Prettier for formatting (`npm run prettier:fix`) +- TypeScript strict mode (`npm run type:check`) +- CI script runs all checks: `npm run ci` + +## Deployment + +- Automatic deployment to Cloudflare Pages on push to `main` branch +- Production URL: [algonoderewards.com](https://algonoderewards.com) + +## Development Commands + +```bash +npm install # Install dependencies +npm run dev # Start dev server +npm run build # Production build +npm run lint # Run ESLint +npm run type:check # TypeScript type checking +npm test # Run tests once +npm run test:watch # Run tests in watch mode +npm run ci # Full CI check (lint, format, type, build, test) +``` + +## Important Notes + +### API Usage + +- Uses Nodely API for Algorand indexer access (free tier) +- Binance API for real-time ALGO/USD price +- No authentication required + +### Address Handling + +- Supports multiple addresses (comma or space-separated) +- NFD resolution for friendly names +- Validates Algorand address format +- Type: `ResolvedAddress` in `components/heatmap/types.ts` + +### Chart Data + +- Block rewards are in microAlgos (divide by 1,000,000 for ALGO) +- Timestamps are in Unix seconds +- Date groupings use `date-fns` with proper timezone handling + +### Performance + +- React Scan integration for performance monitoring (disabled in prod) +- Lazy loading for dev tools (TanStack Router/Query devtools) +- Auto code-splitting via TanStack Router plugin + +## Common Tasks + +### Adding a New Route + +1. Create file in `src/routes/` (e.g., `about.tsx`) +2. Use `createFileRoute` pattern +3. Route tree auto-generates via TanStack Router plugin + +### Adding a New UI Component + +1. Use `shadcn/ui` CLI if it's a base component +2. Place in `src/components/ui/` for base components +3. Place in appropriate feature folder for feature components +4. Use `cn()` for className composition + +### Adding a New Data Query + +1. Create hook in `src/hooks/` or query function in `src/queries/` +2. Use TanStack Query (`useQuery` or `useSuspenseQuery`) +3. Handle loading/error states appropriately +4. Type return data properly + +### Styling Guidelines + +- Mobile-first responsive design +- Use Tailwind breakpoints: `sm:`, `md:`, `lg:`, `xl:` +- Support dark mode with `dark:` variant +- Follow shadcn/ui component patterns