💡 PROPOSAL: Microkernel Architecture - Split into Focused Micro-Packages

[jordanpartridge]

💡 Proposal: Microkernel Architecture for GitHub Client

Background

While working on Conduit - a microkernel CLI with component system - I've been exploring ultra-modular package architectures. This sparked an idea for github-client that could benefit the broader ecosystem.

Current State vs. Vision

Current (Monolithic):

composer require jordanpartridge/github-client  # Everything (~500KB+)

Proposed (Microkernel):

# Core foundation
composer require jordanpartridge/github-connector

# Surgical precision - install only what you need
composer require jordanpartridge/github-repos-list
composer require jordanpartridge/github-search-repos  
composer require jordanpartridge/github-issues-create
composer require jordanpartridge/github-releases-list

Package Structure Proposal

🏗️ Core Foundation

• github-connector - Base Saloon connector + authentication
• github-http-client - HTTP foundation if not using Saloon

📦 Repository Operations

• github-repos-list - List user/org repositories
• github-repos-create - Create repositories
• github-repos-clone - Clone operations with Process integration
• github-repos-settings - Repository settings management

🔍 Search Operations

• github-search-repos - Repository search
• github-search-code - Code search
• github-search-users - User search
• github-search-issues - Issue/PR search

🐛 Issue Management

• github-issues-list - List issues
• github-issues-create - Create issues
• github-issues-update - Update/close issues
• github-issues-comments - Issue comment operations

🚀 Release Management

• github-releases-list - List releases
• github-releases-create - Create releases
• github-releases-assets - Upload/manage release assets

👥 User/Organization

• github-users-profile - User profile operations
• github-orgs-management - Organization operations

Benefits

🎯 For Developers

• Dependency Precision: Install exactly what you need
• Faster Installs: 5KB vs 500KB+ for simple use cases
• Reduced Attack Surface: Minimal code footprint
• Better Testing: Each package easily unit tested
• Granular Updates: Update repos without affecting issues

🏗️ For Architecture

• Composability: Mix and match capabilities
• Single Responsibility: Each package has one clear purpose
• Independent Versioning: Breaking changes isolated to specific functionality
• Framework Agnostic: Core can work anywhere, Laravel packages add Laravel-specific features

⚡ For Performance

• No Unused Code: Only load what you use
• Faster Autoloading: Smaller class maps
• Memory Efficiency: Lower memory footprint

Implementation Strategy

Phase 1: Core Foundation

1. Extract github-connector with basic Saloon setup
2. Create github-repos-list as proof of concept
3. Ensure backward compatibility with existing github-client

Phase 2: Popular Operations

1. github-search-repos - Most common search operation
2. github-issues-list - Popular issue operations
3. github-releases-list - Release management

Phase 3: Complete Ecosystem

1. All remaining operations as micro-packages
2. Convenience meta-packages (github-repos = list + create + clone)
3. Framework-specific integrations

Backward Compatibility

The current jordanpartridge/github-client could become a meta-package:

{
  "name": "jordanpartridge/github-client",
  "type": "metapackage",
  "require": {
    "jordanpartridge/github-connector": "^2.0",
    "jordanpartridge/github-repos-list": "^2.0",
    "jordanpartridge/github-repos-create": "^2.0",
    "jordanpartridge/github-search-repos": "^2.0",
    "jordanpartridge/github-issues-list": "^2.0"
  }
}

Real-World Use Cases

Conduit Component Discovery

// Only needs search - 5KB vs 500KB
composer require jordanpartridge/github-search-repos

$components = $searchService->searchByTopic('conduit-component');

Simple Repository Lister

// Only needs repo listing - 8KB total
composer require jordanpartridge/github-repos-list

$repos = $repoService->listUserRepos();

Full GitHub Integration

// Install everything (same as current)
composer require jordanpartridge/github-client

Questions for Discussion

1. Naming Convention: Prefer github-repos-list or github-repositories-list?
2. Granularity Level: Too granular or just right?
3. Meta-packages: Should we have convenience bundles like github-repos (list + create + clone)?
4. Framework Integration: Laravel-specific packages or framework-agnostic core?
5. Migration Path: How to best maintain backward compatibility?

Inspiration

This approach is inspired by:

• NPM ecosystem: Lodash → individual function packages
• Conduit: Microkernel with component architecture
• Saloon: Already provides great HTTP foundation
• Laravel ecosystem: Many successful micro-packages

Impact

This could set a new standard for PHP package architecture - moving from monolithic packages to composable ecosystems where developers get surgical precision in their dependencies.

Would love to hear thoughts on this architectural direction! 🚀

---

This proposal came from building Conduit where we needed minimal GitHub functionality for component discovery but didn't want to pull in a full GitHub client.