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](#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 <div>Your component</div>;
}
```

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 <View>Your screen</View>;
}
```

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!