Transform your GitHub repositories with AI-generated, always up-to-date documentation
Features β’ Demo β’ Installation β’ Tech Stack β’ API Docs β’ Deployment
DaemonDoc is an intelligent README generation platform that leverages AI to automatically create and maintain comprehensive documentation for your GitHub repositories. By analyzing your codebase structure, dependencies, and commits, DaemonDoc generates professional, contextual READMEs that stay synchronized with your code through GitHub webhooks.
- β±οΈ Save Time: Stop writing boilerplate documentation manually
- π Always Current: Auto-updates when you push code changes
- π§ Context-Aware: Analyzes actual code, not just file names
- π¨ Professional: Generates well-structured, comprehensive docs
- π Secure: OAuth authentication with encrypted token storage
- β‘ Fast: Background processing with Redis-powered job queues
-
π€ AI-Powered Analysis
- Uses Groq's LLaMA 3.3 70B model for intelligent code understanding
- Uses Groq's openai/gpt-oss-120b for Readme Generation
- Analyzes repository structure, dependencies, and file relationships
- Generates contextual documentation based on actual implementation
-
π Automatic Updates
- GitHub webhook integration for real-time updates
- Regenerates README on every push event
- Smart diff analysis to focus on changed files
-
π Intelligent Context Building
- Identifies and prioritizes important files
- Extracts metadata from package managers (npm, pip, maven, etc.)
- Builds optimal prompts with code snippets and structure
-
π― Repository Management
- Select specific repositories to activate
- Dashboard to manage all your projects
- One-click activation/deactivation
-
π Enterprise-Grade Security
- GitHub OAuth 2.0 authentication
- AES-256-GCM token encryption
- HMAC-SHA256 webhook signature verification
- JWT-based session management
-
β‘ High Performance
- BullMQ-powered background job processing
- Redis queue for async operations
- Optimized context building (70% size reduction)
- Handles large repositories efficiently
Frontend: Coming soon (Vercel deployment)
Backend API: https://daemondoc-4.onrender.com
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β 1. Connect GitHub Account β OAuth Authentication β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β 2. Select Repository β Creates Webhook & Activates β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β 3. Push Code β Webhook Triggers β Job Queued β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β 4. AI Analyzes Codebase β Generates README β Commits to Repo β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
(Add screenshots of your landing page, dashboard, and repository selection UI here)
ββββββββββββββββββββ
β React Client β
β (Vite + TW) β
ββββββββββ¬ββββββββββ
β REST API
β
ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β Express Backend β
β ββββββββββββββββ ββββββββββββββββ βββββββββββββββββββββ β
β β Auth β β GitHub β β Worker β β
β β Controller β β Controller β β Controller β β
β ββββββββββββββββ ββββββββββββββββ βββββββββββββββββββββ β
ββββββββββ¬βββββββββββββββββββ¬βββββββββββββββββββ¬βββββββββββββββββ
β β β
β β β
ββββββββββββββ βββββββββββββββββββ ββββββββββββββββ
β MongoDB β β GitHub API β β Redis β
β (User β β (Repos, Trees, β β (BullMQ) β
β Repos) β β Webhooks) β β β
ββββββββββββββ βββββββββββββββββββ ββββββββ¬ββββββββ
β
β
ββββββββββββββββββββ
β Background β
β Worker Process β
ββββββββββ¬ββββββββββ
β
β
ββββββββββββββββββββ
β Groq AI API β
β (LLaMA 3.3 70B) β
ββββββββββββββββββββ
- User Authentication: GitHub OAuth β Encrypted Token Storage β JWT Generation
- Repository Activation: Create Webhook β Store in MongoDB β Initial README Generation
- Push Event: GitHub Webhook β Verify Signature β Queue Job in Redis
- Background Processing:
- Fetch repository tree and changed files
- Build intelligent context with code analysis
- Generate README using Groq AI
- Commit README back to repository
- Update job status
| Technology | Purpose | Version |
|---|---|---|
| React | UI framework | 19.2.0 |
| Vite | Build tool & dev server | 7.2.4 |
| React Router | Client-side routing | 7.12.0 |
| Tailwind CSS | Utility-first styling | 4.1.18 |
| Framer Motion | Animation library | 12.25.0 |
| Zustand | State management | 5.0.9 |
| Lucide React | Icon library | 0.562.0 |
| Technology | Purpose | Version |
|---|---|---|
| Node.js | Runtime environment | 18+ |
| Express | Web framework | 5.2.1 |
| MongoDB | Primary database | - |
| Mongoose | ODM for MongoDB | 9.1.2 |
| Redis | Job queue & caching | - |
| IORedis | Redis client | 5.9.1 |
| BullMQ | Job queue management | 5.66.4 |
| JWT | Authentication tokens | 9.0.3 |
| Axios | HTTP client | 1.13.2 |
- Groq AI - LLaMA 3.3 70B model for README generation
- GitHub API - Repository access, webhooks, commits
- Redis Labs - Managed Redis instance
- MongoDB Atlas - Cloud database
Before you begin, ensure you have:
- Node.js 18.x or higher (Download)
- npm or yarn package manager
- MongoDB instance (MongoDB Atlas for cloud)
- Redis instance (Redis Labs for cloud or local)
- GitHub OAuth App (Create one)
- Groq API Key (Get free key)
git clone https://github.com/yourusername/daemondoc.git
cd daemondoccd server
npm installCreate .env file in server/ directory:
# Database Configuration
MONGO_URI=mongodb+srv://username:[email protected]/daemondoc
# JWT Secret (generate with: openssl rand -base64 32)
JWT_SECRET=your_super_secret_jwt_key_minimum_32_characters
# GitHub OAuth App Configuration
GITHUB_CLIENT_ID=your_github_oauth_client_id
GITHUB_CLIENT_SECRET=your_github_oauth_client_secret
GITHUB_CALLBACK_URL=http://localhost:3000/auth/github/callback
# Token Encryption (generate with: openssl rand -hex 32)
GITHUB_TOKEN_SECRET=64_character_hex_string_for_aes256_encryption
# Webhook Security
GITHUB_WEBHOOK_SECRET=your_custom_webhook_secret_string
# Redis Configuration
REDIS_HOST=your-redis-host.cloud.redislabs.com
REDIS_PORT=17140
REDIS_PASSWORD=your_redis_password
# Application URLs
FRONTEND_URL=http://localhost:5173
BACKEND_URL=http://localhost:3000
# Groq AI Configuration
GROQ_API_KEY=gsk_your_groq_api_key_here
GROQ_MODEL=llama-3.3-70b-versatile
README_FILE_NAME=README.mdcd ../client
npm installCreate .env file in client/ directory:
VITE_BACKEND_URL=http://localhost:3000Terminal 1 - Backend:
cd server
npm run dev
# Server starts on http://localhost:3000Terminal 2 - Frontend:
cd client
npm run dev
# Client starts on http://localhost:5173Open your browser and navigate to http://localhost:5173
- Go to GitHub Developer Settings
- Click New OAuth App
- Fill in the details:
- Application name: DaemonDoc (or your choice)
- Homepage URL:
http://localhost:5173(dev) or production URL - Authorization callback URL:
http://localhost:3000/auth/github/callback
- Click Register application
- Copy Client ID and generate Client Secret
- Add to your
server/.envfile
- Visit Groq Console
- Sign up for a free account
- Navigate to API Keys section
- Click Create API Key
- Copy the key and add to
server/.envasGROQ_API_KEY
Local Development:
# macOS with Homebrew
brew install redis
brew services start redis
# Ubuntu/Debian
sudo apt-get install redis-server
sudo systemctl start redis-server
# Verify installation
redis-cli ping # Should return PONGProduction (Redis Labs):
- Sign up at Redis Cloud
- Create a new database
- Copy connection details (host, port, password)
- Add to
server/.env
Local Development:
# macOS
brew tap mongodb/brew
brew install mongodb-community
brew services start mongodb-community
# Ubuntu
sudo apt-get install mongodb
sudo systemctl start mongodbProduction (MongoDB Atlas):
- Sign up at MongoDB Atlas
- Create a free cluster
- Add a database user
- Whitelist your IP address (or 0.0.0.0/0 for all)
- Get connection string and add to
server/.env
- Development:
http://localhost:3000 - Production:
https://daemondoc-4.onrender.com
All protected routes require a JWT token in the Authorization header:
Authorization: Bearer <your_jwt_token>
Initiates GitHub OAuth flow.
Response: Redirects to GitHub authorization page
GitHub OAuth callback handler.
Query Parameters:
code(string, required) - Authorization code from GitHub
Response:
{
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"user": {
"id": "507f1f77bcf86cd799439011",
"githubId": "12345678",
"username": "octocat",
"avatar": "https://avatars.githubusercontent.com/u/583231"
}
}Status Codes:
200 OK- Successful authentication400 Bad Request- Invalid or missing code500 Internal Server Error- Server error
Verifies JWT token and returns user information.
Headers:
Authorization: Bearer <jwt_token>
Response:
{
"user": {
"id": "507f1f77bcf86cd799439011",
"githubId": "12345678",
"username": "octocat"
}
}Status Codes:
200 OK- Token valid401 Unauthorized- Invalid or expired token404 Not Found- User not found
Fetches all repositories accessible to the authenticated user.
Headers:
Authorization: Bearer <jwt_token>
Response:
{
"reposData": [
{
"id": 123456789,
"name": "my-awesome-project",
"full_name": "octocat/my-awesome-project",
"private": false,
"owner": "octocat",
"default_branch": "main",
"activated": true
},
{
"id": 987654321,
"name": "another-repo",
"full_name": "octocat/another-repo",
"private": true,
"owner": "octocat",
"default_branch": "master",
"activated": false
}
]
}Status Codes:
200 OK- Success401 Unauthorized- Invalid token404 Not Found- GitHub access token not found500 Internal Server Error- Failed to fetch repositories
Activates README generation for a repository.
Headers:
Authorization: Bearer <jwt_token>
Content-Type: application/json
Body:
{
"repoId": 123456789,
"repoName": "my-awesome-project",
"repoFullName": "octocat/my-awesome-project",
"repoOwner": "octocat",
"defaultBranch": "main"
}Response:
{
"message": "Repository activity added successfully"
}Status Codes:
200 OK- Successfully activated400 Bad Request- Missing required fields or already activated401 Unauthorized- Invalid token422 Unprocessable Entity- Webhook already exists500 Internal Server Error- Failed to create webhook
Actions Performed:
- Creates GitHub webhook for push events
- Stores repository activation in database
- Queues initial README generation job
Deactivates README generation for a repository.
Headers:
Authorization: Bearer <jwt_token>
Content-Type: application/json
Body:
{
"repoId": 123456789
}Response:
{
"message": "Repository deactivated successfully"
}Status Codes:
200 OK- Successfully deactivated401 Unauthorized- Invalid token404 Not Found- Active repository not found500 Internal Server Error- Failed to delete webhook
Actions Performed:
- Deletes GitHub webhook
- Marks repository as inactive in database
Receives GitHub webhook events for push notifications.
Headers:
X-Hub-Signature-256: sha256=<hmac_signature>
Content-Type: application/json
Body: Standard GitHub push event payload
Response:
{
"message": "Webhook received and job queued"
}Status Codes:
200 OK- Webhook processed successfully403 Forbidden- Invalid webhook signature400 Bad Request- Invalid payload500 Internal Server Error- Processing error
Webhook Event Processing:
- Verifies HMAC-SHA256 signature
- Extracts repository and commit information
- Checks if repository is activated
- Queues README generation job in Redis
Health check endpoint for monitoring.
Response:
{
"status": "ok",
"timestamp": "2026-01-11T10:30:00.000Z",
"uptime": 3600.5,
"redis": "connected"
}Status Codes:
200 OK- Service healthy
Use Cases:
- Uptime monitoring
- Load balancer health checks
- Keepalive pings for Render free tier
-
Create Web Service
- Go to Render Dashboard
- Click New + β Web Service
- Connect your GitHub repository
-
Configure Service
Name: daemondoc-backend Region: Choose closest to your users Branch: main Root Directory: server Runtime: Node Build Command: npm install Start Command: npm start -
Environment Variables Add all variables from your
server/.env:MONGO_URIJWT_SECRETGITHUB_CLIENT_IDGITHUB_CLIENT_SECRETGITHUB_CALLBACK_URL(update with Render URL)GITHUB_TOKEN_SECRETGITHUB_WEBHOOK_SECRETREDIS_HOSTREDIS_PORTREDIS_PASSWORDFRONTEND_URL(your Vercel URL)BACKEND_URL(your Render URL)GROQ_API_KEYGROQ_MODELREADME_FILE_NAME
-
Deploy
- Click Create Web Service
- Wait for deployment to complete
- Note your service URL (e.g.,
https://daemondoc-4.onrender.com)
-
Import Project
- Go to Vercel Dashboard
- Click Add New β Project
- Import your GitHub repository
-
Configure Project
Framework Preset: Vite Root Directory: client Build Command: npm run build Output Directory: dist Install Command: npm install -
Environment Variables Add environment variable:
VITE_BACKEND_URL= Your Render backend URL
-
Deploy
- Click Deploy
- Vercel will automatically deploy
- Note your deployment URL
-
Update GitHub OAuth App
- Go to GitHub OAuth App settings
- Update Homepage URL to your Vercel URL
- Update Callback URL to
https://your-render-app.onrender.com/auth/github/callback
-
Update Environment Variables
- Update
GITHUB_CALLBACK_URLin Render - Update
FRONTEND_URLin Render - Update
BACKEND_URLin Render and Vercel
- Update
-
Test the Application
- Visit your Vercel URL
- Test GitHub login
- Activate a test repository
- Make a commit and verify README generation
Option 1: GitHub Actions (Already configured)
- File:
.github/workflows/keepalive.yml - Pings every 10 minutes
- Note: May have delays during high GitHub load
Option 2: External Monitoring (Recommended)
- Sign up at UptimeRobot
- Create new monitor:
- Monitor Type: HTTP(s)
- URL:
https://daemondoc-4.onrender.com/health - Monitoring Interval: 5 minutes
- Save and activate
Option 3: Cron-job.org
- Sign up at cron-job.org
- Create new cron job:
- URL:
https://daemondoc-4.onrender.com/health - Schedule: Every 10 minutes
- URL:
- Activate
-
Authentication
- OAuth 2.0 with GitHub
- JWT tokens with 7-day expiration
- Secure token storage in localStorage
-
Encryption
- AES-256-GCM encryption for GitHub access tokens
- Random IV generation for each encryption
- Authentication tags for data integrity
-
Webhook Security
- HMAC-SHA256 signature verification
- Timing-safe equal comparison
- Secret key validation
-
Database Security
- Mongoose schema validation
- MongoDB connection with authentication
- Encrypted sensitive fields
-
API Security
- CORS configuration
- Rate limiting (recommended to add)
- Input validation and sanitization
- Never commit
.envfiles - Add to.gitignore - Rotate secrets regularly - Especially JWT and encryption keys
- Use HTTPS in production - Both Render and Vercel provide free SSL
- Whitelist IPs for databases - Restrict MongoDB and Redis access
- Monitor logs - Watch for suspicious activity
- Update dependencies - Run
npm auditregularly
Problem: Redis connection failed or ECONNREFUSED
Solutions:
# Check if Redis is running locally
redis-cli ping # Should return PONG
# Check Redis credentials in .env
echo $REDIS_HOST
echo $REDIS_PORT
# For cloud Redis, verify:
# 1. IP whitelist includes your server IP
# 2. Credentials are correct
# 3. Firewall allows connections on Redis portProblem: MongoServerError: bad auth or connection timeout
Solutions:
# Test connection with mongosh
mongosh "your_connection_string"
# For MongoDB Atlas:
# 1. Check network access (IP whitelist)
# 2. Verify database user credentials
# 3. Ensure user has read/write permissions
# 4. Check if connection string includes database nameProblem: README not updating after push
Solutions:
-
Check webhook exists:
- Go to repo β Settings β Webhooks
- Verify webhook URL matches your backend
- Check recent deliveries for errors
-
Verify webhook secret:
- Ensure
GITHUB_WEBHOOK_SECRETmatches webhook configuration - Check server logs for signature verification errors
- Ensure
-
Test webhook manually:
curl -X POST https://your-render-app.onrender.com/api/github/webhookhandler \ -H "Content-Type: application/json" \ -H "X-Hub-Signature-256: sha256=test" \ -d '{"ref":"refs/heads/main"}'
Problem: README generation takes too long or times out
Solutions:
- Large repositories: Generation may take 1-3 minutes
- Check Groq API limits: Verify you haven't exceeded rate limits
- Review context size: Check if repository is extremely large
- Check worker logs: Look for specific errors in Render logs
# Monitor job queue
redis-cli
> KEYS bullmq:*
> LLEN bullmq:readme-generation:waitProblem: redirect_uri_mismatch or callback fails
Solutions:
-
Verify callback URL:
- GitHub OAuth App settings must match exactly
- Include protocol (http:// or https://)
- No trailing slash
-
Update environment variables:
GITHUB_CALLBACK_URL=https://your-actual-domain.com/auth/github/callback
-
Clear browser cache: Old redirect URIs may be cached
The system implements intelligent file filtering:
// Files automatically excluded:
- node_modules/, vendor/, dist/, build/
- .git/, .github/workflows/
- Binary files, images, fonts
- Lock files (package-lock.json, yarn.lock)
- Log files
// Files prioritized:
- Package.json, requirements.txt, pom.xml
- Main source files (src/, lib/)
- Configuration files
- Documentation files// Job configuration
{
removeOnComplete: { count: 100 }, // Keep last 100 completed
removeOnFail: { count: 50 }, // Keep last 50 failed
attempts: 3, // Retry failed jobs 3 times
backoff: {
type: 'exponential',
delay: 2000 // Start with 2s delay
}
}Ensure indexes are created for optimal query performance:
// User schema
username: { type: String, index: true }
githubId: { type: String, unique: true, index: true }
// ActiveRepo schema
userId: { type: ObjectId, index: true }
repoId: { type: Number, index: true }
active: { type: Boolean, index: true }- GitHub OAuth login flow
- Repository list fetches correctly
- Repository activation creates webhook
- Push event triggers README generation
- Generated README commits to repository
- Repository deactivation removes webhook
- Health endpoint responds
- Error handling for invalid tokens
- Error handling for missing environment variables
# Health check
curl https://daemondoc.online/health
# Get repositories (requires token)
curl -H "Authorization: Bearer YOUR_JWT_TOKEN" \
https://daemondoc.online/api/github/getGithubRepos
# Activate repository
curl -X POST https://daemondoc.online/api/github/addRepoActivity \
-H "Authorization: Bearer YOUR_JWT_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"repoId": 123456,
"repoName": "test-repo",
"repoFullName": "username/test-repo",
"repoOwner": "username",
"defaultBranch": "main"
}'Contributions are welcome! Here's how you can help:
- Report Bugs - Open an issue with details
- Suggest Features - Propose new functionality
- Submit PRs - Fix bugs or add features
- Improve Docs - Enhance documentation
- Share Feedback - Tell us what you think
-
Fork the repository
gh repo fork yourusername/daemondoc
-
Create a feature branch
git checkout -b feature/amazing-feature
-
Make your changes
- Follow existing code style
- Add comments for complex logic
- Update documentation if needed
-
Test your changes
# Run server cd server && npm run dev # Run client cd client && npm run dev
-
Commit with meaningful message
git commit -m "feat: add amazing feature" -
Push to your fork
git push origin feature/amazing-feature
-
Open a Pull Request
- Describe what you changed
- Reference any related issues
- Add screenshots if UI changes
- Use ES6+ features
- Follow existing naming conventions
- Add JSDoc comments for functions
- Keep functions small and focused
- Use async/await over promises
- Handle errors gracefully
This project is licensed under the ISC License.
Copyright (c) 2026 DaemonDoc
Permission to use, copy, modify, and/or distribute this software for any
purpose with or without fee is hereby granted, provided that the above
copyright notice and this permission notice appear in all copies.
THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
Special thanks to:
- Groq - For providing lightning-fast LLaMA inference
- GitHub - For comprehensive API and OAuth support
- BullMQ - For robust job queue management
- Render - For reliable and simple deployment
- Vercel - For seamless frontend hosting
- Open Source Community - For the amazing tools and libraries
- π Bug Reports: GitHub Issues
- π¬ Discussions: GitHub Discussions
- π§ Email: [email protected]
- π¦ Twitter: @daemondoc_ai
- Multi-language README generation (ES, FR, DE, ZH)
- Custom README templates
- README preview before committing
- Dark mode support
- GitLab integration
- Bitbucket support
- Team collaboration features
- Analytics dashboard
- API documentation auto-generation
- Changelog auto-generation
- Code comment analysis
- Integration with Notion/Confluence
- VS Code extension
- CLI tool
- Self-hosted version
- Enterprise features