# 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
```bash
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