Project
Contributing
TradeClaw is open source and welcomes contributions. Whether you are adding an indicator, improving the UI, or fixing a bug — this page covers everything you need to get from zero to a merged pull request.
Monorepo Architecture
TradeClaw uses a standard npm workspaces monorepo. The main application lives in apps/web. Shared packages (types, utilities) live under packages/.
tradeclaw/
├── apps/
│ └── web/ # Next.js application (main app)
│ ├── app/ # App Router pages and API routes
│ │ ├── api/ # REST API handlers
│ │ ├── dashboard/ # Dashboard UI
│ │ ├── docs/ # This documentation site
│ │ └── lib/ # TA engine, stores, utilities
│ ├── components/ # Reusable React components
│ └── public/ # Static assets
├── packages/
│ └── types/ # Shared TypeScript types
├── docker-compose.yml # Production compose file
├── docker-compose.dev.yml # Dev compose with hot reload
└── STATE.yaml # Project state trackerDev Setup
Fork and clone
git clone https://github.com/your-fork/tradeclaw && cd tradeclawInstall dependencies
npm installCopy env template
cp apps/web/.env.example apps/web/.env.localStart dev server
npm run dev --workspace=apps/webThe dev server starts at http://localhost:3000 with hot reload. No database setup is required — TradeClaw uses JSON file storage by default.
Tech Stack
Next.js 14
FrameworkApp Router, Server Components, Route Handlers
TypeScript
LanguageStrict mode, no implicit any
Tailwind CSS v4
StylingUtility classes, no CSS modules
File-based storage
DataJSON files in /data — no database required
Server-Sent Events
Real-timeLive price stream via /api/prices/stream
Node.js crypto
SecurityHMAC-SHA256 for webhook signing
Key Directories
| Path | Purpose |
|---|---|
| apps/web/app/api/ | All REST API route handlers (Next.js Route Handlers) |
| apps/web/app/lib/ta-engine.ts | Technical analysis — RSI, MACD, EMA, BB, Stochastic |
| apps/web/app/lib/signal-store.ts | File-based signal persistence and query layer |
| apps/web/app/lib/hooks/ | React hooks (use-price-stream, use-signals, etc.) |
| apps/web/components/ | Shared React components (charts, cards, modals) |
| apps/web/app/docs/ | This documentation site — App Router pages |
| apps/web/public/sw.js | Service Worker for PWA offline support |
Code Style
TypeScript strict mode
All files must pass tsc --noEmit. No implicit any, no unused vars.
Server Components by default
Only add "use client" when you need browser APIs or React state.
No external state libraries
Use React state, context, and URL params. No Redux or Zustand.
Tailwind over inline styles
Use utility classes. Avoid style={{}} except for truly dynamic values.
File-based storage API
All data access goes through the store modules in app/lib/. No direct fs calls in routes.
Adding a New Indicator
// Export the result type
export interface MyIndicatorResult {
value: number;
signal: 'BUY' | 'SELL' | 'NEUTRAL';
}
// Export the calculation function
export function calcMyIndicator(closes: number[], period = 14): MyIndicatorResult {
// … your implementation
return { value, signal };
}
// 2. Import and call it in generateSignal()
// 3. Include its vote in the confluence score calculationPull Request Process
Open an issue first
Describe what you want to build or fix. We will confirm the approach before you invest time writing code.
Branch from main
Use the pattern feat/description or fix/description. Keep branches focused — one feature or fix per PR.
Run the build
npm run build must pass clean with zero TypeScript errors before opening a PR.
Write a clear description
Summarize what changed and why. Include screenshots for UI changes. Link to the related issue.
Update docs if needed
New endpoints go in /docs/api. New indicators go in /docs/signals. New env vars go in /docs/configuration.