# Developer Onboarding Guide **Purpose:** Comprehensive onboarding guide for new developers joining the trading dashboard monorepo project. **Target Audience:** New developers, contractors, contributors. --- ## Table of Contents - [Project Overview](#project-overview) - [Prerequisites](#prerequisites) - [Development Setup](#development-setup) - [Project Structure](#project-structure) - [Development Workflow](#development-workflow) - [Testing](#testing) - [Code Review Process](#code-review-process) - [Common Tasks](#common-tasks) - [Resources](#resources) - [Getting Help](#getting-help) --- ## Project Overview ### What is the Trading Dashboard? The trading dashboard is a monorepo containing three product surfaces: - **Backend** - Trading engine, REST API, WebSocket server (port 4018) - **Web** - React 19 + Vite dashboard (port 3050) - **Mobile** - Expo + React Native app ### Tech Stack **Backend:** - Node.js with TypeScript (ESM) - Express.js REST API - Socket.IO WebSocket - Azure Cosmos DB (primary data store) - Alpaca + CCXT for exchange integration - Platform-service for auth and feature flags **Web:** - React 19 + Vite - React Router v7 - Recharts for charts - Socket.IO client - @bytelyst/ui for UI components - TailwindCSS v4 **Mobile:** - Expo + React Native - Expo Router - React Native Web - Socket.IO client - @bytelyst/react-native-platform-sdk ### Key Concepts - **Monorepo** - Single repo with backend, web, mobile workspaces - **Common Platform** - Shared packages from `learning_ai_common_plat` - **Platform Auth** - JWT-based authentication via platform-service - **Kill Switch** - Product-wide maintenance mode - **Feature Flags** - Product-level feature flags - **Tenant Isolation** - Data scoped by tenant/user - **Trading Control** - Global and profile-level trading pause/resume --- ## Prerequisites ### Required Software **For All Development:** - Node.js 18+ (LTS recommended) - pnpm 10.6.5+ - Git - Docker (optional, for containerized development) **For Backend Development:** - TypeScript 5.9+ - Azure Cosmos DB emulator (local) or Azure Cosmos DB (production) **For Web Development:** - Modern web browser (Chrome, Firefox, Safari, Edge) - Node.js 18+ **For Mobile Development:** - Node.js 18+ - Expo CLI - iOS: Xcode (for iOS builds) - Android: Android Studio (for Android builds) ### Required Accounts - GitHub account (for code access) - Azure account (for production Cosmos DB) - Platform-service access (for auth and feature flags) ### Optional Tools - VS Code (recommended IDE) - Postman (for API testing) - Expo Go app (for mobile testing) - Docker Desktop (for containerized development) --- ## Development Setup ### 1. Clone the Repository ```bash git clone https://github.com/saravanakumardb1/learning_ai_invt_trdg.git cd learning_ai_invt_trdg ``` ### 2. Install Dependencies **Using local common platform packages (default):** ```bash BYTELYST_PACKAGE_SOURCE=common-plat pnpm install ``` **Using Gitea registry (requires auth):** ```bash BYTELYST_PACKAGE_SOURCE=gitea pnpm install ``` ### 3. Configure Environment Variables **Backend (.env):** ```bash cd backend cp .env.example .env # Edit .env with your values ``` **Required backend environment variables:** - `COSMOS_ENDPOINT` - Cosmos DB endpoint - `COSMOS_KEY` - Cosmos DB key - `COSMOS_DATABASE` - Cosmos DB database name - `PLATFORM_API_URL` - Platform-service URL - `PLATFORM_AUTH_ENABLED` - Enable platform auth (true/false) - `PLATFORM_JWT_PUBLIC_KEY` - JWT public key (if platform auth enabled) - `JWT_SECRET` - Legacy JWT secret (dev only) - `ALPACA_API_KEY` - Alpaca API key - `ALPACA_API_SECRET` - Alpaca API secret - `FMP_API_KEY` - Financial Modeling Prep key - `OPENAI_API_KEY` - OpenAI API key - `ENABLE_TRADING` - Enable live trading (true/false) - `PAPER_TRADING` - Paper trading mode (true/false) **Web (.env.local):** ```bash cd web cp .env.local.example .env.local # Edit .env.local with your values ``` **Required web environment variables:** - `VITE_TRADING_API_URL` - Backend API URL - `VITE_PLATFORM_URL` - Platform-service URL - `VITE_PRODUCT_ID` - Product ID (invttrdg) - `VITE_BACKTEST_ENABLED` - Backtest enabled (true/false) **Mobile (.env.local):** ```bash cd mobile cp .env.local.example .env.local # Edit .env.local with your values ``` **Required mobile environment variables:** - `EXPO_PUBLIC_PRODUCT_ID` - Product ID (invttrdg) - `EXPO_PUBLIC_PLATFORM_URL` - Platform-service URL - `EXPO_PUBLIC_TRADING_API_URL` - Backend API URL ### 4. Verify Setup ```bash # From monorepo root pnpm verify ``` This runs: - Type checking for all workspaces - Tests for all workspaces - Linting for all workspaces --- ## Project Structure ### Monorepo Layout ``` learning_ai_invt_trdg/ ├── backend/ # Backend service │ ├── src/ │ │ ├── strategies/ # Trading strategy engine │ │ ├── services/ # Business logic services │ │ ├── connectors/ # Exchange connectors │ │ ├── config/ # Configuration │ │ ├── scripts/ # Maintenance scripts │ │ └── bootstrap.ts # Server entry point │ ├── Dockerfile │ └── package.json │ ├── web/ # Web dashboard │ ├── src/ │ │ ├── views/ # Page components │ │ ├── components/ # Reusable components │ │ ├── hooks/ # Custom React hooks │ │ ├── lib/ # API clients, utilities │ │ ├── context/ # React contexts │ │ └── main.tsx # Entry point │ ├── e2e/ # Playwright E2E tests │ ├── stories/ # Storybook stories │ ├── Dockerfile │ └── package.json │ ├── mobile/ # Mobile app │ ├── app/ # Expo Router screens │ │ ├── (tabs)/ # Tab navigation │ │ ├── _layout.tsx # Root layout │ │ ├── marketplace.tsx │ │ └── chat.tsx │ ├── components/ # Mobile components │ ├── lib/ # Mobile utilities │ ├── providers/ # React Native providers │ ├── Dockerfile │ └── package.json │ ├── shared/ # Shared code │ ├── product.json # Canonical product identity │ ├── platform-*.ts # Platform integration │ ├── feature-flags.ts # Feature flag definitions │ ├── realtime.ts # WebSocket contracts │ └── runtime.ts # Runtime configuration │ ├── docs/ # Documentation │ ├── planned/ # Planned work documentation │ ├── inprogress/ # In-progress work documentation │ └── completed/ # Completed work documentation │ ├── scripts/ # Root scripts │ ├── tests/ # Test runners │ ├── verify.sh # Verification script │ └── dev.sh # Development script │ ├── package.json # Root package.json ├── pnpm-workspace.yaml # Workspace configuration ├── docker-compose.yml # Production Docker compose ├── docker-compose.dev.yml # Development Docker compose └── .env.example # Environment variables template ``` ### Key Files **Root:** - `package.json` - Root package.json with workspace scripts - `pnpm-workspace.yaml` - Workspace configuration - `README.md` - Project overview - `docs/PRD.md` - Product requirements - `docs/ROADMAP.md` - Implementation status **Backend:** - `backend/src/bootstrap.ts` - Server entry point - `backend/src/services/apiServer.ts` - REST API server - `backend/src/services/TradeExecutor.ts` - Order execution - `backend/src/strategies/ProStrategyEngine.ts` - Strategy engine **Web:** - `web/src/main.tsx` - Entry point - `web/src/App.tsx` - Root app component - `web/src/views/HomeView.tsx` - Dashboard overview - `web/src/components/ui/Primitives.tsx` - UI adapter **Mobile:** - `mobile/app/_layout.tsx` - Root layout - `mobile/app/(tabs)/index.tsx` - Overview tab - `mobile/lib/runtime.ts` - Runtime configuration --- ## Development Workflow ### Starting Development **Option 1: Using dev script (recommended):** ```bash pnpm dev ``` This starts: - Backend (port 4018) - Web (port 3050) - Mobile dev server **Option 2: Starting individually:** **Backend:** ```bash cd backend npm run dev # Backend starts on port 4018 ``` **Web:** ```bash cd web pnpm dev # Web starts on port 3050 ``` **Mobile:** ```bash cd mobile pnpm dev # Mobile dev server starts # Scan QR code with Expo Go app ``` ### Making Changes 1. **Create a branch:** ```bash git checkout -b feature/your-feature-name # or git checkout -b fix/your-fix-name ``` 2. **Make your changes:** - Edit files in the appropriate workspace - Follow existing code style - Add tests if needed 3. **Test your changes:** ```bash # Type check pnpm typecheck # Run tests pnpm test # Lint pnpm lint ``` 4. **Commit your changes:** ```bash git add . git commit -m "feat(scope): description" # or git commit -m "fix(scope): description" ``` ### Commit Message Format Follow conventional commits: - `feat:` - New feature - `fix:` - Bug fix - `docs:` - Documentation changes - `refactor:` - Code refactoring - `test:` - Test changes - `chore:` - Maintenance tasks Examples: - `feat(backend): add order cancellation endpoint` - `fix(web): resolve WebSocket reconnection issue` - `docs(readme): update setup instructions` ### Pushing Changes ```bash git push origin feature/your-feature-name ``` --- ## Testing ### Backend Tests ```bash cd backend npm test ``` Backend tests include: - Contract tests (API, WebSocket, session rules) - Security tests (tenant isolation, security guards) - Lifecycle tests (trade executor, reconciliation) - Integration tests (market data, chat copilot) ### Web Tests ```bash cd web pnpm test ``` Web tests include: - Unit tests (components, hooks) - DOM tests (component rendering) - E2E tests (Playwright) **Run E2E tests:** ```bash cd web pnpm test:e2e ``` ### Mobile Tests ```bash cd mobile pnpm typecheck # Mobile currently has limited test coverage ``` ### Verification Script ```bash pnpm verify ``` This runs: - Type checking for all workspaces - Tests for all workspaces - Linting for all workspaces --- ## Code Review Process ### Pull Request Process 1. **Create a pull request:** - Go to GitHub - Create PR from your branch to main - Include description of changes - Link to relevant issues 2. **PR Checklist:** - [ ] Tests pass - [ ] Type checking passes - [ ] Linting passes - [ ] Documentation updated if needed - [ ] Commit messages follow conventional commits 3. **Code Review:** - At least one approval required - Address review comments - Make requested changes 4. **Merge:** - Squash and merge - Delete branch after merge ### Code Review Guidelines **What reviewers look for:** - Code correctness - Code style consistency - Test coverage - Documentation - Performance considerations - Security considerations **How to respond to review:** - Address all comments - Explain if you disagree - Make requested changes - Ask for re-review --- ## Common Tasks ### Adding a New Backend Endpoint 1. **Add route handler:** ```typescript // backend/src/services/apiServer.ts app.get('/api/your-endpoint', async (req, res) => { // implementation }); ``` 2. **Add validation:** ```typescript // Use Zod for validation const schema = z.object({ param1: z.string(), param2: z.number(), }); ``` 3. **Add authentication:** ```typescript // Use platform auth middleware // Check user permissions ``` 4. **Add tests:** ```typescript // Add contract test // Add integration test ``` 5. **Update documentation:** ```typescript // Add JSDoc comments // Update API documentation ``` ### Adding a New Web Component 1. **Create component:** ```typescript // web/src/components/YourComponent.tsx export function YourComponent() { return
Your component
; } ``` 2. **Use UI primitives:** ```typescript import { Button } from '../components/ui/Primitives'; ``` 3. **Add tests:** ```typescript // web/src/components/YourComponent.test.tsx // Add unit test // Add DOM test ``` 4. **Add Storybook story:** ```typescript // web/stories/YourComponent.stories.tsx ``` ### Adding a New Mobile Screen 1. **Create screen:** ```typescript // mobile/app/your-screen.tsx export function YourScreen() { return Your screen; } ``` 2. **Add to navigation:** ```typescript // mobile/app/_layout.tsx // Add screen to navigation ``` 3. **Add tests:** ```typescript // Add mobile tests ``` ### Adding a New Feature Flag 1. **Define flag:** ```typescript // shared/feature-flags.ts export const FEATURE_FLAGS = { yourFeature: { enabled: false, description: 'Your feature description', }, }; ``` 2. **Implement flag check:** ```typescript // Use flag in code if (FEATURE_FLAGS.yourFeature.enabled) { // feature code } ``` 3. **Test flag:** ```typescript // Test with flag enabled/disabled ``` --- ## Resources ### Documentation - **README.md** - Project overview - **PRD.md** - Product requirements - **ROADMAP.md** - Implementation status - **ARCHITECTURE_DOCUMENTATION.md** - System architecture - **API_DOCUMENTATION_GUIDE.md** - API documentation - **TROUBLESHOOTING_GUIDE.md** - Troubleshooting guide - **FUNCTIONALITY_REVIEW.md** - Functional gaps and issues - **UX_TESTING_SETUP_GUIDE.md** - UX testing setup ### External Documentation - **@bytelyst packages** - Common platform packages - **Platform-service** - Platform service documentation - **Azure Cosmos DB** - Cosmos DB documentation - **Alpaca API** - Alpaca API documentation - **CCXT** - CCXT documentation - **Expo** - Expo documentation ### Tools - **pnpm** - Package manager - **TypeScript** - TypeScript documentation - **React** - React documentation - **Vite** - Vite documentation - **Expo** - Expo documentation - **Playwright** - Playwright documentation - **Storybook** - Storybook documentation --- ## Getting Help ### Internal Resources - **Team Slack** - #trading-dashboard channel - **On-call engineer** - For production issues - **Tech lead** - For architectural questions ### Common Issues **Setup issues:** - Check TROUBLESHOOTING_GUIDE.md - Verify environment variables - Check dependencies **Development issues:** - Check logs for errors - Verify configuration - Check network connectivity **Code issues:** - Check existing code for patterns - Ask team for guidance - Review documentation ### Asking Questions 1. **Check documentation first** - Look for answers in docs 2. **Search existing issues** - Check GitHub issues 3. **Ask in Slack** - Post in #trading-dashboard channel 4. **Create issue** - If it's a bug or feature request ### Best Practices - **Be specific** - Include error messages, logs, context - **Provide context** - Explain what you're trying to do - **Show research** - Show what you've already tried - **Be patient** - Team members may be busy --- ## Next Steps ### First Week 1. **Complete setup:** - [ ] Clone repository - [ ] Install dependencies - [ ] Configure environment variables - [ ] Verify setup with `pnpm verify` 2. **Explore codebase:** - [ ] Read README.md - [ ] Read PRD.md - [ ] Read ARCHITECTURE_DOCUMENTATION.md - [ ] Explore project structure 3. **Make first contribution:** - [ ] Fix a small bug - [ ] Add a test - [ ] Update documentation ### First Month 1. **Deep dive into your area:** - Backend: Understand trading loop, strategy engine - Web: Understand component structure, data flow - Mobile: Understand app structure, navigation 2. **Contribute to features:** - Pick up a feature from ROADMAP.md - Implement and test - Submit PR 3. **Learn the ecosystem:** - Understand common platform packages - Understand platform-service integration - Understand deployment process ### Ongoing 1. **Stay updated:** - Read team updates - Review PRs - Attend standups 2. **Improve documentation:** - Update docs as you learn - Add examples - Fix errors 3. **Help others:** - Review PRs - Answer questions - Mentor new developers --- ## Summary Welcome to the trading dashboard team! This guide should help you get started with development. If you have questions, don't hesitate to ask in Slack or create an issue. **Key takeaways:** - Use `pnpm verify` to validate your changes - Follow conventional commit format - Use @bytelyst/ui primitives for web components - Check documentation before asking questions - Be specific when asking for help Good luck and happy coding!