FollowMe

Automated GitHub repository discovery, NVIDIA NIM LLM evaluation, and intelligent developer community networking tool.

---

Overview & Dashboard

FollowMe continuously searches for recently created repositories across your tech stack, analyzes code snippets and READMEs with LLMs (NVIDIA NIM), filters for active peer builders (students, hobbyists, independent developers), automatically stars quality projects, and manages mutual connections with customizable grace periods.

---

Key Features

• AI Code & README Evaluation: Grades repositories on a scale of 1–10 using NVIDIA NIM & Groq LLMs with resilient JSON extraction tolerant to reasoning preamble (<think>) and codeblock wrappers.
• Smart Peer Targeting: Filters accounts based on follower ranges, account maturity, and organic follow ratios (stars high-profile developers instead of following).
• Persistent Evaluation Cache: Stores low-score and skipped repositories in Supabase with follow_skipped flags to prevent repeated re-evaluation and conserve LLM API credits.
• Live GitHub Rate Limit Monitor: Real-time Core API and Search API quota tracking with dynamic progress bars and $<20%$ remaining alert thresholds.
• Automated Grace Period & Cleanup: Configurable non-followback grace period (default 7 days), manual follow protection, and mutual sync engine.
• Autonomous Interval Scheduling: Worker service features built-in periodic scheduling with dynamic next-run time estimation and on-demand trigger support.
• Dedicated Console Views: Dedicated pages for /profiles, /repositories, /logs, and /?tab=stats with search, filters, and paginated tables.
• Dual Authentication & Middleware: Master password login, one-click GitHub OAuth authentication, and Next.js middleware route protection.
• Loud Quota Alerts: Immediate fatal alerting to database logs on AI API key exhaustion or rate limit walls.

---

Architecture

┌────────────────────────────────────────────────────────┐
│                   GitHub Ecosystem                     │
│  (Repo Search, User Profiles, Follow/Star API, OAuth)  │
└───────────────────────────┬────────────────────────────┘
                            │
              ┌─────────────┴─────────────┐
              ▼                           ▼
┌───────────────────────────┐   ┌───────────────────────────┐
│     Background Worker     │   │      Next.js Console      │
│  (Node.js / Express API)  │   │  (Dashboard UI & Actions) │
└─────────────┬─────────────┘   └─────────────┬─────────────┘
              │                               │
              ├───────────────┬───────────────┤
              ▼               ▼               ▼
┌──────────────────┐ ┌─────────────────┐ ┌──────────────────┐
│    NVIDIA NIM    │ │ Supabase DB     │ │  GitHub Actions  │
│  (LLM Evaluator) │ │ (PostgreSQL)    │ │   (Scheduler)    │
└──────────────────┘ └─────────────────┘ └──────────────────┘

---

Before You Begin

Note

The /demo folder in this repository contains seed/mock data used for the reference demo deployment. It is not required for your own self-hosted instance and can safely be removed or ignored.

---

Quick Start (Docker Compose)

The easiest way to run the complete FollowMe stack (Worker + Dashboard) locally or on a VPS is with Docker Compose:

1. Clone the repository:

   git clone https://github.com/madhanio/followme.git
   cd followme

2. Configure environment variables:

   cp .env.example .env

   Fill in your credentials in .env (Supabase, GitHub PAT, NVIDIA NIM key, master password).

3. Start services:

   docker compose up -d --build

4. Access Dashboard: Open http://localhost:3000 in your browser.

---

Cloud Self-Hosting Guide

1. Prerequisites & API Keys

Gather the following credentials before deployment:

• GitHub Personal Access Token (PAT): Create a token under GitHub Settings → Developer Settings → Personal Access Tokens. Required scopes: user:follow, public_repo, read:user.
• NVIDIA NIM API Key: Obtain a key at build.nvidia.com.
• Supabase Project: Create a project at supabase.com. Copy the Project URL, anon key, and service_role key from Project Settings → API.

Warning

Keep your secret keys secure and never commit .env files with real credentials to your git repository.

---

2. Database Setup (Supabase)

1. Open your Supabase project dashboard and navigate to SQL Editor.
2. Click New Query.
3. Copy the contents of schema.sql and click Run.

---

3. Deploy Background Worker (Render)

1. Create a new Web Service on Render and link your repository.
2. Set Root Directory to worker.
3. Configure the environment variables (see worker/.env.example):

