DriftGuard

Autonomous API Drift Detection & Documentation

DriftGuard is a production-aware API intelligence platform that analyzes live HTTP traffic, source-code changes, and Git history to detect documentation drift. It uses an AI-powered LangGraph pipeline to analyze API behavior, generate updated technical documentation, and automatically open GitHub Pull Requests for developer review.

Live API Behavior + Source Code + Git History
                     ↓
              AI Analysis (LangGraph)
                     ↓
               Drift Detection
                     ↓
          Documentation Generation
                     ↓
      Automated GitHub Pull Request

📸 Dashboard Preview

🎯 Overview

The Problem: Documentation Drift

In modern engineering teams, APIs evolve rapidly. Developers introduce new routes, modify payload schemas, adjust status codes, and patch business logic. Traditional API documentation struggles to keep pace:

Static Docs Stagnate: Manually written READMEs, Wiki pages, and OpenAPI specs quickly fall out of sync with real implementations.
Code vs. Reality Disconnect: Code annotations reflect intended design, while APM dashboards show raw telemetry without explaining functionality.
Integration Friction: API consumers rely on outdated documentation, causing unexpected payload errors, breaking changes, and support overhead.

The DriftGuard Approach

DriftGuard unifies runtime telemetry, source code analysis, and Git version control into a continuous intelligence loop. By correlating observed HTTP traffic with codebase changes, DriftGuard identifies discrepancies (drift), synthesizes accurate technical documentation, and opens a GitHub Pull Request for human review.

✨ Key Features

📡 Live API Traffic Intelligence

Intercepts incoming HTTP requests and responses non-intrusively using FastAPI middleware.
Records HTTP methods, endpoints, status codes, query parameters, request/response payloads, latency, payload sizes, client IP, and user agents.
Delivers per-user data isolation and non-blocking asynchronous logging to PostgreSQL.

🔍 Dynamic Endpoint Discovery & Parameter Normalization

Automatically identifies API routes from observed traffic and normalizes dynamic segments (e.g. /api/v1/users/usr_1001 → /api/v1/users/{id}).
Aggregates call counts, error rates, average latency, and drift status across your entire service.

🧠 AI-Powered Behavioral Analysis

Evaluates real request/response payloads and edge cases to construct accurate behavioral summaries of production endpoints.
Detects error spikes, latency anomalies, and schema discrepancies.

🔄 Git-Aware Drift Detection

Inspects repository file trees, source files, dependencies, and commit diffs via the GitHub REST API.
Compares recent code changes against existing documentation to verify whether documentation accurately reflects production behavior.

📝 Autonomous Documentation Generation

Produces clean, publication-ready API references, comprehensive READMEs, usage guides, and full OpenAPI 3.0 JSON specifications.
Captures real-world edge cases and request/response examples directly from execution telemetry.

🚀 Automated GitHub Pull Requests

Creates an isolated branch (driftguard/update-docs), commits updated documentation files (README.md, DOCUMENTATION.md, or custom paths), and opens a Pull Request with an AI-generated drift summary and review checklist.

🔌 Multi-LLM Provider Architecture

Prioritized LLM fallback system:
1. OpenRouter (Claude 3.5 Sonnet / GPT-4o)
2. Groq (Llama 3.3 70B Versatile — high throughput, low latency)
3. Google Gemini (Gemini 2.5 Flash / Gemini 2.0 Flash)

🖼️ Product Screenshots

Overview Console

The central operations dashboard provides real-time API health metrics, traffic trends, endpoint status, and recent drift alerts.

Live Documentation

Interactive endpoint documentation generated from real observed traffic, including path parameters, response schemas, and curl examples.

API Intelligence

Deep behavioral analysis, detected drift reasons, and error pattern breakdowns computed by the LangGraph pipeline.

Traffic Logs & Observability

Real-time stream of intercepted HTTP requests with status filtering, latency tracking, and full payload inspection.

GitHub Automation & PR Workflow

Connect any repository to scan source code, compare commit diffs, generate updated documentation, and open GitHub Pull Requests.

🏗️ How It Works

DriftGuard captures runtime HTTP telemetry, correlates it with source code extracted from Git repositories, and runs structured AI graph workflows to detect discrepancies:

flowchart LR
    A[Live API Traffic] --> B[Traffic Capture Middleware]
    B --> C[(PostgreSQL)]
    C --> D[Endpoint Intelligence]

    E[GitHub Repository] --> F[Source Code + Git Diffs]

    D --> G[LangGraph AI Pipeline]
    F --> G

    G --> H[Behavior Analysis]
    H --> I[Drift Detection]
    I --> J[Documentation Generation]

    J --> K[GitHub Branch]
    K --> L[Documentation Commit]
    L --> M[Pull Request]

