docs/DBIS_MONOREPO_MIGRATION_PLAN.md

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:

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:

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:

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

export { DBISApiClient } from './client';
export { createGraphQLClient } from './graphql';
export * from './types';

@dbis/schemas

Dependencies:

• zod
• @dbis/shared

Exports:

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
• Integration & Streamlining Plan
• Dependency Consolidation Plan

---

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