# DBIS Monorepo Migration Plan

**Date**: 2025-01-27
**Purpose**: Detailed migration plan for consolidating DBIS projects into monorepo
**Status**: Implementation Plan

---

## Executive Summary

This plan outlines the migration of DBIS projects (dbis_core, smom-dbis-138, dbis_docs, dbis_portal, dbis_dc_tools) into a unified monorepo structure.

**Target Projects**:
- dbis_core (Active)
- smom-dbis-138 (Active)
- dbis_docs (Active)
- dbis_portal (Placeholder)
- dbis_dc_tools (Placeholder)

---

## Migration Strategy

### Approach: Submodule + Workspace Packages

**Phase 1**: Add projects as git submodules (maintain independence)
**Phase 2**: Extract shared code to workspace packages
**Phase 3**: Gradually integrate (optional full migration)

---

## Phase 1: Structure Setup (Weeks 1-2)

### 1.1 Initialize Monorepo

**Tasks**:
- [ ] Initialize git repository in `dbis_monorepo/`
- [ ] Set up pnpm workspaces
- [ ] Configure Turborepo
- [ ] Create directory structure
- [ ] Set up CI/CD base configuration

**Structure**:
```
dbis_monorepo/
├── .gitmodules
├── packages/
│   ├── dbis-core/          # Submodule
│   ├── dbis-blockchain/    # Submodule (smom-dbis-138)
│   ├── dbis-docs/          # Submodule
│   ├── dbis-shared/        # Workspace package
│   ├── dbis-api-client/    # Workspace package
│   └── dbis-schemas/       # Workspace package
├── apps/
│   └── dbis-portal/        # Submodule (when ready)
├── tools/
│   └── dbis-dc-tools/      # Submodule (when ready)
├── infrastructure/
├── docs/
├── package.json
├── pnpm-workspace.yaml
└── turbo.json
```

### 1.2 Add Projects as Submodules

**Commands**:
```bash
cd dbis_monorepo
git submodule add <dbis_core-url> packages/dbis-core
git submodule add <smom-dbis-138-url> packages/dbis-blockchain
git submodule add <dbis_docs-url> packages/dbis-docs
```

**Status Tracking**:
- [ ] Add dbis_core as submodule
- [ ] Add smom-dbis-138 as submodule
- [ ] Add dbis_docs as submodule
- [ ] Verify submodule setup
- [ ] Document submodule management

---

## Phase 2: Shared Packages (Weeks 3-6)

### 2.1 Create dbis-shared Package

**Purpose**: Common utilities and types

**Contents**:
- TypeScript type definitions
- Utility functions
- Configuration helpers
- Constants and enums
- Validation schemas

**Tasks**:
- [ ] Create `packages/dbis-shared/` structure
- [ ] Extract common types from dbis_core
- [ ] Extract common types from smom-dbis-138
- [ ] Extract utility functions
- [ ] Create package.json and build config
- [ ] Publish to workspace

**Usage Example**:
```typescript
import { DBISConfig, DBISError } from '@dbis/shared';
import { validateTransaction } from '@dbis/shared/validation';
```

### 2.2 Create dbis-api-client Package

**Purpose**: Type-safe API clients

**Contents**:
- REST API clients
- GraphQL clients
- WebSocket clients
- Type definitions

**Tasks**:
- [ ] Create `packages/dbis-api-client/` structure
- [ ] Extract API client code from dbis_core
- [ ] Create type-safe clients
- [ ] Document API client usage
- [ ] Publish to workspace

### 2.3 Create dbis-schemas Package

**Purpose**: Shared data schemas

**Contents**:
- JSON schemas
- GraphQL schemas
- Prisma schemas (shared models)
- Zod validation schemas

**Tasks**:
- [ ] Create `packages/dbis-schemas/` structure
- [ ] Extract schemas from dbis_core
- [ ] Extract schemas from smom-dbis-138
- [ ] Create unified schema definitions
- [ ] Publish to workspace

---

## Phase 3: Integration (Weeks 7-10)

### 3.1 Update Projects to Use Shared Packages

