learning_ai_invt_trdg/docs/planned/ONBOARDING_GUIDE.md

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
• Prerequisites
• Development Setup
• Project Structure
• Development Workflow
• Testing
• Code Review Process
• Common Tasks
• Resources
• 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

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):

BYTELYST_PACKAGE_SOURCE=common-plat pnpm install

Using Gitea registry (requires auth):

BYTELYST_PACKAGE_SOURCE=gitea pnpm install

3. Configure Environment Variables

Backend (.env):

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):

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):

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

# 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):

pnpm dev

This starts:

• Backend (port 4018)
• Web (port 3050)
• Mobile dev server

Option 2: Starting individually:

Backend:

cd backend
npm run dev
# Backend starts on port 4018

Web:

cd web
pnpm dev
# Web starts on port 3050

Mobile:

cd mobile
pnpm dev
# Mobile dev server starts
# Scan QR code with Expo Go app

Making Changes

1. Create a branch:

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:

# Type check
pnpm typecheck

# Run tests
pnpm test

# Lint
pnpm lint

4. Commit your changes:

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

git push origin feature/your-feature-name

---

Testing

Backend Tests

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

cd web
pnpm test

Web tests include:

• Unit tests (components, hooks)
• DOM tests (component rendering)
• E2E tests (Playwright)

Run E2E tests:

cd web
pnpm test:e2e

Mobile Tests

cd mobile
pnpm typecheck
# Mobile currently has limited test coverage

Verification Script

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:

// backend/src/services/apiServer.ts
app.get('/api/your-endpoint', async (req, res) => {
  // implementation
});

2. Add validation:

// Use Zod for validation
const schema = z.object({
  param1: z.string(),
  param2: z.number(),
});

3. Add authentication:

// Use platform auth middleware
// Check user permissions

4. Add tests:

// Add contract test
// Add integration test

5. Update documentation:

// Add JSDoc comments
// Update API documentation

Adding a New Web Component

1. Create component:

// web/src/components/YourComponent.tsx
export function YourComponent() {
  return <div>Your component</div>;
}

2. Use UI primitives:

import { Button } from '../components/ui/Primitives';

3. Add tests:

// web/src/components/YourComponent.test.tsx
// Add unit test
// Add DOM test

4. Add Storybook story:

// web/stories/YourComponent.stories.tsx

Adding a New Mobile Screen

1. Create screen:

// mobile/app/your-screen.tsx
export function YourScreen() {
  return <View>Your screen</View>;
}

2. Add to navigation:

// mobile/app/_layout.tsx
// Add screen to navigation

3. Add tests:

// Add mobile tests

Adding a New Feature Flag

1. Define flag:

// shared/feature-flags.ts
export const FEATURE_FLAGS = {
  yourFeature: {
    enabled: false,
    description: 'Your feature description',
  },
};

2. Implement flag check:

// Use flag in code
if (FEATURE_FLAGS.yourFeature.enabled) {
  // feature code
}

3. Test flag:

// 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!