---
roadcrew_template_name: "techContext.template.md"
roadcrew_template_type: "memory-bank"
roadcrew_template_version: "1.0"
roadcrew_last_updated: "2025-11-03"
roadcrew_min_version: "1.6.0"
roadcrew_license: "See LICENSE file in .roadcrew folder"
roadcrew_copyright: "Copyright (c) 2025 North Star Holdings, LLC"
spdx_license_identifier: "LicenseRef-RoadcrewLicense-1.0"
cline_memory_bank: "techContext"
---

# Technical Context

**Technologies used, development setup, technical constraints, dependencies, and tool usage patterns**

Last Updated: November 3, 2025  
Node Version: >=18.0.0  
Package Manager: npm

---

## Technology Stack

### Frontend

- **Framework:** None (command-line system, not web app)
- **State Management:** N/A
- **Styling:** N/A
- **Build Tool:** TypeScript compiler (tsc)
- **UI Components:** N/A

---

### Backend

- **Runtime:** Node.js >=18.0.0
- **Framework:** Cursor AI commands (no server framework)
- **Database:** N/A (uses customer's databases)
- **ORM/Query Builder:** N/A
- **API Style:** Command-based (/.cursor/commands/)

---

### Infrastructure

- **Hosting:** Git submodule (customers install via git)
- **CI/CD:** GitHub Actions (.github/workflows/)
- **Container:** Docker (optional, for local development)
- **Monitoring:** N/A
- **Logging:** Console output (Node.js built-in)

---

### Supporting Tools

- **Version Control:** Git + GitHub
- **Package Registry:** npm registry
- **Testing Framework:** Jest with ts-jest
- **Linting:** ESLint 9.37.0 with TypeScript support
- **Code Formatting:** Prettier (enforced via ESLint)

---

## Development Setup

### Prerequisites

- Node.js 18.0.0 or higher
- npm (comes with Node.js)
- Git (for submodule operations)
- GitHub account (for API access via GITHUB_TOKEN)

### Project Structure

```
roadcrew-internal/
├─ commands/                  # Cursor commands (8 folders, 40+ commands)
│  ├─ 01-analysis/
│  ├─ 02-planning/
│  ├─ 03-release/
│  ├─ 04-implementation/
│  ├─ 05-code-analysis/
│  ├─ 06-testing/
│  ├─ 07-publishing/
│  └─ 08-validation/
├─ scripts/                   # Core automation scripts (TypeScript)
│  ├─ core/                   # Main implementations
│  └─ utils/                  # Shared utilities
├─ templates/                 # Customer-facing templates (published)
│  └─ roadcrew/
│      ├─ memory-bank/        # Cline Memory Bank templates
│      ├─ rules/              # Cursor rules templates
│      └─ (other templates)
├─ .cursor/                   # Internal Cursor rules
│  ├─ rules/                  # Auto-applied rules (00-06)
│  └─ commands/               # Internal commands
├─ .roadcrew/                 # This repo becomes .roadcrew/ submodule for customers
├─ context/                   # Product vision, specs, PRDs, BRDs
│  ├─ vision.md               # Long-term strategy
│  ├─ prds/                   # Product requirements
│  ├─ specs/                  # Technical specifications
│  ├─ brds/                   # Business requirements
│  └─ epics/                  # Epic tracking
├─ milestones/                # Release tracking
├─ memory-bank/               # Living documentation (Cline structure)
│  ├─ projectbrief.md
│  ├─ productContext.md
│  ├─ systemPatterns.md
│  ├─ techContext.md          # ← This file
│  ├─ activeContext.md
│  └─ progress.md
├─ config/                    # Configuration files
│  └─ tech-stack.md          # (being retired, see memory-bank/techContext.md)
├─ dist/                      # Compiled JavaScript (published to customers)
├─ package.json               # Dependencies
├─ tsconfig.json              # TypeScript configuration
├─ jest.config.js             # Jest testing configuration
└─ .eslintrc.js              # ESLint configuration
```

### Installation Steps

1. Clone the repository: `git clone https://github.com/tailwind-ai/roadcrew-internal`
2. Install dependencies: `npm install`
3. Set GITHUB_TOKEN: `export GITHUB_TOKEN=your_github_token`
4. Build TypeScript: `npm run build`
5. Run tests: `npm test`

### Quick Start

```bash
# Install dependencies
npm install

# Build TypeScript to dist/
npm run build

# Run all tests
npm test

# Run tests in watch mode (for development)
npm run test:watch

# Run specific command analysis
npm run analyze-repo

# Check code quality
npm run lint
npm run type-check
```

---

## Environment Configuration

### Required Environment Variables

```env
GITHUB_TOKEN=ghp_xxxxxxxxxxxxx    # GitHub Personal Access Token (full repo scope)
```

### Optional Environment Variables

```env
NODE_ENV=development              # Set to production for releases
DEBUG=roadcrew:*                   # Enable debug output
```

### Configuration Files

- `package.json` - Dependencies, scripts, project metadata
- `tsconfig.json` - TypeScript compiler options (strict mode enabled)
- `jest.config.js` - Jest testing configuration
- `.eslintrc.js` - ESLint linting rules
- `.github/workflows/*.yml` - CI/CD automation

---

## Technical Constraints

### Performance Requirements

- Command execution should complete in <5 seconds
- Template processing should take <2 seconds per file
- Build time target: <30 seconds (from 180-200s baseline)
- API rate limits: GitHub API (5,000 requests/hour for authenticated users)

### Compatibility Requirements

- Node.js 18.0.0 or higher
- Works on macOS, Linux, Windows (via WSL or native)
- GitHub API v3 compatible

### Security & Compliance

- All secrets managed via environment variables (GITHUB_TOKEN)
- No hardcoded credentials in source code
- GitHub token rotated regularly
- GDPR-compliant (customer data not stored)

### Scalability Requirements

- Support publishing 640+ files to customer repos
- Handle rate limiting for 50+ concurrent GitHub operations
- Support multi-repo scenarios (future: Enterprise tier)

---

## Dependencies

### Critical Dependencies

#### @octokit/rest (22.0.0)

- **Version:** 22.0.0
- **Purpose:** GitHub API client library
- **Why this version:** Latest stable with full API v3 support
- **Key features used:**
  - Issues creation/update
  - Pull request management
  - Repository operations

#### typescript (5.9.3)

- **Version:** 5.9.3
- **Purpose:** TypeScript compiler and type system
- **Why this version:** Latest stable with full ES2025 support
- **Key features used:**
  - Strict type checking
  - Source maps for debugging
  - Module resolution

#### eslint (9.37.0)

- **Version:** 9.37.0
- **Purpose:** Code linting and quality analysis
- **Why this version:** Latest version with TypeScript plugin support
- **Key features used:**
  - TypeScript linting via @typescript-eslint
  - Custom rule validation
  - Automatic fixes

---

### Development Dependencies

- **jest** (29.7.0): Testing framework with ts-jest support
- **ts-jest** (29.1.1): TypeScript support for Jest
- **@types/node** (24.7.2): TypeScript types for Node.js APIs
- **@typescript-eslint/parser** (8.46.1): TypeScript parsing for ESLint
- **prettier** (3.0.0): Code formatting (via ESLint)

### Peer Dependencies

- **@octokit/rest**: No peer dependencies
- **typescript**: No peer dependencies (dev only)

---

## Tool Usage Patterns

### Testing

#### Unit Tests

- **Framework:** Jest with ts-jest
- **Location:** `tests/` directory (mirrors `scripts/` structure)
- **Run command:** `npm test`
- **Coverage target:** 80%+

#### Integration Tests

- **Framework:** Jest + @octokit/rest (uses GitHub API)
- **Location:** `tests/integration/`
- **Run command:** `npm run test:integration`

#### End-to-End Tests

- **Framework:** Jest + real GitHub API
- **Location:** `tests/e2e/`
- **Run command:** `npm run test:e2e` (requires GITHUB_TOKEN)

### Database Management

- **Note:** Roadcrew doesn't manage databases—customers do
- **Schema validation:** Via generated TypeScript types
- **Migration tracking:** Documented in specs/ folder

### Build & Deployment

- **Build:** `npm run build` (TypeScript to dist/)
- **Development server:** N/A (command-based system)
- **Production build:** `npm run build` (same as dev)
- **Deploy:** Push to dev branch → merge PR → GitHub Actions publishes to roadcrew repo

### Code Quality

- **Lint:** `npm run lint` (ESLint)
- **Format:** `npm run lint:fix` (Prettier via ESLint)
- **Type check:** `npm run type-check` (TypeScript without build)

### Development Commands

- **Analyze repo:** `npm run analyze-repo` (generates tech-stack.md)
- **Audit complexity:** `npm run audit-complexity` (code metrics)
- **Audit security:** `npm run audit-security` (dependency vulnerabilities)
- **Audit performance:** `npm run audit-performance` (benchmarking)
- **Review code:** `npm run review-code` (comprehensive analysis)
- **Validate release:** `npm run validate-release` (current-release.md structure)

---

## Ports & URLs

### Development

- **Node.js REPL:** N/A (no server)
- **GitHub API:** https://api.github.com
- **GitHub Web:** https://github.com

### Staging

- **Dev branch:** https://github.com/tailwind-ai/roadcrew-internal (dev)
- **PR previews:** GitHub PR checks

### Production

- **Distribution repo:** https://github.com/tailwind-ai/roadcrew (main)
- **npm package:** N/A (distributed via git submodule)

---

## Debugging & Troubleshooting

### Common Issues

#### Issue 1: GITHUB_TOKEN not found

**Symptom:** `Error: GITHUB_TOKEN environment variable is required`

**Solution:**
```bash
export GITHUB_TOKEN=ghp_xxxxxxxxxxxxx
echo $GITHUB_TOKEN  # Verify it's set
```

---

#### Issue 2: Rate limit exceeded

**Symptom:** `403 Forbidden: API rate limit exceeded`

**Solution:**
```bash
# Check remaining rate limit
curl -H "Authorization: token $GITHUB_TOKEN" https://api.github.com/rate_limit

# Wait 1 hour for limit reset, or request higher limit
```

---

### Debug Mode

Set `DEBUG=roadcrew:*` to enable debug logging:
```bash
DEBUG=roadcrew:* npm run build
DEBUG=roadcrew:* npm test
```

### Logging

- **Log level:** INFO (default) or DEBUG (via DEBUG env var)
- **Log output:** Console (stdout/stderr)
- **How to enable debug logs:** `DEBUG=roadcrew:* command`

---

## Performance Metrics

### Key Metrics to Monitor

- **Build time:** 0-30s (target), was 180-200s baseline
- **Test run time:** <5s for unit tests
- **GitHub API latency:** 100-500ms per request
- **Template processing:** <2s per file

### Profiling Tools

- **Node.js profiler:** `node --prof scripts/core/publish-api.ts`
- **GitHub rate limit monitor:** `curl -H "Authorization: token $GITHUB_TOKEN" https://api.github.com/rate_limit`

---

## Related Documents

- **Project Brief:** See `memory-bank/projectbrief.md` for scope and requirements
- **Product Context:** See `memory-bank/productContext.md` for problems and UX goals
- **System Patterns:** See `memory-bank/systemPatterns.md` for architecture and design patterns
- **Active Context:** See `memory-bank/activeContext.md` for current work
- **Progress:** See `memory-bank/progress.md` for status and milestones

---

**Note:** This document defines WHAT technologies are used and HOW to set them up. Keep this updated as versions and tools change. For detailed technical specifications, see `memory-bank/requirements/specs/`.