Skip to content
BranchesTags

Repository files navigation

🌐 Driftless

Driftless is an AI-powered platform that automates README generation and detects documentation drift, ensuring codebase documentation is always current by reading code, generating accurate documentation, and raising GitHub PRs automatically.

TypeScript Supabase Tailwind CSS Groq @google/generative-ai License: MIT

📖 Table of Contents

🎯 About

Outdated documentation is a common pain point for development teams, leading to confusion, slower onboarding, and increased maintenance overhead. As codebases evolve, manual README updates often fall behind, creating a "documentation drift" that hinders productivity and project understanding. This problem is exacerbated in fast-paced development environments where keeping documentation in sync with code changes becomes a significant burden.

Driftless solves this by intelligently reading code and generating accurate READMEs using advanced AI models like Google Gemini and Groq. It proactively detects when documentation diverges from the codebase, providing real-time drift alerts 📈 and automating updates via GitHub Pull Requests 🤖. This ensures that your project's documentation is always current, reducing manual effort and improving developer experience.

✨ Features

  • 🤖 AI-powered README generation — Automatically create and update READMEs by analyzing your codebase using Google Gemini and Groq.
  • 📈 Real-time documentation drift detection — Continuously monitor your repositories for discrepancies between code and documentation, with historical tracking and alerts.
  • 🔄 Automated GitHub Pull Request creation — When drift is detected, Driftless can automatically generate and submit GitHub PRs with suggested documentation updates.
  • 🔒 Secure user authentication — Seamlessly sign in and manage access using NextAuth.js with GitHub OAuth and Supabase for robust security.
  • 💳 Subscription management and checkout flows — Integrated with Dodo Payments for handling various subscription plans and secure transactions.
  • 🔗 CI/CD integration for documentation drift checks — Incorporate documentation checks into your continuous integration pipeline using dedicated API keys.
  • 📊 Interactive data visualization — Track documentation health and drift history with intuitive charts powered by Recharts.
  • ⚙️ Customizable settings — Manage account details, API keys, and notification preferences through a dedicated settings portal.

🛠️ Tech Stack

🎨 Frontend

Technology Purpose
Next.js React Framework for server-side rendering and routing
Tailwind CSS Utility-first CSS framework for rapid UI development
Radix UI Unstyled, accessible components for building design systems
Recharts Composable charting library built with React and D3

⚙️ Backend & Infrastructure

Technology Purpose
TypeScript Statically typed superset of JavaScript for enhanced code quality
Supabase Open-source Firebase alternative for database, auth, and storage
NextAuth.js Flexible authentication for Next.js applications
Groq High-performance AI inference engine for generative models
Octokit Official GitHub API client for Node.js
Resend Developer-friendly email API for transactional emails
Google Gemini Advanced generative AI models for code analysis and content generation

📋 Prerequisites

⚠️ Make sure you have all of these installed before starting.

  1. Node.js 18+ — Download · Check: node --version
  2. npm — Comes with Node.js · Check: npm --version
  3. Supabase account — Sign up
  4. GitHub OAuth App — Create one
  5. Google Cloud Project (Generative AI) — Set up
  6. Dodo Payments account — Sign up
  7. Resend account — Sign up

⚙️ Installation

Step 1 — Clone the repository

git clone https://github.com/het2576/Driftless.git
cd Driftless

Step 2 — Install dependencies

npm install

Step 3 — Configure environment

cp .env.example .env.local

💡 Open .env.local and fill in your values. See Environment Variables below.

🔐 Environment Variables

Create a .env.local file in the project root:

# ✅ Required: Secret key for NextAuth.js session encryption
NEXTAUTH_SECRET=

# ✅ Required: Base URL of the application for NextAuth.js callbacks
NEXTAUTH_URL=

# ⚪ Optional: Email address used as the 'From' sender for Resend emails
RESEND_FROM_EMAIL=

# ✅ Required: GitHub OAuth Client ID for authentication
GITHUB_CLIENT_ID=

# ✅ Required: GitHub OAuth Client Secret for authentication
GITHUB_CLIENT_SECRET=

# ✅ Required: API key for Google Gemini Generative AI services
GEMINI_API_KEY=

# ✅ Required: API key for Groq AI inference engine
GROQ_API_KEY=

# ✅ Required: Public URL for the Supabase project
NEXT_PUBLIC_SUPABASE_URL=

# ✅ Required: Public Anon Key for client-side Supabase access
NEXT_PUBLIC_SUPABASE_ANON_KEY=

# ✅ Required: Service Role Key for server-side Supabase access
SUPABASE_SERVICE_ROLE_KEY=

# ✅ Required: GitHub App ID for webhook automation
GITHUB_APP_ID=

# ✅ Required: Private key for GitHub App authentication
GITHUB_APP_PRIVATE_KEY=

# ✅ Required: Webhook secret for GitHub App events
GITHUB_APP_WEBHOOK_SECRET=

