ContractRipple - API Change Impact Mapper

# Overview

ContractRipple is a full-stack developer tool designed to help developers understand the impact of API contract changes before those changes break existing integrations. Users can create projects, manage API contracts, upload baseline and candidate OpenAPI specifications in JSON or YAML format, and review classified differences with explanations and JSON Pointer evidence. The platform extends contract comparison with TypeScript and JavaScript source analysis, identifying potential API call sites and connecting changed operations to relevant source files. Developers can explore evidence-backed impact relationships, review regression-test suggestions, access saved analysis history, and export reports in JSON and Markdown formats. ContractRipple features a modular architecture built with Next.js, React, TypeScript, Tailwind CSS, Express.js, Prisma, and PostgreSQL, with authenticated workspaces and server-side resource ownership protections.

# Features

• ▸OpenAPI contract comparison for reviewing baseline and candidate API specifications in JSON or YAML format.
• ▸Automated detection and classification of API changes, including added, modified, and removed operations and schema elements supported by the comparison engine.
• ▸Risk classification for potentially breaking and non-breaking changes to help developers prioritize API compatibility reviews.
• ▸Evidence-backed findings with human-readable explanations, before-and-after details, and JSON Pointer locations.
• ▸TypeScript and JavaScript source analysis using the TypeScript Compiler API to identify supported API call patterns.
• ▸Secure ZIP source-upload pipeline designed to analyze supported frontend source files without executing uploaded code.
• ▸GitHub repository analysis through a server-side integration that keeps repository credentials out of the browser.
• ▸Impact graph connecting changed API operations to matching frontend source files using persisted source-analysis evidence.
• ▸Accessible impact relationship table providing an alternative to graph-based navigation.
• ▸Source evidence containing file paths, line numbers, columns, code snippets, and matching details where available.
• ▸Saved analysis history with cursor-based pagination for revisiting previously completed comparisons.
• ▸Downloadable JSON and Markdown reports generated from persisted findings and source-analysis data.
• ▸Regression review suggestions derived from classified findings to help developers plan targeted validation and testing.
• ▸Authenticated user workspaces for managing projects, contracts, versions, and analysis records.
• ▸Email and password authentication with scrypt password hashing and server-side session management.
• ▸Security protections including HttpOnly session cookies, CSRF validation, origin checks, rate limiting, security headers, and resource ownership enforcement.
• ▸Modular monorepo architecture separating shared validation schemas, OpenAPI comparison logic, source analysis, impact graph generation, and backend services.
• ▸Automated testing and validation covering core application behavior, API services, security checks, and other implemented functionality.

# Challenges Faced

The primary challenge was designing a reliable workflow that connects API contract changes to the frontend code that may depend on them. Comparing OpenAPI specifications requires normalizing contract data, detecting meaningful differences, and classifying potential compatibility risks without overstating their consequences. Another significant challenge was analyzing TypeScript and JavaScript source code to identify supported API call patterns and match them to normalized OpenAPI operations. Building an evidence-backed impact graph required ensuring that relationships were derived from actual source-analysis results rather than inferred or fabricated connections. Additional challenges included secure source uploads, persistent analysis history, report generation, authenticated resource ownership, CSRF protection, and maintaining clear boundaries between the frontend, backend, database, and reusable analysis packages.