🤖 LangGraph AI Pipeline

DriftGuard models the AI analysis process as a deterministic, typed state machine using LangGraph:

[analyze_behavior] ──► [detect_drift] ──► [generate_docs] ──► END

Pipeline Nodes

analyze_behavior:
- Ingests recent API execution logs (methods, paths, status codes, latencies).
- Generates a concise summary of the endpoint's functional behavior, normal operation patterns, and edge cases.
detect_drift:
- Calculates error rates, latency spikes, and payload changes.
- Evaluates sample response bodies against expected behavior to flag anomalies and provide a drift reason.
generate_docs:
- Synthesizes the behavioral analysis into markdown documentation, edge case catalogs, and structured request/response examples.

# Shared LangGraph State
class AnalysisState(TypedDict):
    endpoint_method:   str
    endpoint_path:     str
    logs:              List[Dict[str, Any]]
    behavior_summary:  str
    drift_detected:    bool
    drift_description: Optional[str]
    documentation:     str
    edge_cases:        List[str]
    examples:          List[Dict[str, Any]]
    error:             Optional[str]

🐙 GitHub Automation Workflow

When documentation drift is detected or documentation is regenerated, DriftGuard executes an autonomous GitHub workflow:

1. Repository Analysis
   └── Inspects repository tree, source code files, and dependency manifests.

2. Commit Diff Analysis
   └── Compares recent commits to detect code changes since last documentation update.

3. Documentation Drift Detection
   └── LLM compares code changes against existing docs to confirm if docs are outdated.

4. Documentation Generation
   └── Writes a complete, production-grade documentation file with API references.

5. Branch Creation
   └── Creates an isolated branch (e.g. driftguard/update-docs) from default branch.

6. File Commit
   └── Commits the updated documentation to the target path.

7. Pull Request Submission
   └── Opens a Pull Request with drift summary, changed files list, and merge checklist.

Why Pull Requests? DriftGuard enforces a human-in-the-loop workflow. Automated changes are proposed as reviewable pull requests rather than silently overwriting the primary branch.

💻 Technology Stack

Layer	Technology	Description
Frontend	HTML5, TailwindCSS, Alpine.js, Chart.js	Responsive, accessible developer console with dark/light mode parity
Backend	Python 3.11+, FastAPI, Uvicorn, Starlette	High-performance asynchronous REST API and traffic capture middleware
Database	PostgreSQL, Neon Serverless	Relational database for logs, endpoints, user accounts, and doc history
ORM & Driver	SQLAlchemy 2.0 (Async), asyncpg	Fully asynchronous database queries and connection pooling
AI Orchestration	LangGraph, LangChain Core	Deterministic multi-step state graph execution
LLM Integrations	OpenRouter, Groq, Google Gemini	Flexible multi-provider support (Claude 3.5 Sonnet, Llama 3.3 70B, Gemini 2.5 Flash)
Authentication	JWT (PyJWT), GitHub OAuth 2.0	Secure session tokens and OAuth repository integration
Git Automation	GitHub REST API (httpx)	Branch creation, tree analysis, file commits, and PR management
Observability	OpenTelemetry	Distributed tracing and telemetry instrumentation
Deployment	Docker	Portable containerization ready for cloud deployments

📁 Project Structure

DriftGuard/
├── app/
│   ├── __init__.py
│   ├── config.py                  # Pydantic Settings & environment loader
│   ├── database.py                # SQLAlchemy async engine & session management
│   ├── deps.py                    # FastAPI authentication dependencies
│   ├── main.py                    # Application entry point & demo endpoints
│   ├── middleware/
│   │   ├── __init__.py
│   │   └── traffic_capture.py     # Non-blocking HTTP request/response interceptor
│   ├── models/
│   │   ├── __init__.py
│   │   ├── api_log.py             # Log entry SQLAlchemy model
│   │   ├── doc_history.py         # PR & documentation history model
│   │   ├── documentation.py       # Versioned documentation model
│   │   └── endpoint.py            # Discovered endpoint model
│   ├── routers/
│   │   ├── __init__.py
│   │   ├── auth.py                # JWT auth & GitHub OAuth endpoints
│   │   ├── dashboard.py           # Metrics, stats, and analytics router
│   │   ├── docs_router.py         # Documentation & OpenAPI export router
│   │   ├── endpoints.py           # Endpoint discovery & drift re-analysis
│   │   ├── github.py              # GitHub connection, analysis & PR router
│   │   └── logs.py                # Traffic logs query router
│   ├── schemas/
│   │   └── __init__.py            # Pydantic request/response schemas
│   └── services/
│       ├── __init__.py
│       ├── ai_service.py          # LangGraph state graph & LLM provider logic
│       ├── background_tasks.py    # Background stats refresh & maintenance
│       ├── endpoint_service.py    # Endpoint aggregation & drift tracking
│       └── log_service.py         # Log retrieval & filtering service
├── frontend/
│   └── index.html                 # Complete single-page Alpine.js console
├── screenshots/
│   └── README.md                  # Screenshot directory guide
├── Dockerfile                     # Docker container configuration
├── LICENSE                        # MIT License
├── migration_user_isolation.py    # Database migration helper
├── README.md                      # Project documentation
└── requirements.txt               # Python package dependencies