PORT=8000
WORKER_SECRET=your_worker_secret_here
GITHUB_TOKEN=your_github_personal_access_token_here
GITHUB_USERNAME=your_github_username_here
NVIDIA_API_KEY=your_nvidia_api_key_here
SUPABASE_URL=https://your_supabase_url_here.supabase.co
SUPABASE_ANON_KEY=your_supabase_anon_key_here

4. Deploy the service and note your service URL (e.g. https://your-worker.onrender.com).

---

4. Deploy Dashboard Console (Vercel)

1. Import your repository into Vercel.
2. Set Root Directory to dashboard.
3. Configure the environment variables (see dashboard/.env.example):

NEXT_PUBLIC_SUPABASE_URL=https://your_supabase_url_here.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=your_supabase_anon_key_here
SUPABASE_SERVICE_ROLE_KEY=your_supabase_service_role_key_here
NEXT_PUBLIC_WORKER_URL=https://your-worker.onrender.com
WORKER_URL=https://your-worker.onrender.com
WORKER_SECRET=your_worker_secret_here
GITHUB_TOKEN=your_github_personal_access_token_here
GITHUB_USERNAME=your_github_username_here
DASHBOARD_PASSWORD=your_dashboard_password_here
NEXT_PUBLIC_APP_URL=https://your-dashboard.vercel.app

4. Click Deploy.

---

5. Configure Authentication (Choose One)

FollowMe supports two secure login methods for the web dashboard:

Option A: Password Login (Recommended — Simplest Setup)

The fastest path for self-hosters with zero third-party configuration:

1. In your dashboard environment variables (or .env), set DASHBOARD_PASSWORD:

   DASHBOARD_PASSWORD=your_secure_password_here

2. When opening your dashboard, enter this password to gain immediate access.

Option B: GitHub OAuth Login (Optional — One-Click Sign In)

If you prefer a seamless "Continue with GitHub" button on the login screen:

1. In GitHub, go to Settings → Developer Settings → OAuth Apps → New OAuth App.
2. Configure the OAuth App details:
   • Application Name: FollowMe Dashboard
   • Homepage URL: https://your-dashboard.vercel.app (or http://localhost:3000 for local Docker)
   • Authorization callback URL: https://your-dashboard.vercel.app/api/auth/callback/github (or http://localhost:3000/api/auth/callback/github)
3. Click Register application, copy your Client ID, and generate a Client Secret.
4. Add these to your dashboard environment variables:

   GITHUB_CLIENT_ID=your_github_oauth_client_id_here
   GITHUB_CLIENT_SECRET=your_github_oauth_client_secret_here
   NEXT_PUBLIC_APP_URL=https://your-dashboard.vercel.app

Note

When signing in via GitHub OAuth, FollowMe verifies your GitHub username against GITHUB_USERNAME to ensure only you can access the dashboard.

---

6. Automated CRON Execution (GitHub Actions)

1. In your GitHub repository, navigate to Settings → Secrets and variables → Actions.
2. Add the following repository secrets:
   • WORKER_URL: https://your-worker.onrender.com/run
   • WORKER_SECRET: The shared worker secret string.
3. Enable workflows under the Actions tab. The discovery job runs every 6 hours automatically.

---

Environment Variables Reference

Variable	Required By	Description
GITHUB_TOKEN	Worker & Dashboard	GitHub Personal Access Token (read:user, user:follow, public_repo)
GITHUB_USERNAME	Worker & Dashboard	Your GitHub username for account locking and mutual sync
NVIDIA_API_KEY	Worker	API Key from build.nvidia.com for LLM grading
SUPABASE_URL	Worker & Dashboard	Supabase PostgreSQL project URL
SUPABASE_ANON_KEY	Worker & Dashboard	Supabase public anonymous API key
SUPABASE_SERVICE_ROLE_KEY	Dashboard	Supabase service role key for settings and logs management
WORKER_SECRET	Worker & Dashboard	Shared secret header (x-worker-secret) to protect API endpoints
DASHBOARD_PASSWORD	Dashboard	Master password for dashboard web console
GITHUB_CLIENT_ID	Dashboard	Optional GitHub OAuth Application Client ID
GITHUB_CLIENT_SECRET	Dashboard	Optional GitHub OAuth Application Client Secret
NEXT_PUBLIC_APP_URL	Dashboard	Production dashboard URL for OAuth redirects

---

License

Distributed under the MIT License.