Define GitHub organization architecture for 60+ repository microkernel ecosystem - #397

Defines complete repository architecture for ObjectStack's transition from monorepo to distributed microkernel ecosystem. Addresses the question: "如何在一个GitHub组织中创建哪些项目" (How to organize projects in a GitHub organization).

Architecture

7 repository categories, 60+ total repositories:

Protocol Layer (1)          Microkernel Layer (6)         Plugin Layer (50+)
└─ spec                     ├─ core, objectql             ├─ Drivers (12+): postgres, mysql, mongodb, redis...
                            ├─ runtime, client            ├─ Connectors (10+): salesforce, slack, stripe...
                            └─ cli, types                 ├─ Plugins (15+): encryption, cache, multitenancy...
                                                          ├─ Server Adapters (8+): hono, express, nextjs...
                                                          ├─ Templates (10+): crm, helpdesk, hr-system...
                                                          └─ Tools (5+): devtools, vscode-extension...

Naming conventions:

• Core: [name] → @objectstack/[name]
• Drivers: driver-[database] → @objectstack/driver-[database]
• Connectors: connector-[service] → @objectstack/connector-[service]
• Plugins: plugin-[feature] → @objectstack/plugin-[feature]
• Templates: template-[domain] → @objectstack/template-[domain]

Migration Strategy

4-phase extraction from monorepo:

Repository Templates

Each category has standardized structure with CI/CD, testing, docs requirements. Example driver template:

driver-postgres/
├── src/
│   ├── driver.ts              # Implements DriverInterface from @objectstack/spec
│   ├── connection.ts          # Connection pooling
│   ├── query-builder.ts       # SQL generation
│   └── __tests__/
│       ├── unit/
│       └── integration/       # With docker-compose.yml for test DB
├── .github/workflows/
│   ├── ci.yml                 # Lint, typecheck, test, build
│   └── integration-test.yml   # Database integration tests
└── docs/
    ├── CONFIGURATION.md
    └── MIGRATION.md

Governance & Quality

Tier-based ownership:

• Tier 1 (spec, core): Core team only, RFC + voting required
• Tier 2 (objectql, runtime, client, cli): Core + trusted contributors
• Tier 3 (drivers, server plugins): Core + community
• Tier 4 (connectors, templates, tools): Community-led

Quality standards:

• Test coverage: 60-90% (tier-dependent)
• TypeScript strict mode required for core/drivers/plugins
• All repos: CodeQL scanning, Dependabot, signed commits (Tier 1-2)

Deliverables

• ARCHITECTURE_QUICK_REFERENCE.md - Visual overview, 5-min read
• GITHUB_ORGANIZATION_STRUCTURE.md / CN - Complete specification, 849 lines
• PROJECT_STRUCTURE_IMPLEMENTATION_SUMMARY.md - Implementation roadmap with benchmarking against Kubernetes, Salesforce, VS Code, Prisma

Rationale

Why multi-repo over monorepo:

• Independent versioning (plugins evolve at different rates)
• Lower contribution barrier (fork single repo, not entire monorepo)
• Isolated CI/CD (faster feedback, parallel builds)
• Clear ownership boundaries (Tier 1-4 governance model)
• Scalable community growth (40+ community-maintained repos planned)

Benchmarked against:

• Kubernetes: Core vs kubernetes-sigs/* separation, CRD pattern
• Salesforce: AppExchange marketplace model, metadata-driven architecture
• VS Code: Extension marketplace, plugin API design
• Prisma: Schema-first approach, driver abstraction pattern

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.