# ✅ Required: GitHub App Client ID for OAuth flows
GITHUB_APP_CLIENT_ID=

# ✅ Required: GitHub App Client Secret for OAuth flows
GITHUB_APP_CLIENT_SECRET=

# ✅ Required: API key for Dodo Payments
DODO_API_KEY=

# ✅ Required: Dodo Payments environment (test_mode or live_mode)
DODO_ENVIRONMENT=

# ✅ Required: Webhook secret for Dodo Payments events
DODO_WEBHOOK_SECRET=

# ✅ Required: Product ID for the Dodo Pro plan
DODO_PRO_PRODUCT_ID=

# ✅ Required: Product ID for the Dodo Pro annual plan
DODO_PRO_ANNUAL_PRODUCT_ID=

# ✅ Required: Product ID for the Dodo Team plan
DODO_TEAM_PRODUCT_ID=

# ✅ Required: Product ID for the Dodo Team annual plan
DODO_TEAM_ANNUAL_PRODUCT_ID=

# ✅ Required: Public publishable key for Dodo Payments client-side integration
NEXT_PUBLIC_DODO_PUBLISHABLE_KEY=

# ✅ Required: Email address for receiving contact form submissions
CONTACT_EMAIL=

# ✅ Required: Secret key for authenticating cron jobs
CRON_SECRET=
Variable Required Description
NEXTAUTH_SECRET ✅ Yes Secret key for NextAuth.js session encryption
NEXTAUTH_URL ✅ Yes Base URL of the application for NextAuth.js callbacks
RESEND_FROM_EMAIL ⚪ No Email address used as the 'From' sender for Resend emails
GITHUB_CLIENT_ID ✅ Yes GitHub OAuth Client ID for authentication
GITHUB_CLIENT_SECRET ✅ Yes GitHub OAuth Client Secret for authentication
GEMINI_API_KEY ✅ Yes API key for Google Gemini Generative AI services
GROQ_API_KEY ✅ Yes API key for Groq AI inference engine
NEXT_PUBLIC_SUPABASE_URL ✅ Yes Public URL for the Supabase project
NEXT_PUBLIC_SUPABASE_ANON_KEY ✅ Yes Public Anon Key for client-side Supabase access
SUPABASE_SERVICE_ROLE_KEY ✅ Yes Service Role Key for server-side Supabase access
GITHUB_APP_ID ✅ Yes GitHub App ID for webhook automation
GITHUB_APP_PRIVATE_KEY ✅ Yes Private key for GitHub App authentication
GITHUB_APP_WEBHOOK_SECRET ✅ Yes Webhook secret for GitHub App events
GITHUB_APP_CLIENT_ID ✅ Yes GitHub App Client ID for OAuth flows
GITHUB_APP_CLIENT_SECRET ✅ Yes GitHub App Client Secret for OAuth flows
DODO_API_KEY ✅ Yes API key for Dodo Payments
DODO_ENVIRONMENT ✅ Yes Dodo Payments environment (test_mode or live_mode)
DODO_WEBHOOK_SECRET ✅ Yes Webhook secret for Dodo Payments events
DODO_PRO_PRODUCT_ID ✅ Yes Product ID for the Dodo Pro plan
DODO_PRO_ANNUAL_PRODUCT_ID ✅ Yes Product ID for the Dodo Pro annual plan
DODO_TEAM_PRODUCT_ID ✅ Yes Product ID for the Dodo Team plan
DODO_TEAM_ANNUAL_PRODUCT_ID ✅ Yes Product ID for the Dodo Team annual plan
NEXT_PUBLIC_DODO_PUBLISHABLE_KEY ✅ Yes Public publishable key for Dodo Payments client-side integration
CONTACT_EMAIL ✅ Yes Email address for receiving contact form submissions
CRON_SECRET ✅ Yes Secret key for authenticating cron jobs

🔒 Never commit your .env.local file. It's already in .gitignore.

🚀 Usage

Development Server

npm run dev

Open http://localhost:3000 in your browser.

Quick Start Example

To experience Driftless, start the development server and navigate to the application in your browser.

  1. Click "Sign in with GitHub" to authenticate your account.
  2. Once logged in, you can navigate to the "Generate README" section.
  3. Provide a GitHub repository URL or select one from your installations.
  4. Initiate the README generation process to see how Driftless analyzes your code and produces documentation.
  5. Explore the "Drift History" to monitor documentation health over time.

🔌 API Reference

🌐 Base URL: http://localhost:3000

🔒 Authentication: Sign in via the web interface — API endpoints use session cookies.

