570 lines
13 KiB
Markdown
570 lines
13 KiB
Markdown
# Panda Monorepo
|
|
|
|
**Status**: 🚧 **Placeholder - Under Planning**
|
|
**Purpose**: Unified monorepository for all Panda ecosystem projects with shared code, tooling, and unified dependency management.
|
|
|
|
**Note**: PANDA (Pan-African Network for Digital Advancement) is a partner in **PanTel**, a telecommunications joint venture with Sankofa. The panda_monorepo organizes PANDA-related projects.
|
|
|
|
---
|
|
|
|
## Overview
|
|
|
|
The Panda Monorepo consolidates all Panda ecosystem projects into a single, unified repository structure. This enables shared code, unified versioning, simplified dependency management, and coordinated development across all Panda initiatives.
|
|
|
|
---
|
|
|
|
## Purpose
|
|
|
|
The monorepo structure provides:
|
|
|
|
- **Unified Development**: Single repository for all Panda projects
|
|
- **Shared Libraries**: Common code, types, and utilities across projects
|
|
- **Dependency Management**: Unified versioning and dependency resolution
|
|
- **Cross-Project Refactoring**: Easier refactoring across project boundaries
|
|
- **Coordinated Releases**: Unified versioning and release process
|
|
- **Shared Tooling**: Common build, test, and deployment tools
|
|
- **Simplified CI/CD**: Single pipeline for all projects
|
|
|
|
---
|
|
|
|
## Monorepo Structure (Planned)
|
|
|
|
```
|
|
panda_monorepo/
|
|
├── .github/ # GitHub workflows (if using GitHub)
|
|
│ └── workflows/ # CI/CD workflows
|
|
├── .gitmodules # Git submodules configuration
|
|
├── packages/ # Shared packages and libraries
|
|
│ ├── panda-shared/ # Shared TypeScript libraries
|
|
│ │ ├── types/ # TypeScript type definitions
|
|
│ │ ├── utils/ # Utility functions
|
|
│ │ ├── constants/ # Shared constants
|
|
│ │ └── config/ # Configuration utilities
|
|
│ ├── panda-api-client/ # API client libraries
|
|
│ ├── panda-schemas/ # JSON/GraphQL schemas
|
|
│ ├── panda-auth/ # Authentication/authorization
|
|
│ └── [project-packages]/ # Individual project packages
|
|
├── apps/ # Applications
|
|
│ ├── [panda-app-1]/ # Application 1 (TBD)
|
|
│ ├── [panda-app-2]/ # Application 2 (TBD)
|
|
│ └── [panda-app-n]/ # Additional applications
|
|
├── tools/ # Development and operational tools
|
|
│ ├── [panda-tool-1]/ # Tool 1 (TBD)
|
|
│ └── [panda-tool-n]/ # Additional tools
|
|
├── docs/ # Documentation
|
|
│ ├── panda-docs/ # Documentation (submodule)
|
|
│ ├── architecture/ # Architecture documentation
|
|
│ ├── development/ # Development guides
|
|
│ └── deployment/ # Deployment guides
|
|
├── infrastructure/ # Infrastructure as Code
|
|
│ ├── terraform/ # Terraform configurations
|
|
│ ├── kubernetes/ # Kubernetes manifests
|
|
│ └── helm/ # Helm charts
|
|
├── scripts/ # Monorepo management scripts
|
|
│ ├── bootstrap.sh # Initial setup script
|
|
│ ├── test-all.sh # Run all tests
|
|
│ ├── build-all.sh # Build all packages
|
|
│ └── release.sh # Release management
|
|
├── package.json # Root package.json (if using npm/pnpm workspaces)
|
|
├── pnpm-workspace.yaml # pnpm workspace configuration
|
|
├── turbo.json # Turborepo configuration (if using Turborepo)
|
|
├── nx.json # Nx configuration (if using Nx)
|
|
└── README.md # This file
|
|
```
|
|
|
|
---
|
|
|
|
## Submodules & Projects (Planned)
|
|
|
|
### Documentation (Submodule)
|
|
|
|
| Submodule | Path | Description | Status |
|
|
|-----------|------|-------------|--------|
|
|
| **pan-tel** | `packages/pan-tel` or `apps/pan-tel` | Telecommunications project | 🚧 Placeholder |
|
|
| **panda_docs** | `docs/panda-docs` | Documentation repository | 🚧 Placeholder |
|
|
|
|
**Note**:
|
|
- The `pan-tel` project content is currently archived in `loc_az_hci` under an archive beginning with `6g_gpu*`. The project directory serves as a placeholder until the archive is unpacked and integrated.
|
|
- PanTel is a **joint venture** between Sankofa and PANDA (Pan-African Network for Digital Advancement).
|
|
|
|
### Projects (To Be Added)
|
|
|
|
Projects in the Panda ecosystem will be integrated as submodules or packages. Specific projects are to be determined.
|
|
|
|
---
|
|
|
|
## Package Manager & Tooling
|
|
|
|
### Recommended: pnpm Workspaces + Turborepo
|
|
|
|
**Benefits:**
|
|
- Fast installs with pnpm
|
|
- Build caching with Turborepo
|
|
- Task orchestration
|
|
- Dependency graph optimization
|
|
|
|
### Alternative: Nx
|
|
|
|
**Benefits:**
|
|
- Comprehensive monorepo tooling
|
|
- Advanced dependency graph
|
|
- Code generation
|
|
- Testing and building
|
|
|
|
### Configuration Example (pnpm + Turborepo)
|
|
|
|
```yaml
|
|
# pnpm-workspace.yaml
|
|
packages:
|
|
- 'packages/*'
|
|
- 'apps/*'
|
|
- 'tools/*'
|
|
```
|
|
|
|
```json
|
|
// turbo.json
|
|
{
|
|
"pipeline": {
|
|
"build": {
|
|
"dependsOn": ["^build"],
|
|
"outputs": ["dist/**", "build/**"]
|
|
},
|
|
"test": {
|
|
"dependsOn": ["build"],
|
|
"outputs": ["coverage/**"]
|
|
},
|
|
"lint": {},
|
|
"type-check": {}
|
|
}
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## Shared Packages (Planned)
|
|
|
|
### panda-shared
|
|
**Purpose**: Common utilities and types shared across all Panda projects
|
|
|
|
**Contents:**
|
|
- TypeScript type definitions
|
|
- Utility functions
|
|
- Configuration helpers
|
|
- Constants and enums
|
|
- Validation schemas
|
|
|
|
### panda-api-client
|
|
**Purpose**: Type-safe API clients for Panda services
|
|
|
|
**Contents:**
|
|
- REST API clients
|
|
- GraphQL clients
|
|
- WebSocket clients
|
|
- Type definitions for API responses
|
|
|
|
### panda-schemas
|
|
**Purpose**: Shared data schemas and validation
|
|
|
|
**Contents:**
|
|
- JSON schemas
|
|
- GraphQL schemas
|
|
- Prisma schemas (if applicable)
|
|
- Zod validation schemas
|
|
|
|
### panda-auth
|
|
**Purpose**: Shared authentication and authorization
|
|
|
|
**Contents:**
|
|
- Auth utilities
|
|
- Token management
|
|
- Permission checking
|
|
- Session management
|
|
|
|
---
|
|
|
|
## Development Workflow (Planned)
|
|
|
|
### Setup
|
|
|
|
```bash
|
|
# Clone monorepo
|
|
git clone <monorepo-url>
|
|
cd panda_monorepo
|
|
|
|
# Initialize submodules
|
|
git submodule update --init --recursive
|
|
|
|
# Install dependencies
|
|
pnpm install
|
|
|
|
# Build all packages
|
|
pnpm build
|
|
|
|
# Run tests
|
|
pnpm test
|
|
```
|
|
|
|
### Adding a New Package
|
|
|
|
```bash
|
|
# Create new package
|
|
mkdir -p packages/my-package
|
|
cd packages/my-package
|
|
|
|
# Initialize package
|
|
pnpm init
|
|
|
|
# Add to workspace (already configured in pnpm-workspace.yaml)
|
|
|
|
# Install dependencies
|
|
pnpm add <dependency>
|
|
|
|
# Build
|
|
pnpm build
|
|
```
|
|
|
|
### Working with Submodules
|
|
|
|
```bash
|
|
# Update all submodules
|
|
git submodule update --remote
|
|
|
|
# Add new submodule
|
|
git submodule add <repository-url> packages/panda-new-project
|
|
|
|
# Commit submodule updates
|
|
git add .gitmodules packages/panda-new-project
|
|
git commit -m "Add panda-new-project submodule"
|
|
```
|
|
|
|
### Building and Testing
|
|
|
|
```bash
|
|
# Build all packages
|
|
pnpm build
|
|
|
|
# Build specific package
|
|
pnpm --filter @panda/shared build
|
|
|
|
# Run all tests
|
|
pnpm test
|
|
|
|
# Run tests for specific package
|
|
pnpm --filter @panda/shared test
|
|
|
|
# Type check all packages
|
|
pnpm type-check
|
|
|
|
# Lint all packages
|
|
pnpm lint
|
|
```
|
|
|
|
---
|
|
|
|
## CI/CD Pipeline (Planned)
|
|
|
|
### Workflow Structure
|
|
|
|
1. **Lint & Type Check**: Run on all packages
|
|
2. **Unit Tests**: Run package-specific tests
|
|
3. **Integration Tests**: Run cross-package tests
|
|
4. **Build**: Build all packages
|
|
5. **E2E Tests**: Run end-to-end tests
|
|
6. **Deploy**: Deploy based on changed packages
|
|
|
|
### Turborepo Pipeline
|
|
|
|
```yaml
|
|
# .github/workflows/ci.yml (example)
|
|
- Build packages (cached)
|
|
- Test packages (cached)
|
|
- Type check (cached)
|
|
- Lint (cached)
|
|
- Integration tests
|
|
- E2E tests
|
|
- Build Docker images (for applications)
|
|
- Deploy (staging/production)
|
|
```
|
|
|
|
---
|
|
|
|
## Versioning Strategy
|
|
|
|
### Option 1: Independent Versioning
|
|
- Each package has its own version
|
|
- Semantic versioning per package
|
|
- Useful for submodules approach
|
|
|
|
### Option 2: Unified Versioning
|
|
- Single version for monorepo
|
|
- All packages versioned together
|
|
- Easier for coordinated releases
|
|
|
|
**Recommendation**: Start with independent versioning, consider unified for major releases.
|
|
|
|
---
|
|
|
|
## Dependency Management
|
|
|
|
### Shared Dependencies
|
|
|
|
Common dependencies should be hoisted to root:
|
|
|
|
```json
|
|
// package.json (root)
|
|
{
|
|
"devDependencies": {
|
|
"typescript": "^5.0.0",
|
|
"@types/node": "^20.0.0",
|
|
"eslint": "^8.0.0",
|
|
"prettier": "^3.0.0"
|
|
}
|
|
}
|
|
```
|
|
|
|
### Package-Specific Dependencies
|
|
|
|
Package-specific dependencies in package.json:
|
|
|
|
```json
|
|
// packages/panda-shared/package.json
|
|
{
|
|
"dependencies": {
|
|
"zod": "^3.22.0"
|
|
}
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## Documentation Structure
|
|
|
|
### Monorepo-Level Documentation
|
|
- Architecture overview
|
|
- Development setup
|
|
- Contribution guidelines
|
|
- Release process
|
|
- CI/CD documentation
|
|
|
|
### Package-Level Documentation
|
|
Each package maintains its own:
|
|
- README.md
|
|
- API documentation
|
|
- Usage examples
|
|
- Changelog
|
|
|
|
### Documentation Submodule
|
|
### Documentation Submodule
|
|
- **[panda_docs](../panda_docs/)** - Documentation repository (submodule)
|
|
- Integrated documentation site
|
|
- API documentation generation
|
|
- User and developer guides
|
|
|
|
---
|
|
|
|
## Integration Strategy
|
|
|
|
### Phase 1: Foundation
|
|
- Initialize monorepo structure
|
|
- Set up package manager and tooling
|
|
- Create shared packages
|
|
- Add documentation submodule
|
|
|
|
### Phase 2: Project Integration
|
|
- Add existing projects as submodules
|
|
- Extract shared code to packages
|
|
- Update projects to use shared packages
|
|
|
|
### Phase 3: Full Integration (Optional)
|
|
- Move projects into monorepo as packages
|
|
- Unified CI/CD
|
|
- Unified versioning
|
|
|
|
---
|
|
|
|
## Benefits of Monorepo Structure
|
|
|
|
### For Development
|
|
- ✅ Shared code and types
|
|
- ✅ Easier refactoring across projects
|
|
- ✅ Unified tooling and configurations
|
|
- ✅ Single source of truth
|
|
- ✅ Faster local development
|
|
|
|
### For Operations
|
|
- ✅ Coordinated releases
|
|
- ✅ Unified CI/CD pipeline
|
|
- ✅ Easier dependency management
|
|
- ✅ Simplified testing
|
|
- ✅ Better visibility across projects
|
|
|
|
### For Maintenance
|
|
- ✅ Easier to keep dependencies updated
|
|
- ✅ Consistent code quality standards
|
|
- ✅ Centralized documentation
|
|
- ✅ Simplified onboarding
|
|
|
|
---
|
|
|
|
## Prerequisites (For Development)
|
|
|
|
### Required Tools
|
|
- **Node.js** >= 18.0.0
|
|
- **pnpm** >= 8.0.0 (recommended) or npm/yarn
|
|
- **Git** with submodule support
|
|
- **Docker** (for local development, if needed)
|
|
|
|
### Optional Tools
|
|
- **Turborepo** (for build orchestration)
|
|
- **Nx** (alternative monorepo tooling)
|
|
|
|
---
|
|
|
|
## Getting Started (When Implemented)
|
|
|
|
### Initial Setup
|
|
|
|
```bash
|
|
# Clone repository
|
|
git clone <monorepo-url>
|
|
cd panda_monorepo
|
|
|
|
# Initialize submodules
|
|
git submodule update --init --recursive
|
|
|
|
# Install dependencies
|
|
pnpm install
|
|
|
|
# Build all packages
|
|
pnpm build
|
|
|
|
# Run development servers
|
|
pnpm dev
|
|
```
|
|
|
|
### Development Commands
|
|
|
|
```bash
|
|
# Install dependencies for all packages
|
|
pnpm install
|
|
|
|
# Build all packages
|
|
pnpm build
|
|
|
|
# Run all tests
|
|
pnpm test
|
|
|
|
# Run linting
|
|
pnpm lint
|
|
|
|
# Type check all packages
|
|
pnpm type-check
|
|
|
|
# Watch mode for development
|
|
pnpm dev
|
|
|
|
# Clean all build artifacts
|
|
pnpm clean
|
|
```
|
|
|
|
### Package-Specific Commands
|
|
|
|
```bash
|
|
# Work in specific package
|
|
cd packages/panda-shared
|
|
pnpm install
|
|
pnpm build
|
|
pnpm test
|
|
|
|
# Or use filter
|
|
pnpm --filter @panda/shared build
|
|
pnpm --filter @panda/shared test
|
|
```
|
|
|
|
---
|
|
|
|
## Roadmap
|
|
|
|
### Phase 1: Setup (Weeks 1-2)
|
|
- [ ] Initialize monorepo structure
|
|
- [ ] Set up package manager (pnpm workspaces)
|
|
- [ ] Configure build tooling (Turborepo/Nx)
|
|
- [ ] Add documentation submodule (panda_docs)
|
|
- [ ] Set up basic CI/CD
|
|
|
|
### Phase 2: Shared Packages (Weeks 3-6)
|
|
- [ ] Create panda-shared package
|
|
- [ ] Create panda-api-client
|
|
- [ ] Create panda-schemas
|
|
- [ ] Create panda-auth
|
|
- [ ] Document shared packages
|
|
|
|
### Phase 3: Project Integration (Weeks 7-12)
|
|
- [ ] Add Panda ecosystem projects as submodules
|
|
- [ ] Extract shared code to packages
|
|
- [ ] Update projects to use shared packages
|
|
- [ ] Unified build system
|
|
- [ ] Cross-package testing
|
|
|
|
### Phase 4: Optimization (Weeks 13-14)
|
|
- [ ] Build caching optimization
|
|
- [ ] Dependency optimization
|
|
- [ ] Development workflow improvements
|
|
- [ ] Production hardening
|
|
|
|
---
|
|
|
|
## Related Projects
|
|
|
|
### Documentation
|
|
- **[panda_docs](../panda_docs/)** - Documentation repository (submodule)
|
|
|
|
### Panda Ecosystem Projects
|
|
- Projects to be added as submodules or packages
|
|
|
|
---
|
|
|
|
## Contributing
|
|
|
|
When contributing to the monorepo:
|
|
|
|
1. **Follow Monorepo Standards**:
|
|
- Use shared packages where possible
|
|
- Maintain package boundaries
|
|
- Update shared code carefully
|
|
|
|
2. **Development Process**:
|
|
- Create feature branch
|
|
- Update affected packages
|
|
- Run tests for all packages
|
|
- Update documentation
|
|
|
|
3. **Submodule Updates**:
|
|
- Update submodule in separate PR
|
|
- Test integration
|
|
- Update documentation
|
|
|
|
---
|
|
|
|
## License
|
|
|
|
[To be determined - will align with Panda ecosystem licensing]
|
|
|
|
---
|
|
|
|
## Status
|
|
|
|
**Current Status**: 🚧 Placeholder
|
|
**Next Steps**:
|
|
- Define Panda ecosystem projects
|
|
- Finalize monorepo tooling choice (Turborepo vs Nx)
|
|
- Set up initial structure
|
|
- Add panda_docs as submodule
|
|
- Begin Phase 1 implementation
|
|
|
|
---
|
|
|
|
**Last Updated**: 2025-01-27
|
|
**Monorepo Tool**: TBD (Turborepo or Nx recommended)
|
|
|