🚀 Getting Started

Prerequisites

Python 3.11+ installed
PostgreSQL database (local PostgreSQL or cloud instance like Neon)
Git installed
API key for at least one supported LLM provider:
- OpenRouter (OPENROUTER_API_KEY)
- Groq (GROK_API_KEY)
- Google Gemini (GEMINI_API_KEY)
GitHub Personal Access Token (PAT) with repo scope or GitHub OAuth App credentials.

Step-by-Step Installation

1. Clone the Repository

git clone https://github.com/Mohith-R17/DriftGuard.git
cd DriftGuard

2. Create and Activate Virtual Environment

# Windows
python -m venv venv
.\venv\Scripts\activate

# Linux / macOS
python3 -m venv venv
source venv/bin/activate

3. Install Dependencies

pip install -r requirements.txt

4. Configure Environment Variables

Create a .env file in the project root:

# Application
APP_NAME=DriftGuard
APP_VERSION=1.0.0
DEBUG=False
SECRET_KEY=generate_a_secure_random_string_here

# Database (PostgreSQL / Neon)
DATABASE_URL=postgresql+asyncpg://username:password@hostname:5432/database_name

# AI Providers (configure at least one)
OPENROUTER_API_KEY=your_openrouter_api_key_here
OPENROUTER_MODEL=anthropic/claude-3.5-sonnet

GROK_API_KEY=your_groq_api_key_here
GROQ_MODEL=llama-3.3-70b-versatile

GEMINI_API_KEY=your_gemini_api_key_here
GEMINI_MODEL=gemini-3.6-flash

# GitHub Integration
GITHUB_TOKEN=your_github_personal_access_token
GITHUB_CLIENT_ID=your_github_oauth_client_id
GITHUB_CLIENT_SECRET=your_github_oauth_client_secret
GITHUB_OAUTH_REDIRECT=http://localhost:8000/api/auth/github/callback

# Frontend & CORS
FRONTEND_URL=http://localhost:5500
CORS_ORIGINS=http://localhost:5500,http://127.0.0.1:5500,http://localhost:3000

5. Run Database Migrations

python migration_user_isolation.py

6. Start the Backend Server

uvicorn app.main:app --host 127.0.0.1 --port 8000 --reload

The FastAPI backend will start at http://127.0.0.1:8000. Interactive API docs are available at http://127.0.0.1:8000/docs.

7. Start the Frontend Server

In a new terminal window:

python -m http.server 5500 --directory frontend

8. Open the Application

Navigate to http://localhost:5500 in your web browser.

⚙️ Environment Variables

Variable	Required	Description
`DATABASE_URL`	Yes	PostgreSQL connection URL using `postgresql+asyncpg://` protocol
`SECRET_KEY`	Yes	Secret key for JWT signing and session validation
`OPENROUTER_API_KEY`	Optional	OpenRouter API key for Claude 3.5 Sonnet / GPT-4o inference
`OPENROUTER_MODEL`	Optional	Model identifier for OpenRouter (default: `anthropic/claude-3.5-sonnet`)
`GROK_API_KEY`	Optional	Groq API key for Llama 3.3 70B high-throughput inference
`GROQ_MODEL`	Optional	Model identifier for Groq (default: `llama-3.3-70b-versatile`)
`GEMINI_API_KEY`	Optional	Google Gemini API key for fallback inference
`GEMINI_MODEL`	Optional	Model identifier for Gemini (default: `gemini-3.6-flash`)
`GITHUB_TOKEN`	Optional	GitHub PAT for server-level fallback on Git write operations
`GITHUB_CLIENT_ID`	Optional	GitHub OAuth App Client ID for user sign-in
`GITHUB_CLIENT_SECRET`	Optional	GitHub OAuth App Client Secret
`GITHUB_OAUTH_REDIRECT`	Optional	OAuth callback URL (default: `http://localhost:8000/api/auth/github/callback`)
`FRONTEND_URL`	Optional	URL of the frontend application (default: `http://localhost:5500`)
`CORS_ORIGINS`	Optional	Comma-separated list of allowed CORS origins

📊 Current Capabilities vs. Future Scope

✅ Currently Implemented & Working

