docs/ONBOARDING_GUIDE.md

# Developer Onboarding Guide

**Date**: 2025-01-27
**Purpose**: Comprehensive guide for new developers joining the workspace
**Status**: Complete

---

## Welcome!

This guide will help you get started with the workspace projects and understand the development workflow.

---

## Prerequisites

### Required Software
- **Node.js**: >= 18.0.0
- **pnpm**: >= 8.0.0
- **Git**: Latest version
- **Docker**: (for containerized projects)
- **VS Code**: (recommended IDE)

### Recommended Extensions
- ESLint
- Prettier
- TypeScript
- GitLens

---

## Workspace Overview

### Project Structure
- **40+ projects** across 8 categories
- **6 monorepos** with 18 submodules
- **Shared packages** in `workspace-shared/`
- **Infrastructure** in `infrastructure/`

### Key Directories
- `workspace-shared/` - Shared packages and libraries
- `infrastructure/` - Infrastructure as Code
- `docs/` - Documentation hub
- `scripts/` - Workspace utility scripts

---

## Getting Started

### 1. Clone Repository

```bash
# Clone with submodules
git clone --recurse-submodules <repository-url>
cd projects
```

### 2. Install Dependencies

```bash
# Install workspace dependencies
pnpm install

# Install dependencies for specific project
cd project-name
pnpm install
```

### 3. Set Up Environment

```bash
# Copy environment template
cp .env.example .env

# Edit environment variables
nano .env
```

### 4. Verify Setup

```bash
# Run workspace verification
pnpm verify

# Test specific project
cd project-name
pnpm test
```

---

## Development Workflow

### Working with Shared Packages

```bash
# Use shared package in your project
cd your-project
pnpm add @workspace/shared-types@workspace:*
pnpm add @workspace/shared-auth@workspace:*
```

### Running Projects

```bash
# Development mode
pnpm dev

# Production build
pnpm build

# Run tests
pnpm test

# Lint code
pnpm lint
```

### Making Changes

1. **Create branch**: `git checkout -b feature/your-feature`
2. **Make changes**: Edit code, add tests
3. **Test locally**: `pnpm test && pnpm lint`
4. **Commit**: `git commit -m "feat: your feature"`
5. **Push**: `git push origin feature/your-feature`
6. **Create PR**: Open pull request on GitHub

---

## Project Categories

### Blockchain & DeFi
- **Defi-Mix-Tooling**: Monorepo with 6 DeFi projects
- **smom-dbis-138**: DBIS blockchain infrastructure
- **27-combi, 237-combo**: DeFi tools

### Banking & Financial
- **dbis_core**: Core banking system
- **the_order**: Identity platform
- **dbis_docs**: Documentation

### Infrastructure
- **loc_az_hci**: Proxmox infrastructure
- **Sankofa**: Blockchain orchestration

---

## Code Standards

### TypeScript
- Use TypeScript for all new code
- Enable strict mode
- Use shared types from `@workspace/shared-types`

### Testing
- Write tests for all new features
- Aim for 80%+ coverage
- Use Vitest or Jest

### Documentation
- Update README for significant changes
- Document public APIs
- Add JSDoc comments

---

## Common Tasks

### Adding a New Shared Package

1. Create package in `workspace-shared/packages/`
2. Add to `pnpm-workspace.yaml`
3. Build: `pnpm build`
4. Publish: `pnpm publish`

### Updating Dependencies

```bash
# Check for updates
pnpm outdated

# Update dependencies
pnpm update

# Audit security
pnpm audit
```

### Running CI/CD Locally

```bash
# Install act (GitHub Actions local runner)
brew install act

# Run workflow
act -W .github/workflows/ci.yml
```

---

## Resources

### Documentation
- [Integration Plan](../INTEGRATION_STREAMLINING_PLAN.md)
- [Project Review](../COMPREHENSIVE_PROJECT_REVIEW.md)
- [Monorepo Structure](../MONOREPO_STRUCTURE.md)

### Tools
- [Dependency Audit](./DEPENDENCY_AUDIT.md)
- [CI/CD Guide](./CI_CD_MIGRATION_GUIDE.md)
- [Terraform Modules](./TERRAFORM_MODULES_CONSOLIDATION.md)

---

## Getting Help

### Questions?
- Check project README
- Review documentation in `docs/`
- Ask team on Slack/Discord
- Open GitHub issue

### Reporting Issues
- Use GitHub Issues
- Include reproduction steps
- Add relevant logs
- Tag with appropriate labels

---

**Last Updated**: 2025-01-27