Method Endpoint Description Auth
GET /api/alerts/drift Retrieve documentation drift alerts 🔒 Required
POST /api/analyze Analyze a repository for documentation insights 🔒 Required
GET /api/auth/[...nextauth] Handle NextAuth.js authentication callbacks 🔓 Public
POST /api/auth/[...nextauth] Handle NextAuth.js authentication requests 🔓 Public
POST /api/checkout/confirm Confirm a Dodo Payments checkout session 🔒 Required
GET /api/checkout Retrieve Dodo Payments checkout details 🔒 Required
POST /api/checkout Initiate a Dodo Payments checkout session 🔒 Required
POST /api/ci/check Perform a documentation drift check for CI/CD 🔒 Required
POST /api/contact Submit a contact form message 🔒 Required
GET /api/cron/drift-alerts Trigger scheduled documentation drift alerts 🔒 Required
POST /api/cron/test-alert Send a test documentation drift alert 🔒 Required
GET /api/drift/history Retrieve historical documentation drift data 🔒 Required
POST /api/drift/reset Reset documentation drift history for a repository 🔒 Required
POST /api/drift Initiate a documentation drift analysis 🔒 Required
POST /api/generate Generate a README for a given repository 🔒 Required
POST /api/generate/stream Stream README generation results 🔒 Required
POST /api/install/save Save GitHub App installation details 🔒 Required
GET /api/installations Retrieve user's GitHub App installations 🔒 Required
GET /api/me Get current authenticated user's profile 🔒 Required
POST /api/notifications/read Mark user notifications as read 🔒 Required
GET /api/notifications Retrieve user's notifications 🔒 Required
GET /api/org/repos Get repositories for an organization 🔒 Required
GET /api/portal Access Dodo Payments customer portal 🔒 Required
POST /api/pr Create a GitHub Pull Request for documentation updates 🔒 Required
GET /api/readmes/[id]/share Share a generated README by ID 🔒 Required
GET /api/readmes/latest Retrieve the latest generated README 🔒 Required
GET /api/repos Get user's accessible repositories 🔒 Required
GET /api/review/[token] Review a documentation update via token 🔒 Required
POST /api/roast Generate a "roast" of a README (public demo) 🔓 Public
POST /api/settings/account Update user account settings 🔒 Required
POST /api/settings/apikey Manage user API keys 🔒 Required
POST /api/settings/notifications Update user notification settings 🔒 Required
GET /api/team/members Retrieve team members 🔒 Required
POST /api/webhooks/dodo Handle incoming Dodo Payments webhook events 🔓 Public
POST /api/webhooks/github Handle incoming GitHub webhook events 🔓 Public

Example Request

# Public endpoints can be called directly.
# Protected endpoints require an active browser session.
curl http://localhost:3000/api/roast -X POST -H "Content-Type: application/json" -d '{"text": "This is a README."}'

Example Response

{
  "success": true,
  "data": {
    "roast": "Your README is so basic, it probably thinks 'git push' is a workout routine."
  }
}

📁 Project Structure

Driftless/
├── app/              # Next.js App Router: pages, API routes, and layouts
│   ├── api/          # API routes (e.g., /api/auth, /api/generate)
│   ├── (auth)/       # Authentication-related pages and components
│   ├── (dashboard)/  # Main application dashboard and features
│   └── page.tsx      # Entry point for the root application
├── components/       # Reusable UI components
├── lib/              # Utility functions, API clients, and helpers
├── public/           # Static assets (images, favicons)
├── styles/           # Global styles and Tailwind CSS configuration
├── types/            # TypeScript type definitions
├── .env.example      # Environment variables template
├── package.json      # Dependencies and scripts
└── README.md         # This file

The project follows a modular, feature-based structure typical for Next.js applications using the App Router. Core application logic, UI components, and API routes are logically grouped, promoting maintainability and scalability. This organization allows for clear separation of concerns, making it easier to navigate and extend the codebase.

🤝 Contributing

Contributions make this project better. Here's how to get involved:

🐛 Reporting Bugs

Before creating a bug report:

  • ✅ Check the existing issues
  • ✅ Collect your environment details (OS, Node version, browser)
  • ✅ Reproduce the bug consistently

Create a bug report →

💡 Suggesting Features

Feature suggestions are tracked as GitHub issues.

Suggest a feature →

🔧 Pull Requests

  1. 🍴 Fork the repository
  2. 🌿 Create a feature branch: git checkout -b feat/amazing-feature
  3. 💾 Commit your changes: git commit -m 'feat: add amazing feature'
  4. 📤 Push to the branch: git push origin feat/amazing-feature
  5. 🔁 Open a Pull Request

Commit convention: We use Conventional Commits

  • feat: — new feature
  • fix: — bug fix
  • docs: — documentation only
  • refactor: — code change, no feature or fix
  • test: — add or update tests

📄 License

This project is licensed under the MIT License.

You're free to use, modify, and distribute this project for any purpose. See the LICENSE file for full details.

Built with ❤️ by het2576

If this project helped you, consider giving it a ⭐

⭐ Star this repo · 🐛 Report a Bug · 💡 Request a Feature

About

driftlessx.dev

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages