Launchpad

Repository onboarding and webhook handling service for the Rippler impact analysis system.

Architecture Diagram

The following diagram illustrates the internal architecture of the Launchpad service, showing how GitHub webhooks are processed, how PR analysis is orchestrated, and how the service integrates with other Rippler components.

Update the Architecture Diagram

To view and edit the architecture diagram:

Open /docs/architecture/services/launchpad.drawio in diagrams.net or VS Code with the Draw.io extension
The diagram shows the complete webhook handling and orchestration architecture including GitHub integration, repository management, PR analysis coordination, and downstream service communication
After making changes, export to HTML and copy to /website/static/architecture/services/launchpad.drawio.html

Overview

The Launchpad service is the entry point for repositories into Rippler. It handles repository onboarding, GitHub webhook processing, and orchestrates the impact analysis workflow.

Features

GitHub Repository Search: Search public GitHub repositories via GitHub REST API
Repository Onboarding: Register new repositories for monitoring with one-click setup
Webhook Handler: Process GitHub PR events and trigger automated impact analysis
PR Analysis: Automatically analyze pull requests using LLM for impact assessment
GitHub Notifications: Send PR analysis notifications back to GitHub
Metadata Management: Store and manage repository configuration
Validation: Comprehensive validation of repository data
REST API: Full CRUD operations for repository management
Database Persistence: PostgreSQL backend with Flyway migrations
Data Security: Encrypted storage for sensitive data (tokens, secrets)

Technology Stack

Java 17: Modern Java runtime
Spring Boot 3.2: Enterprise application framework
Spring Data JPA: Database access layer
PostgreSQL: Relational database
Flyway: Database migration management
Lombok: Reduce boilerplate code
Maven: Build and dependency management

API Endpoints

Repository Management

Search GitHub Repositories

GET /api/v1/search/repositories?q={query}

Search for public repositories on GitHub.

Example:

curl "http://localhost:8007/api/v1/search/repositories?q=spring+boot"

Onboard Repository

POST /api/v1/repositories

Request Body:

{
  "name": "my-repo",
  "owner": "my-org",
  "url": "https://github.com/my-org/my-repo",
  "access_token": "ghp_xxxxx",
  "webhook_secret": "secret123"
}

Get Repository

GET /api/v1/repositories/{id}

List Repositories

GET /api/v1/repositories

Update Repository

PUT /api/v1/repositories/{id}

Delete Repository

DELETE /api/v1/repositories/{id}

Webhook Handling

GitHub Webhook Endpoint

POST /api/v1/webhooks/github

Receives GitHub webhook events for pull request activities.

Supported Events:

pull_request.opened
pull_request.synchronize
pull_request.reopened

Notifications

Send GitHub Notification

POST /api/v1/notifications/github

Send impact analysis results as a comment on the PR.

Request Body:

{
  "repository": "owner/repo",
  "pr_number": 123,
  "message": "Impact analysis results...",
  "status": "success"
}

Health Check

GET /actuator/health

Returns service health status.

Configuration

Environment Variables

Variable	Description	Default
`SERVER_PORT`	Service port	8007
`DB_HOST`	Database hostname	localhost
`DB_PORT`	Database port	5432
`DB_NAME`	Database name	rippler_launchpad
`DB_USERNAME`	Database username	postgres
`DB_PASSWORD`	Database password	postgres
`GITHUB_TOKEN`	GitHub API token	-
`ENCRYPTION_KEY`	Data encryption key	-

Application Properties

# Server Configuration
server.port=8007

# Database Configuration
spring.datasource.url=jdbc:postgresql://${DB_HOST}:${DB_PORT}/${DB_NAME}
spring.datasource.username=${DB_USERNAME}
spring.datasource.password=${DB_PASSWORD}

# JPA Configuration
spring.jpa.hibernate.ddl-auto=validate
spring.jpa.show-sql=false

# Flyway Configuration
spring.flyway.enabled=true
spring.flyway.locations=classpath:db/migration

Installation

Prerequisites

Java 17 or higher
Maven 3.6+
PostgreSQL 13+

Local Development

# Start PostgreSQL
docker run -d \
  --name launchpad-postgres \
  -e POSTGRES_DB=rippler_launchpad \
  -e POSTGRES_USER=postgres \
  -e POSTGRES_PASSWORD=postgres \
  -p 5432:5432 \
  postgres:15

# Build the application
mvn clean install

# Run the application
mvn spring-boot:run

Using Docker

# Build image
docker build -t rippler/launchpad .

# Run container
docker run -d \
  -p 8007:8007 \
  -e DB_HOST=postgres \
  -e GITHUB_TOKEN=your-token \
  rippler/launchpad

Using Docker Compose

# From project root
docker-compose up launchpad postgres

Usage

Onboarding a Repository

Search for a repository:

curl "http://localhost:8007/api/v1/search/repositories?q=your-repo"

Onboard the repository:

curl -X POST http://localhost:8007/api/v1/repositories \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-repo",
    "owner": "my-org",
    "url": "https://github.com/my-org/my-repo",
    "access_token": "ghp_xxxxx"
  }'

Configure GitHub webhook:
- Go to repository settings on GitHub
- Add webhook with URL: http://your-server:8007/api/v1/webhooks/github
- Select event: Pull requests
- Set content type: application/json

Processing PR Events

When a PR is opened or updated:

GitHub sends webhook event to Launchpad
Launchpad validates the event
Extracts PR data (diff, files changed, etc.)
Sends data to Impact Analyzer
Impact Analyzer coordinates with other services
Results are sent back to GitHub as PR comments

Architecture

Workflow

graph LR
    GH[GitHub] -->|Webhook| LP[Launchpad]
    LP -->|PR Data| IA[Impact Analyzer]
    IA -->|Query| DG[Dependency Graph]
    IA -->|Analyze| LLM[LLM Service]
    IA -->|Results| LP
    LP -->|Comment| GH

Database Schema

The service uses PostgreSQL with the following main tables:

repositories: Store repository metadata
webhook_events: Log incoming webhook events
analysis_results: Cache analysis results

Development

Running Tests

# Run unit tests
mvn test

# Run integration tests
mvn verify

Database Migrations

Flyway manages database schema:

# Clean database (dev only)
mvn flyway:clean

# Run migrations
mvn flyway:migrate

# Check migration status
mvn flyway:info

Troubleshooting

Webhook Not Received

Verify webhook URL is accessible from GitHub
Check firewall/network settings
Review webhook delivery logs on GitHub
Check service logs for errors

Database Connection Failed

Verify PostgreSQL is running
Check database credentials
Ensure database exists
Review connection string

Repository

GitHub: launchpad

Architecture Diagram​

Overview​

Features​

Technology Stack​

API Endpoints​

Repository Management​

Search GitHub Repositories​

Onboard Repository​

Get Repository​

List Repositories​

Update Repository​

Delete Repository​

Webhook Handling​

GitHub Webhook Endpoint​

Notifications​

Send GitHub Notification​

Health Check​

Configuration​

Environment Variables​

Application Properties​

Installation​

Prerequisites​

Local Development​

Using Docker​

Using Docker Compose​

Usage​

Onboarding a Repository​

Processing PR Events​

Architecture​

Workflow​

Database Schema​

Development​

Running Tests​

Database Migrations​

Troubleshooting​

Webhook Not Received​

Database Connection Failed​

Related Documentation​

Repository​