⭐ StarWise

<img src="./logo.PNG" alt="StarWise Logo" width="120" height="120"> Important: Check out the <a href="https://github.com/hamzamix/StarWise/releases/tag/1.2.0">v1.2.0 release notes</a> Organize your GitHub Stars with AI-powered tagging Transform your scattered GitHub stars into an organized, searchable knowledge base using the power of Google Gemini AI. <a href="#features">Features</a> • <a href="#quick-start">Quick Start</a> • <a href="#installation">Installation</a> • <a href="#docker">Docker</a> • <a href="#contributing">Contributing</a>

✨ Features

🤖 AI-Powered Smart Tagging

Automatic Tag Generation: Uses Google Gemini AI to analyze repository metadata and generate relevant, technical tags
Background Processing: Tag generation runs in the background with real-time progress tracking
Rate Limit Handling: Automatically detects and handles API rate limits with pause/resume functionality
Progress Persistence: Resume tagging from where you left off after any interruption

📋 Powerful Organization

Custom Lists: Create and manage custom lists to categorize repositories
Advanced Filtering: Filter by language, repository type, tags, and more
Smart Search: Search across repository names, descriptions, and tags
Bulk Operations: Move repositories between lists and manage tags efficiently
Force Sync: Automatic sync when selecting "Recently Active" filter for up-to-date data

🔐 Secure & Private

GitHub OAuth: Secure authentication using your GitHub account
Local Data Storage: All your data stays on your machine
API Key Security: Environment-based configuration for API keys

🎨 Modern Interface

Dark/Light Theme: Beautiful themes that adapt to your preference
Responsive Design: Works perfectly on desktop and mobile
Material-UI Components: Clean, modern interface built with Material-UI
Real-time Updates: Live progress tracking and instant feedback
Version Management: Built-in version display with update notifications

📸 Screenshots

home 1 Starwise logo

home 2 Starwise logo

lists Starwise logo

Backups Starwise logo

Insights Starwise logo

Settings Starwise logo

Share Stack

🚀 Quick Start

Option 1: Docker (Recommended)

Clone the repository:

git clone https://github.com/yourusername/starwise.git
cd starwise

Set up environment variables:

cp backend/.env.example backend/.env
# Edit backend/.env with your API keys (see setup guide below)

Run with Docker:
```
docker-compose up --build
```
Open your browser: Navigate to http://localhost:4000

Option 2: Local Development

Install dependencies:

npm install
cd backend && npm install && cd ..

Set up environment variables:

cp backend/.env.example backend/.env
# Edit backend/.env with your API keys

Start the backend:
```
cd backend && npm start
```
Start the frontend (new terminal):
```
npm run dev
```
Open your browser: Navigate to http://localhost:5173

🛠 Installation

Prerequisites

Node.js (v18 or later)
npm or yarn
Docker (optional, for Docker setup)
GitHub account
Google AI Studio API Key

1. GitHub OAuth Setup

Create a GitHub OAuth application to enable authentication:

For Local Development

Go to GitHub Settings → Developer settings → OAuth Apps
Click New OAuth App
Fill in the details:
- Application name: StarWise (Development)
- Homepage URL: http://localhost:5173
- Authorization callback URL: http://localhost:4000/auth/github/callback
Save your Client ID and Client Secret

For Docker Deployment

Create another OAuth App (or update the existing one):
- Application name: StarWise (Docker)
- Homepage URL: http://localhost:4000 ⚠️ Important: Use port 4000 for Docker
- Authorization callback URL: http://localhost:4000/auth/github/callback
Use the same Client ID and Client Secret in your .env file

💡 Port Explanation:

Local Development: Frontend runs on port 5173, backend on port 4000

Docker Deployment: Both frontend and backend run on port 4000 in a single container

OAuth Setup: Always use port 4000 for the callback URL, but Homepage URL differs based on deployment method

2. Google AI API Setup