**dbis_core**:
- [ ] Add @dbis/shared dependency
- [ ] Replace local types with shared types
- [ ] Replace local utilities with shared utilities
- [ ] Update imports
- [ ] Test integration

**smom-dbis-138**:
- [ ] Add @dbis/shared dependency
- [ ] Replace local types with shared types
- [ ] Update imports
- [ ] Test integration

### 3.2 Unified CI/CD

**Configuration**:
- [ ] Set up Turborepo pipeline
- [ ] Configure build dependencies
- [ ] Set up test pipeline
- [ ] Configure deployment pipeline
- [ ] Document CI/CD workflow

**Pipeline Stages**:
1. Lint & Format
2. Type Check
3. Build (with dependencies)
4. Test
5. Security Scan
6. Deploy

### 3.3 Cross-Package Testing

**Setup**:
- [ ] Configure integration tests
- [ ] Set up test dependencies
- [ ] Create test utilities
- [ ] Document testing strategy

---

## Phase 4: Optimization (Weeks 11-12)

### 4.1 Build Optimization

**Tasks**:
- [ ] Optimize Turborepo caching
- [ ] Parallelize builds
- [ ] Reduce build times
- [ ] Optimize dependency graph

### 4.2 Dependency Optimization

**Tasks**:
- [ ] Audit dependencies
- [ ] Remove duplicates
- [ ] Update versions
- [ ] Optimize package sizes

### 4.3 Documentation

**Tasks**:
- [ ] Complete monorepo documentation
- [ ] Document shared packages
- [ ] Create migration guides
- [ ] Update project READMEs

---

## Shared Packages Details

### @dbis/shared

**Dependencies**:
- No runtime dependencies (types only)
- Dev dependencies: TypeScript, Vitest

**Exports**:
```typescript
// Types
export * from './types';
export * from './config';
export * from './constants';

// Utilities
export * from './utils';
export * from './validation';
```

### @dbis/api-client

**Dependencies**:
- axios
- @dbis/shared

**Exports**:
```typescript
export { DBISApiClient } from './client';
export { createGraphQLClient } from './graphql';
export * from './types';
```

### @dbis/schemas

**Dependencies**:
- zod
- @dbis/shared

**Exports**:
```typescript
export * from './json';
export * from './graphql';
export * from './prisma';
export * from './zod';
```

---

## Migration Timeline

### Week 1-2: Structure Setup
- Initialize monorepo
- Add submodules
- Set up tooling

### Week 3-4: Shared Packages (Part 1)
- Create dbis-shared
- Extract common types
- Extract utilities

### Week 5-6: Shared Packages (Part 2)
- Create dbis-api-client
- Create dbis-schemas
- Publish packages

### Week 7-8: Integration
- Update projects to use shared packages
- Set up unified CI/CD
- Integration testing

### Week 9-10: Testing & Validation
- Comprehensive testing
- Performance validation
- Documentation

### Week 11-12: Optimization
- Build optimization
- Dependency optimization
- Final documentation

---

## Risk Mitigation

### Breaking Changes
- **Mitigation**: Gradual migration, maintain backward compatibility
- **Testing**: Comprehensive test coverage
- **Rollback**: Keep old structure until migration complete

### Submodule Management
- **Mitigation**: Document submodule workflow
- **Training**: Team training on submodule usage
- **Automation**: Scripts for submodule updates

### Dependency Conflicts
- **Mitigation**: Version pinning, workspace protocol
- **Testing**: Test all projects after updates
- **Isolation**: Isolated testing environments

---

## Success Metrics

- [ ] All DBIS projects in monorepo
- [ ] 3+ shared packages created
- [ ] Projects using shared packages
- [ ] Unified CI/CD operational
- [ ] 50% reduction in duplicate code
- [ ] Faster build times (Turborepo caching)

---

## Related Documents

- [DBIS Monorepo README](../dbis_monorepo/README.md)
- [Integration & Streamlining Plan](../INTEGRATION_STREAMLINING_PLAN.md)
- [Dependency Consolidation Plan](./DEPENDENCY_CONSOLIDATION_PLAN.md)

---

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