ContractGuard AI – Intelligent API Orchestrator

Inspiration

Managing APIs across multiple parallel development branches is one of the most error-prone parts of modern software development. We experienced firsthand how a single renamed field or removed endpoint can silently break a mobile app at 3 AM, trigger emergency war rooms, and cost teams hours of debugging. The disconnect between backend teams making changes and frontend teams depending on stable contracts felt like an unsolved problem hiding in plain sight. We were inspired by the idea that AI could act as a vigilant intermediary — watching every branch, understanding every change, and warning teams before damage reaches production.

What it does

ContractGuard is an AI-assisted API contract conflict detection platform built for multi-branch development teams. It connects to GitHub repositories, automatically discovers all branches, and scans source code files to extract API endpoint signatures including paths, methods, fields, types, and required status. It then compares each feature branch against the main branch at three levels — endpoint level, field level, and behavior level — and surfaces every breaking or risky difference ranked by severity from Critical down to Easy. Teams get guided conflict resolution workflows where they can keep the main version, accept the branch change, make a field optional, or consolidate multiple branch changes into a smart merge. An integrated Ollama AI engine explains each conflict in plain English, suggests the safest resolution, and generates a full migration guide. The final output is a downloadable merged YAML contract and migration guide that developers can apply manually — nothing is ever pushed to GitHub automatically.

How we built it

The frontend is a React 19 single-page application built with Vite and TypeScript, styled entirely with Tailwind CSS, with Zustand managing global state and Axios handling all API communication. The backend is an Express REST API written in TypeScript running on Node.js, using Prisma ORM to manage a PostgreSQL database that stores repositories, branches, extracted endpoints, conflict sessions, and resolutions. GitHub integration uses the official Octokit REST SDK to fetch repository metadata, branch lists, and raw file contents using a personal access token. The deep extraction engine scans TypeScript, JavaScript, Python, Java, and Go source files using pattern matching and backtracking — following function references across imported files up to three levels deep to extract complete request and response field definitions including Joi, Zod, and express-validator schemas. Conflict detection runs a three-level comparison algorithm covering endpoint existence, field presence and type matching, and behavioral changes like required-to-optional transitions. Severity is calculated using five factors: conflict type, field required status, affected branch count, endpoint criticality, and field name semantics. AI features are powered by Ollama running qwen2.5-coder:32b locally, with a custom fine-tuned phi-4 LoRA adapter as an alternative. The entire system is containerized using Docker for PostgreSQL and orchestrated with a monorepo root package.json using concurrently.

Challenges we ran into

The hardest challenge was building the deep extraction engine that could follow function references across files. Most API route definitions in real codebases delegate to controller functions in separate files, which themselves call validation schemas in yet another file. Making the extractor follow these import chains reliably across TypeScript, JavaScript, and Python without infinite loops or false positives required significant iteration. A second major challenge was defining severity rules that felt accurate and meaningful rather than arbitrary — balancing conflict type, field requirements, and cross-branch impact into a single trustworthy score took multiple redesigns. Connecting Server-Sent Events for real-time scan progress while keeping the Express server stable under concurrent scans was also unexpectedly complex. Finally, getting Ollama to return structured JSON consistently from a large model like qwen2.5-coder:32b required careful prompt engineering and retry logic since the model occasionally wrapped responses in markdown code blocks.

Accomplishments that we're proud of

We are proud of building a genuinely useful tool that solves a real pain point that most development teams silently suffer through. The three-level conflict comparison algorithm that catches not just missing endpoints but field renames, type changes, and required-to-optional shifts feels meaningfully more powerful than simple diff tools. The cross-branch consolidation engine that detects when two branches conflict with each other — not just with main — is something we have not seen in existing tools. The live scan progress UI that shows the AI backtracking through function references in real time makes the system feel transparent and trustworthy rather than a black box. Running the entire AI stack locally with Ollama means the tool works without sending any code to external APIs, which matters deeply for teams working on proprietary systems.

What we learned

We learned that real-world API extraction is far messier than parsing a clean OpenAPI spec — developers write routes in dozens of different patterns and the extractor has to be resilient to all of them. We learned that severity classification is a product decision as much as a technical one — the same conflict can be Critical in one codebase and Low in another depending on context. We learned that streaming real-time progress over SSE dramatically improves perceived performance and user trust even when the underlying work takes the same amount of time. We learned how to run and prompt large code models locally with Ollama and how to fine-tune a phi-4 model with LoRA adapters using the HuggingFace PEFT library. Most importantly we learned that the hardest part of building developer tooling is not the code — it is understanding exactly where developers feel pain and designing workflows that fit naturally into how they already work.

What's next for ContractGuard AI – Intelligent API Orchestrator

The immediate next step is completing the file rewrite service so that resolved conflicts produce a fully rewritten source file shown as a syntax-highlighted diff in the UI, ready for developers to download and apply. We plan to add webhook support so ContractGuard automatically re-scans branches on every push without manual triggering. Support for Next.js App Router file-based routing, NestJS decorators, and FastAPI type hints is planned to broaden framework coverage. We want to add a GitHub Pull Request integration that posts a ContractGuard conflict summary as a PR comment before merge. A team collaboration layer with user accounts, shared sessions, and comment threads on individual conflicts would make the tool suitable for larger engineering organizations. Long term we want ContractGuard to support automatic resolution suggestions that can open a pull request with the recommended fix applied — turning conflict detection into conflict resolution with a single click.