IntelliDocs

Inspiration

Developers love writing code but not updating project documentation. It’s tedious, easy to miss and can take developer’s focus away from their main work- Writing functional code.

That’s where we came up with the idea of IntelliDocs - A Github app that is integrated into your repository, tracks commits in real time and generates easy to understand documentation everytime you push your code.

What it does

IntelliDocs is a GitHub App that listens to repository push events and automatically generates updated documentation for changed code. Upon each push to the main branch, it fetches the latest files, uses AI to generate documentation and summaries, then commits the docs to a separate repository dedicated to documentation. Additionally, it can add AI-generated summaries as comments or statuses on pull requests, keeping maintainers informed. All of this runs automatically in the background, seamlessly integrating with existing workflows.

How we built it

We built IntelliDocs using FastAPI to handle GitHub webhook events. The app verifies webhook signatures for security, parses push event payloads, and triggers background tasks to process commits. For local development, we use ngrok to expose our localhost and simulate real webhook calls from GitHub.

The backend is structured with separate modules handling GitHub authentication, git operations, webhook parsing, and AI documentation generation. The project is containerized and configurable via environment variables, including secrets and repository info.

Key technologies:

FastAPI for async API endpoints and webhook handling
HMAC signature verification for webhook security
ngrok for local development tunneling
Python environment with modular structure
GitHub App authentication and API interactions
AI-based doc generation (planned, stubbed for testing)

Challenges we ran into

Webhook signature verification: Ensuring secure and reliable verification of incoming webhook signatures to prevent spoofed requests was critical. We had to carefully handle edge cases like missing or malformed signatures.
Payload parsing: GitHub sometimes sends payloads as URL-encoded forms rather than raw JSON, requiring decoding and flexible parsing logic.
Local development setup: Getting ngrok configured and synced with GitHub app webhook URLs took time, especially to handle port forwarding and HTTPS.
Branch and commit handling: Detecting relevant branches (main/master) and handling commit diffs accurately for triggering docs generation involved understanding GitHub’s webhook data deeply.
Mocking AI generation: For early development, we had to stub out AI doc generation to focus on webhook processing and background tasks.

Accomplishments that we're proud of

Successfully built a secure and extensible FastAPI webhook listener that verifies GitHub signatures and processes push events asynchronously.
Designed a clear, modular project structure separating auth, webhook handling, git operations, and doc generation.
Created a comprehensive setup guide covering GitHub App creation, ngrok setup, environment configuration, and testing — making the project accessible to other developers.
Implemented a test mode that bypasses GitHub API calls and simulates the entire flow, allowing quick iteration and debugging.

What we learned

The importance of strict security practices like validating webhook signatures before processing any payload.
Handling GitHub’s webhook payload quirks (like URL-encoded forms) requires careful parsing to avoid errors.
Asynchronous background processing helps keep API endpoints responsive and scalable.
The GitHub App ecosystem is powerful but requires meticulous configuration — permissions, installation, webhook URLs — to work correctly.
Local tunneling tools like ngrok are essential for testing webhooks but add complexity to setup.
Modular design improves maintainability and allows us to incrementally build features like AI integration.