docs/DEPENDENCY_CONSOLIDATION_PLAN.md

# Dependency Consolidation Plan

**Date**: 2025-01-27
**Based On**: Dependency Analysis Report (`reports/dependency-analysis.md`)
**Status**: Implementation Plan

---

## Executive Summary

This plan consolidates dependencies across 111+ package.json files, identifying opportunities to reduce duplication, standardize versions, and extract shared packages.

**Key Findings**:
- **86 projects** use TypeScript
- **22 projects** use ethers (blockchain)
- **20 projects** use dotenv
- **18 projects** use axios
- **17 projects** use zod and react
- **40 projects** use ESLint

---

## Phase 1: Immediate Actions (Week 1-2)

### 1.1 Hoist Common DevDependencies to Workspace Root

**Target Dependencies**:
- `typescript` (86 projects) → Workspace root
- `@types/node` (75 projects) → Workspace root
- `eslint` (40 projects) → Workspace root
- `prettier` (18 projects) → Workspace root
- `@typescript-eslint/parser` (15 projects) → Workspace root
- `@typescript-eslint/eslint-plugin` (15 projects) → Workspace root

**Action**:
```json
// package.json (root)
{
  "devDependencies": {
    "typescript": "^5.5.4",
    "@types/node": "^20.11.0",
    "eslint": "^9.17.0",
    "prettier": "^3.3.3",
    "@typescript-eslint/parser": "^7.18.0",
    "@typescript-eslint/eslint-plugin": "^7.18.0"
  }
}
```

**Benefits**:
- Single source of truth for tooling versions
- Reduced disk space (shared node_modules)
- Faster installs
- Consistent tooling across projects

### 1.2 Version Standardization

**Priority Dependencies**:

| Dependency | Current Versions | Target Version | Projects Affected |
|------------|------------------|----------------|-------------------|
| typescript | Multiple (5.3.3, 5.5.4, etc.) | 5.5.4 | 86 |
| zod | Multiple (3.22.4, 3.23.8, etc.) | 3.23.8 | 17 |
| eslint | Multiple (8.56.0, 8.57.0, 9.17.0) | 9.17.0 | 40 |
| prettier | Multiple (3.1.1, 3.2.0, 3.3.3) | 3.3.3 | 18 |
| react | Multiple versions | Latest stable | 17 |
| react-dom | Multiple versions | Latest stable | 16 |

**Action Plan**:
1. Create version mapping document
2. Update package.json files in batches
3. Test after each batch
4. Document breaking changes

---

## Phase 2: Shared Package Extraction (Weeks 3-8)

### 2.1 High-Priority Shared Packages

#### @workspace/shared-types
**Usage**: Used across dbis_core, the_order, Sankofa, and others
**Contents**:
- Common TypeScript types
- API response types
- Database model types
- Configuration types

**Dependencies to Extract**:
- Type definitions only (no runtime deps)

#### @workspace/shared-utils
**Usage**: Used in 20+ projects
**Contents**:
- Date formatting utilities
- Validation helpers
- String manipulation
- Common algorithms

**Dependencies to Extract**:
- `date-fns` (5+ projects)
- `uuid` (8 projects)
- Common utility functions

#### @workspace/shared-config
**Usage**: All projects with configuration
**Contents**:
- Environment variable schemas
- Configuration validation
- Default configurations

**Dependencies to Extract**:
- `dotenv` (20 projects)
- `zod` (17 projects) - for config validation

#### @workspace/shared-constants
**Usage**: DBIS projects, DeFi projects
**Contents**:
- Shared constants
- Enums
- Error codes
- Status values

**Dependencies to Extract**:
- Constants only (no deps)

### 2.2 Medium-Priority Shared Packages

#### @workspace/api-client
**Usage**: Frontend projects, API consumers
**Contents**:
- HTTP client utilities
- Request/response interceptors
- Error handling
- Retry logic

**Dependencies to Extract**:
- `axios` (18 projects)
- Common API patterns

#### @workspace/validation
**Usage**: Multiple backend services
**Contents**:
- Zod schemas
- Validators
- Validation utilities

**Dependencies to Extract**:
- `zod` (17 projects)
- Validation schemas

#### @workspace/blockchain
**Usage**: Blockchain projects
**Contents**:
- Ethereum utilities
- Contract interaction helpers
- Transaction utilities

**Dependencies to Extract**:
- `ethers` (22 projects)
- Common blockchain patterns

---

## Phase 3: Dependency Registry Setup (Weeks 5-6)

### 3.1 Private npm Registry

**Options**:
1. **Verdaccio** (Recommended - Self-hosted, lightweight)
2. **npm Enterprise** (Commercial)
3. **GitHub Packages** (Integrated with GitHub)

**Recommendation**: Verdaccio for self-hosted, GitHub Packages for cloud

**Setup Steps**:
1. Deploy Verdaccio instance
2. Configure authentication
3. Set up publishing workflow
4. Configure projects to use registry

### 3.2 Version Pinning Strategy

**Strategy**: Semantic versioning with workspace protocol

```json
{
  "dependencies": {
    "@workspace/shared-types": "workspace:*",
    "@workspace/shared-utils": "workspace:^1.0.0"
  }
}
```

**Benefits**:
- Always use latest workspace version during development
- Pin versions for releases
- Easy updates across projects

---

## Phase 4: Automated Dependency Management (Weeks 7-8)

### 4.1 Dependabot Configuration

**Setup**:
- Enable Dependabot for all projects
- Configure update frequency
- Set up security alerts
- Configure auto-merge for patch updates

### 4.2 Dependency Update Workflow

**Process**:
1. Weekly dependency scans
2. Automated PR creation
3. Automated testing
4. Manual review for major updates
5. Automated merge for patch/minor (after tests pass)

---

## Implementation Checklist

### Phase 1: Immediate (Week 1-2)
- [ ] Hoist TypeScript to workspace root
- [ ] Hoist ESLint to workspace root
- [ ] Hoist Prettier to workspace root
- [ ] Standardize TypeScript version (5.5.4)
- [ ] Standardize ESLint version (9.17.0)
- [ ] Standardize Prettier version (3.3.3)
- [ ] Update 10 projects as pilot
- [ ] Test and verify

### Phase 2: Shared Packages (Weeks 3-8)
- [ ] Create workspace-shared/ directory
- [ ] Set up pnpm workspaces
- [ ] Create @workspace/shared-types package
- [ ] Create @workspace/shared-utils package
- [ ] Create @workspace/shared-config package
- [ ] Create @workspace/shared-constants package
- [ ] Extract common code to packages
- [ ] Update projects to use shared packages
- [ ] Test integration

### Phase 3: Registry (Weeks 5-6)
- [ ] Deploy Verdaccio or configure GitHub Packages
- [ ] Set up authentication
- [ ] Configure publishing workflow
- [ ] Publish first shared packages
- [ ] Update projects to use registry

### Phase 4: Automation (Weeks 7-8)
- [ ] Configure Dependabot
- [ ] Set up dependency update workflow
- [ ] Configure automated testing
- [ ] Set up security scanning
- [ ] Document update process

---

## Expected Benefits

### Immediate (Phase 1)
- **30% reduction** in duplicate dev dependencies
- **Faster installs** (shared node_modules)
- **Consistent tooling** across projects

### Short-Term (Phase 2)
- **50% reduction** in duplicate production dependencies
- **Easier maintenance** (update once, use everywhere)
- **Better code reuse**

### Long-Term (Phase 3-4)
- **Automated updates** reduce maintenance burden
- **Security** through automated scanning
- **Consistency** across all projects

---

## Risk Mitigation

### Breaking Changes
- **Mitigation**: Gradual migration, comprehensive testing
- **Rollback**: Keep old dependencies until migration complete

### Version Conflicts
- **Mitigation**: Use workspace protocol, pin versions for releases
- **Testing**: Test all projects after updates

### Registry Availability
- **Mitigation**: Use GitHub Packages as backup
- **Monitoring**: Monitor registry health

---

## Success Metrics

- [ ] 30% reduction in duplicate dependencies (Phase 1)
- [ ] 50% reduction in duplicate dependencies (Phase 2)
- [ ] 10+ shared packages created (Phase 2)
- [ ] 80% of projects using shared packages (Phase 2)
- [ ] Automated dependency updates working (Phase 4)
- [ ] Zero security vulnerabilities in dependencies (Phase 4)

---

**Last Updated**: 2025-01-27
**Next Review**: After Phase 1 completion