AITrader/.github/copilot-instructions.md

Copilot Instructions for AITrader

Quick Start

This is a stock trading application built with React Router 7, TypeScript, and TailwindCSS, integrating with the Alpaca trading API.

Essential Commands

• npm install – Install dependencies (first time only)
• npm run dev – Start development server at http://localhost:5173
• npm run build – Create production build in ./build
• npm start – Serve production build (requires npm run build first)
• npm run typecheck – Validate TypeScript (react-router typegen + tsc) — must run before committing
• npm run test:e2e – Run Playwright end-to-end tests

Architecture Overview

Project Structure

app/
├── root.tsx                 # Root layout and error boundary
├── routes.ts               # Route configuration (React Router 7 RouteConfig API)
├── routes/
│   ├── landing.tsx        # Landing page
│   ├── home.tsx           # Main application page
│   ├── stocks.tsx         # Stock dashboard
│   └── api/               # Server-side API routes
│       ├── indicators.ts  # Stock indicator calculations
│       └── alpaca/        # Alpaca broker integration
│           └── account.ts # Account data endpoints
├── components/            # Reusable React components
│   ├── StockViewer.tsx   # Stock symbol search and indicator display
│   └── AlpacaAccountInfo.tsx # Account balance and portfolio info
├── utils/
│   ├── indicators.ts     # Technical indicator logic (SMA, EMA, RSI, MACD)
│   └── __tests__/        # Unit tests via Vitest
├── types.ts              # TypeScript interfaces (IndicatorData, AlpacaAccount)
└── app.css               # Global styles

Full-Stack Data Flow

1. Client (React Components) – User interacts with StockViewer or AlpacaAccountInfo
2. Server Routes (/routes/api/) – Handle business logic (fetch data from external APIs, run calculations)
3. Utils – Pure functions for indicators and shared logic (testable with Vitest)
4. External APIs – Alpaca API for account/trading data

Server-Side Rendering (SSR)

• Enabled by default (ssr: true in react-router.config.ts)
• Routes can export loaders for initial data fetching
• Use loader functions in route definitions for data pre-loading

Key Conventions

TypeScript & Type Safety

• Path alias – Use ~/ for app imports (e.g., import { IndicatorData } from "~/types")
• Generated types – React Router generates types in .react-router/types/ after running typecheck
• Route types – Import type { Route } from ./+types/[routename] for loader/action types
• Never skip react-router typegen – Directly running tsc will fail; always run npm run typecheck
• ES Module syntax – Project uses "type": "module"; include file extensions in imports where needed

Component Patterns

• Client-side interactivity – Use React hooks (useState, useEffect) in components
• API calls – Fetch from /api/* endpoints; proxy configured in vite.config.ts routes to local dev server
• Error handling – Wrap API calls in try/catch; set error state for UI display
• Loading states – Track loading boolean to show spinners/disable buttons during async work

API Route Patterns

• Handlers in app/routes/api/**/*.ts are server-only functions
• Export a default export default function(...) that receives request context
• Return JSON responses or error responses
• Use utilities in ~/utils/ for shared logic (e.g., indicator calculations)

Testing

• Unit tests – Use Vitest (npm run test:e2e actually runs Playwright, but unit tests exist via vitest)
  • Located alongside source files in __tests__/ directories
  • Test format: *.test.ts or *.test.tsx
• E2E tests – Playwright configured in playwright.config.ts
  • Tests in ./tests/ directory
  • Dev server starts automatically during test runs
  • HTML report generated in test-results/

Styling

• TailwindCSS – Configured via Vite plugin (@tailwindcss/vite); no separate build step needed
• Global styles – Edit app/app.css
• Component styles – Use Tailwind utility classes directly in JSX

Import Paths

• Absolute imports – Use ~/ alias for app folder (e.g., ~/components/StockViewer)
• Relative imports – Use ./ or ../ sparingly within same directory tree

Common Pitfalls

• npm start fails if build doesn't exist – Always run npm run build first
• TypeScript compilation errors after route changes – Missing npm run typecheck step; regenerated types in .react-router/types/ are required
• Vite proxy not working in dev – Ensure dev server is running and API endpoints match vite.config.ts proxy config (default: /api → http://127.0.0.1:3000)
• No test framework exists for unit tests – Repository includes Vitest/Playwright dependencies but no test runner script; configure as needed
• Port conflicts – Dev server uses 5173, Docker/production uses 3000

Deployment

Docker

docker build -t aitrader .
docker run -p 3000:3000 aitrader

Ensure npm run build is run in the Dockerfile before the final CMD.

Environment Variables

• Check Dockerfile for any required environment setup
• Alpaca API credentials likely needed for trading features (not present in repo; set at runtime)

Debugging Tips

• Type errors – Run npm run typecheck to regenerate React Router types and validate all TS
• Module resolution – Check tsconfig.json for path aliases and ensure imports match configured paths
• Component not rendering – Check route configuration in routes.ts and ensure component is exported as default
• API calls failing – Verify Vite proxy config and that the target server is running