GitHub Octokit TypeScript Monorepo

Conventions and guidelines for building TypeScript monorepos that integrate GitHub APIs, AI utilities, and database layers using npm workspaces.

Purpose

This skill provides architectural patterns and coding standards for monorepo projects that combine:

Monorepo Structure

Package Organization

Test Organization

Build Order

Core Shared Packages

| Package | Path | Purpose |

|---------|------|---------|

| @dfb/ai | packages/@dfb/ai | Core AI utilities and OpenAI integration |

| @dfb/db | packages/@dfb/db | TypeORM-based database models and logic |

| @dfb/finddb | packages/@dfb/finddb | Utility for finding and working with DB files |

| @dfb/octokit | packages/@dfb/octokit | GitHub API and workflow integration |

Database Conventions

Naming & Schema

Vector Storage Pattern

Store arrays (especially vectors) as JSON strings in text columns for non-vector databases like SQLite:

```typescript

@Entity('my_table')

export class MyEntity {

@PrimaryColumn()

id!: string;

@Column({ type: 'text', nullable: true })

my_vector?: string; // JSON string in SQLite, parse to number[] for Cosmos

}

```

**Migration strategy**: Convert JSON strings to `number[]` when sending to vector-aware stores (Cosmos DB).

Coding Standards

Async Patterns

Import Order

Code Quality

New Package Template

When creating a new package, follow this structure:

```

packages/new-package/

src/

index.ts

test/

index.test.ts

package.json

tsconfig.json

eslint.config.js (if needed)

```

Example Entity Definition

```typescript

import { Entity, PrimaryColumn, Column } from 'typeorm';

@Entity('my_table')

export class MyEntity {

@PrimaryColumn()

id!: string;

@Column({ type: 'text', nullable: true })

my_vector?: string; // store as JSON string in SQLite, parse to number[] for Cosmos

}

```

Stack & Tooling

**Preferred technologies:**

Key Scripts

Document all scripts added to `scripts/` or root `package.json`:

Database Compatibility Notes

Best Practices

1. **Workspace Management**: Use npm workspaces for cross-package dependencies and script execution

2. **Consistency**: Follow naming conventions strictly (snake_case for DB, camelCase for TypeScript)

3. **Documentation**: Document all utilities and scripts with purpose and usage

4. **Type Safety**: Leverage TypeScript strict mode; avoid `any` types

5. **Testing**: Write tests for all packages; place strategically based on package size

GraphQL Integration

Use GraphQL for API layers where applicable:

Example Workflow

1. Create new package in `packages/` with standard structure

2. Add to npm workspaces in root `package.json`

3. Configure `tsconfig.json` with appropriate extends

4. Set up tests (inline or `test/` directory)

5. Run `npm install` at root to link workspace dependencies

6. Use `build-all.sh` for coordinated builds

Constraints