Non-intrusive FastAPI traffic capture middleware with latency and payload logging.
Dynamic endpoint path discovery and parameter normalization.
Multi-provider LLM integration with automatic priority fallbacks.
LangGraph 3-node state machine (analyze_behavior → detect_drift → generate_docs).
Full OpenAPI 3.0 specification export based on observed traffic.
GitHub REST API integration for tree inspection, commit comparisons, and source file retrieval.
Autonomous Git branch creation, documentation commits, and Pull Request submission.
Multi-tier token resolution (Request Payload → User OAuth Database Record → Environment Fallback).
Modern, accessible developer console with dark/light mode support.

🔮 Future Roadmap

Automated GitHub webhook listener for real-time push event drift checking.
Bidirectional OpenAPI specification synchronization via Pull Requests.
Multi-repository organization workspace management.
Webhook alerts for Slack, Discord, and Microsoft Teams on drift detection.
Framework middleware adapters for Express.js, Spring Boot, and Go Gin.

🔒 Security Notes

Never Commit Secrets: The .gitignore file is pre-configured to ignore .env, virtual environments, and local logs. Never push secrets or API keys to version control.
Least Privilege Access: When using Personal Access Tokens (PATs), grant only the minimum required permissions (repo scope for read/write repository access).
Human-in-the-Loop: DriftGuard creates Pull Requests instead of committing directly to main, ensuring all automated documentation changes are verified by a developer.
Token Protection: Tokens and secrets are masked in logs and never returned in public API responses.

🎮 Demo Workflow

Sign In: Open http://localhost:5500 and sign in or create an account.
View Traffic Logs: Inspect the live HTTP traffic captured by the middleware.
Explore Endpoints: View discovered endpoints and aggregated latency metrics in the Overview tab.
Inspect API Intelligence: View AI-generated summaries, edge cases, and request/response examples.
Re-Analyze Endpoint: Trigger the LangGraph pipeline to re-evaluate endpoint behavior against recent traffic.
Connect GitHub Repository: Navigate to GitHub Integration and enter a repository URL (e.g. https://github.com/username/your-api-project).
Analyze Repository: DriftGuard scans the repository files, inspects recent commits, and compares them with documentation.
Select Destination: Choose whether to update README.md, create DOCUMENTATION.md, or write to a custom path.
Generate Docs & Open PR: Click Generate Documentation & Open PR.
Review on GitHub: Click the generated Pull Request link on GitHub, inspect the automated diff, and merge!

🚀 Deploying to Render

Deploying DriftGuard to Render is streamlined using the provided render.yaml Blueprint.

AUTOMATED BY render.yaml

Render will automatically configure the following from the repository blueprint:

Provision a completely fresh PostgreSQL database (driftguard-db).
Build and deploy the Web Service (driftguard) using the repository's Dockerfile.
Bind the correct $PORT.
Set DEBUG=false.
Pass the internal PostgreSQL connection string dynamically to DATABASE_URL.
Generate a cryptographically secure random SECRET_KEY.

MANUAL CONFIGURATION REQUIRED

Follow these steps to deploy:

Push repository to GitHub: Ensure the latest codebase (including render.yaml) is in your GitHub repository.
Open Render: Go to your Render Dashboard and select New > Blueprint.
Select the DriftGuard repository: Connect your GitHub account and select your repository.
Render reads render.yaml: Render will automatically detect the database and web service configuration.
Enter required secret values: During setup, Render will prompt you for the following secrets (marked as sync: false in the blueprint):
- GROQ_API_KEY (Required for primary fast inference)
- GEMINI_API_KEY (Optional fallback)
- GITHUB_CLIENT_ID (Required for GitHub OAuth)
- GITHUB_CLIENT_SECRET (Required for GitHub OAuth)
Deploy: Click "Apply" to create the database and web service. Note: Database initialization is automatic on the first startup!
Get the Render URL: Once deployed, copy your public Render URL (e.g., https://driftguard-xxxx.onrender.com).
Configure GitHub OAuth callback: Update your GitHub OAuth Application settings to use the new URL:
- Homepage URL: https://driftguard-xxxx.onrender.com
- Authorization callback URL: https://driftguard-xxxx.onrender.com/api/auth/github/callback

📄 License

This project is licensed under the MIT License — see the LICENSE file for details.

Built with ❤️ for developers who believe documentation should always reflect reality.

Name		Name	Last commit message	Last commit date
app		app
frontend		frontend
screenshots		screenshots
.dockerignore		.dockerignore
.gitignore		.gitignore
DOCUMENTATION.md		DOCUMENTATION.md
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
migration_user_isolation.py		migration_user_isolation.py
render.yaml		render.yaml
requirements.txt		requirements.txt

Latest commit

History

Folders and files

Repository files navigation