henry
4206b93614
Copilot Setup Steps / copilot-setup-steps (push) Failing after 17s
- Created playwright.config.ts for test configuration - Added .last-run.json to store test run status - Implemented landing.test.ts with tests for navbar visibility and navigation - Removed unused server proxy configuration from vite.config.ts
117 lines
5.8 KiB
Markdown
117 lines
5.8 KiB
Markdown
# 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
|