Skip to content

ORGANIZATION.md

Latest commit

 

History

History
174 lines (136 loc) · 4.6 KB

ORGANIZATION.md

File metadata and controls

174 lines (136 loc) · 4.6 KB

Project Organization Guide

This document explains the project structure and file organization.

Directory Structure

github-pr-webhook/
├── src/                    # Source code (TypeScript)
│   ├── WebhookService.ts   # Core webhook service with AI analysis
│   ├── app.ts              # Lambda handler entry point
│   └── devServer.ts        # Local development server
│
├── spec/                   # Unit tests
│   ├── support/           # Jasmine configuration
│   └── webhookService.spec.ts  # Test suite (19 tests, 79%+ coverage)
│
├── events/                 # Sample webhook payloads for testing
│   ├── payload.json       # Default test payload
│   └── *.json             # Various test scenarios
│
├── scripts/                # Utility scripts
│   ├── test.sh            # Legacy webhook test script
│   └── webhookService.js  # Old JavaScript version (reference)
│
├── config/                 # Configuration files (GITIGNORED)
│   ├── README.md          # Configuration documentation
│   └── gen-lang-client-*.json  # Service account credentials
│
├── dist/                   # Compiled JavaScript (GITIGNORED)
├── coverage/               # Code coverage reports (GITIGNORED)
├── node_modules/           # Dependencies (GITIGNORED)
└── .aws-sam/               # SAM build artifacts (GITIGNORED)

Root Files

Source Code Configuration

  • tsconfig.json - TypeScript compiler configuration
  • template.yaml - AWS SAM CloudFormation template
  • samconfig.toml - SAM deployment configuration
  • package.json - NPM dependencies and scripts

Documentation

  • README.md - Main project documentation
  • openapi.yaml - API specification

Configuration Templates

  • env.json.example - Environment variables template
  • .c8rc.json - Code coverage configuration
  • .gitignore - Git ignore rules

Environment (GITIGNORED)

  • env.json - Local environment variables (contains secrets)

Files Ignored by Git

The following files/directories are excluded from version control:

Build & Dependencies

  • node_modules/ - NPM packages
  • dist/ - Compiled JavaScript
  • .aws-sam/ - SAM build output

Secrets & Credentials

  • env.json - Environment variables
  • config/gen-lang-client-*.json - Service account keys
  • *.pem, *.key - Private keys

Coverage & Testing

  • coverage/ - HTML/LCOV coverage reports
  • .nyc_output/ - NYC coverage data
  • .c8/ - C8 coverage data

IDE & OS

  • .vscode/, .idea/ - IDE settings
  • .DS_Store, Thumbs.db - OS metadata
  • *.swp, *.swo - Vim swap files

Logs & Temp

  • *.log - Log files
  • *.tmp - Temporary files

Setup Instructions

1. Initial Setup

# Clone repository
git clone https://github.com/vivek-gaddipati/github-pr-webhook.git
cd github-pr-webhook

# Install dependencies
npm install

# Create environment file from template
cp env.json.example env.json
# Edit env.json with your actual credentials

2. Development

# Build TypeScript
npm run build

# Run tests
npm test

# Run tests with coverage
npm run coverage

# Start local dev server
npm run dev

3. Local Testing

# Test Lambda function locally
npm run test-local

# Start local API Gateway
npm run sam:start

4. Deployment

# Build SAM application
npm run sam:build

# Deploy to AWS
sam deploy

File Movement Summary

The project was reorganized to improve maintainability:

Moved Files

  • test.sh → scripts/test.sh
  • webhookService.js → scripts/webhookService.js
  • gen-lang-client-*.json → config/gen-lang-client-*.json

Created Files

  • env.json.example - Environment template
  • config/README.md - Config directory documentation
  • scripts/README.md - Scripts directory documentation
  • .c8rc.json - Code coverage configuration

Removed Files

  • .nycrc.json - Replaced with c8 configuration

Best Practices

Adding New Features

  1. Write code in src/
  2. Add tests in spec/
  3. Run tests with coverage: npm run coverage
  4. Build and test locally: npm run test-local
  5. Deploy: sam deploy

Adding Test Cases

  1. Edit spec/webhookService.spec.ts
  2. Run tests: npm test
  3. Check coverage: npm run coverage
  4. View detailed report: open coverage/index.html

Managing Secrets

  1. Never commit env.json or credential files
  2. Use env.json.example as template
  3. Store production secrets in AWS Secrets Manager
  4. Update .gitignore if adding new secret files

Questions?

See the main README.md for detailed usage instructions.