Visit Google AI Studio
Create a new API key
Save your API key securely

3. Environment Configuration

Create backend/.env with your credentials:

# GitHub OAuth (from step 1)
GITHUB_CLIENT_ID=your_github_client_id
GITHUB_CLIENT_SECRET=your_github_client_secret
GITHUB_CALLBACK_URL=http://localhost:4000/auth/github/callback

# Google Gemini AI (from step 2)
API_KEY=your_google_ai_api_key

# Security
SESSION_SECRET=generate_a_long_random_string_here

# Server Configuration
PORT=4000

# AI Provider API Keys
OPENROUTER_API_KEY=
OPENAI_API_KEY=
ANTHROPIC_API_KEY=
DEFAULT_AI_PROVIDER=

🐳 Docker

StarWise includes full Docker support for easy deployment with secure environment variable handling:

📊 Port Configuration Summary

| Deployment Method | Frontend Port | Backend Port | Access URL | GitHub OAuth Homepage URL | |-------------------|---------------|--------------|------------|---------------------------| | Local Development | 5173 | 4000 | http://localhost:5173 | http://localhost:5173 | | Docker | 4000 | 4000 | http://localhost:4000 | http://localhost:4000 |

🔒 Security Note

For security, API keys are never hardcoded in the Docker Compose files. Instead, they're loaded from your local .env file or system environment variables.

Development Deployment

Ensure your .env file exists:

cp backend/.env.example backend/.env
# Edit backend/.env with your actual API keys

Update GitHub OAuth App:
- Set Homepage URL to http://localhost:4000
- Keep Callback URL as http://localhost:4000/auth/github/callback
Run with Docker Compose:
```
docker-compose up --build
```
This uses env_file: backend/.env to securely load your environment variables.
Access the application: Navigate to http://localhost:4000

Production Deployment

For production, use environment variables from your deployment platform:

# Set environment variables in your deployment platform (Heroku, DigitalOcean, etc.)
export GITHUB_CLIENT_ID="your_actual_client_id"
export GITHUB_CLIENT_SECRET="your_actual_secret"
export API_KEY="your_actual_api_key"
export SESSION_SECRET="your_secure_session_secret"

# AI Provider API Keys
OPENROUTER_API_KEY=
OPENAI_API_KEY=
ANTHROPIC_API_KEY=
DEFAULT_AI_PROVIDER=

# Then deploy with production compose file
docker-compose -f docker-compose.prod.yml up --build

Docker Files Explained

docker-compose.yml - Development setup, loads from backend/.env file
docker-compose.prod.yml - Production setup, uses system environment variables
dockerfile - Multi-stage build with verification steps

Environment Variables Loading Order

Development: backend/.env file → Docker container
Production: System environment variables → Docker container
Fallbacks: Default values for non-sensitive settings (like PORT=4000)

🏗 Technology Stack

Frontend: React 18 + TypeScript + Vite + Material-UI
Backend: Node.js + Express.js + Passport (GitHub OAuth)
AI: Google Gemini API
Deployment: Docker + Docker Compose
Styling: Material-UI with dark/light theme support

🤝 Contributing

We welcome contributions! StarWise is built with ❤️ for the developer community.

How to Contribute

Fork the repository
Create a feature branch: git checkout -b feature/amazing-feature
Make your changes
Test thoroughly
Commit: git commit -m 'Add amazing feature'
Push: git push origin feature/amazing-feature
Open a Pull Request

Areas for Contribution

🎨 UI/UX improvements
🔧 Additional AI providers (OpenAI, Claude, etc.)
📊 Analytics and insights features
🔍 Enhanced search and filtering
🌐 Internationalization
📱 Mobile app development
🧪 Testing improvements

📝 License

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

💝 Support

If StarWise helps you organize your GitHub stars, consider:

⭐ Starring this repository
🐛 Reporting bugs via Issues
💡 Suggesting features via [Discussio

StarWise

Install / Use

README