AITrader/AGENTS.md

AGENTS.md – Repository Quick‑Start Guide

Purpose: Give OpenCode agents the exact commands and conventions they need to work safely and efficiently in the AITrader codebase. Only include items that are easy to miss without explicit guidance.

---

Project structure

• app/routes/ – React Router 7 file-based routes (landing.tsx is the index/home page)
• app/components/ – Shared React components
• app/routes.ts – Route definitions (uses index and route helpers from @react-router/dev/routes)
• app/root.tsx – Root layout with global HTML shell, Links, Meta, Scripts
• app/app.css – Global styles (Tailwind is configured via Vite)
• tests/ – Playwright E2E tests
• vitest.config.ts / vitest.setup.ts – Unit test config (Vitest)
• vite.config.ts – Vite config with Tailwind and React Router plugins
• react-router.config.ts – React Router framework config
• tsconfig.json – TypeScript config (ES modules: "type": "module")

Core npm scripts (run from the repository root)

• npm run dev – Starts the dev server with HMR via react-router dev. Served at http://localhost:5173.
• npm run build – Produces a production build using react-router build. Output lives in ./build with client/ and server/.
• npm start – Serves the production bundle with react-router-serve ./build/server/index.js. Requires a prior npm run build.
• npm run typecheck – Runs react-router typegen then tsc. Must be run before committing TypeScript changes.
• npm run test:e2e – Runs Playwright E2E tests (server starts automatically via playwright.config.ts).

Development workflow

1. Install deps – npm install (first time only).
2. Start dev – npm run dev. Changes are hot-reloaded; no manual restart.
3. Iterate – Edit files under app/ (routes, components, loaders, actions).
4. Validate – Run npm run typecheck regularly; it catches missing typegen steps.
5. E2E tests – npm run test:e2e (Playwright handles server startup).
6. Build & serve – npm run build && npm start.

Routing (React Router 7)

• index() routes render into the parent <Outlet /> at the parent's path.
• route(segment, file) creates an explicit path segment.
• The landing page is index("routes/landing.tsx") — it is the default page at /.
• Do not use multiple index() routes at the same nesting level — only one is allowed per level.
• All route files export meta() for <title> and <meta> tags, and a default export component.

TypeScript nuances

• The typecheck script runs react-router typegen first; agents must not skip this step because generated types are required for successful compilation.
• The project uses ES modules ("type": "module"). Import paths should include file extensions (.js, .ts) where Node requires them.
• Route types are generated — use import type { Route } from "./+types/<route-name>" for type-safe loaders/actions.

TailwindCSS

• Configured via Vite (@tailwindcss/vite). No extra build steps needed; the dev server and production build automatically process Tailwind classes.
• Use arbitrary values and className composition freely.

Playwright E2E testing

• Config: playwright.config.ts in the repo root.
• The web server starts automatically (npm run dev on port 5173) before tests run.
• Tests live in tests/ directory.
• Generate the report with: npm run test:e2e -- --reporter=html (output in test-results/).
• To run tests in headed mode for debugging, set headless: "false" in playwright.config.ts or pass --headed.
• To debug a single test: npx playwright test tests/<file-name>.spec.ts.

Playwright MCP Server

An MCP (Model Context Protocol) server provides Playwright browser automation to AI assistants.

• Start MCP server: npm run mcp:dev (runs via stdio, connects to AI clients)
• Build MCP server: npm run mcp:build (compiles to mcp-server/dist/)

Available tools:

• navigate - Navigate to a URL and get page title
• getPageContent - Get text content from a page
• click - Click an element by CSS selector
• fillForm - Fill a form input

Alpaca API Setup

• Copy .env.example to .env and fill in your Alpaca credentials:
  • ALPACA_API_KEY – Your Alpaca API key
  • ALPACA_SECRET_KEY – Your Alpaca secret key
  • ALPACA_BASE_URL – API endpoint (default: paper trading URL)
• The .env file is gitignored – never commit credentials.
• Account data is fetched from /api/alpaca/account and displayed on the landing page.

Design Guidelines

Layout & Structure:

• All routes use gradient background: <div className="min-h-screen bg-gradient-to-br from-gray-50 to-blue-50">
• Use <Navbar /> component at the top of every page (sticky, with backdrop blur)
• Content container: <div className="mx-auto max-w-7xl px-6 sm:px-8 lg:px-8">

Navbar:

• Use the shared Navbar component from app/components/Navbar.tsx
• Logo: blue-600 rounded square with white "A", text "AITrader" in gray-900 with hover effect
• Links have underline animation on hover

Color Palette:

• Background: bg-gradient-to-br from-gray-50 to-blue-50 for pages, bg-white for cards
• Text: text-gray-900 for headings, text-gray-600 for secondary
• Accent colors for account values: text-green-600 (Cash), text-blue-600 (Buying Power), text-purple-600 (Portfolio Value)
• Error: text-red-600 for error messages

Components:

• Cards: bg-white rounded-xl shadow-lg p-6 border border-gray-200
• Buttons: bg-blue-600 text-white px-6 py-2.5 rounded-lg font-medium hover:bg-blue-700 transition-colors
• Inputs: border border-gray-300 rounded-lg px-4 py-2.5 focus:ring-2 focus:ring-blue-500

Typography:

• Page headings: text-4xl font-bold text-gray-900
• Section headings: text-xl font-bold text-gray-900
• Card titles: text-xl font-bold text-gray-900

Common pitfalls agents might miss

• Running the server without a build – npm start will fail if npm run build hasn't been executed first.
• Skipping typegen – Directly running tsc without the preceding react-router typegen results in missing type definitions.
• Multiple index routes at same level – React Router 7 only allows one index() per nesting level. Use route() for additional paths.
• Port assumptions – Dev server runs on 5173; production server (Docker) defaults to 3000 unless overridden.
• Route file naming – Route files must match the pattern app/routes/<name>.tsx and the corresponding type file at app/routes/+types/<name>.ts if types are needed.
• Import paths – Use react-router for framework imports (Link, Outlet), not @remix-run/react.

---

Keep this file up‑to‑date as scripts or tooling evolve.