Contributing Overview
Thank you for your interest in contributing to Codabra! This guide covers the monorepo structure, development setup, and how to add new capabilities.
Monorepo structure
codabra/
├── packages/
│ ├── core/ ← Domain model and generation use cases
│ │ └── src/
│ │ ├── domain/ ← Canonical application definition
│ │ ├── application/ ← Compilation and generation pipeline
│ │ ├── ports/ ← TargetRenderer output port
│ │ ├── features/ ← Reusable feature expansion
│ │ ├── orm/ ← Next.js ORM adapters
│ │ ├── loader/ ← Config file loaders
│ │ ├── validator/ ← Config validators
│ │ ├── types/ ← Shared TypeScript types
│ │ └── schemas/ ← JSON Schemas for VS Code autocomplete
│ ├── providers/ ← Next.js, Node, PHP, Go and Symfony renderers
│ └── cli/ ← `codabra` and `create-codabra` binaries
└── apps/
├── web/ ← Example Next.js app (generated output)
└── docs/ ← This documentation siteDevelopment setup
Prerequisites: Node.js 20.9+, pnpm 9+.
bash
# Clone and install
git clone https://github.com/your-org/codabra
cd codabra
pnpm install
# Build all packages in dependency order
pnpm build
# Type-check all packages
pnpm typecheck
# Unit and renderer contract tests
pnpm test
# Formatting and lint
pnpm format:check
pnpm lint
# Watch mode (rebuilds on change)
pnpm --filter @codabra/core devRunning the local CLI
bash
# After building, use the local CLI:
node packages/cli/bin/codabra.js generate
node packages/cli/bin/create-codabra.js my-new-projectAdding a new feature
- Implement the feature in
packages/core/src/ - Export it from
packages/core/src/index.ts - Write a test
- Update the relevant page in
apps/docs/
Key design principles
- OrmAdapter — new ORMs plug in via the Strategy Pattern (
packages/core/src/orm/) - ApplicationDefinition — shared semantics never contain framework syntax
- TargetRenderer — pure application model → relative file plan
- Provider — lifecycle and filesystem adapter around a renderer
- No renderer I/O — path validation runs before the CLI writes files