🕸️ GitStars Map - Retro OS Edition v1.0

A nostalgic 90s-2000s desktop operating system environment (styled like Windows 95/98) running inside the browser to explore and map your GitHub Stars, resembling Obsidian's force-directed graph view.

⚡ Try it online! Link your read-only token and explore your stars instantly: git-starmap.vercel.app ⚡

Features • Security Architecture • How It Works • Getting Started • Tech Stack

---

🚀 Features

• 📺 Nostalgic CRT Monitor Shader: CSS-driven scanlines, vignetting, phosphor glowing, and subtle flicker filters that can be toggled on/off via the taskbar tray.
• 🪟 Draggable Retro Windows: Multiple windows for Settings, Help, Mind Map Graph, and Properties. Windows support dragging, Z-index focusing, and minimizing.
• 🔊 Real-time 8-Bit Audio Synthesis: Dynamic micro-beeps synthesized on the fly using the Web Audio API (success chirps, error buzzes, click responses, and floppy drive seek clicks during loading).
• 🤖 Universal Client-Side AI Router: Connects directly from your browser to:
  • Google Gemini API (Free Tier supported natively via AI Studio)
  • OpenRouter (Aggregated access to free and cheap models)
  • OpenAI (GPT-4o-mini, custom URLs)
  • Groq (Llama 3)
  • Custom Endpoints (e.g., Ollama or custom API proxies)
• 🛡️ 100% Billing Protection: Built-in Local Rate Limiter Security Guard checks counts in localStorage and client-side blocks requests exceeding 15/min or 1500/day. Standard free-tier Google AI Studio accounts will return HTTP 429 (Too Many Requests) rather than rolling over to billing.
• 🕸️ Obsidian-Style Mind Map: Interactive Canvas 2D force-directed graph rendering repo and category nodes. Stars are sized logarithmically by star counts and color-coded by programming language, connected with animated data stream particles.

---

📸 Screenshots & Artwork

---

🔒 Security-First Architecture

We take privacy and API billing security seriously:

1. Zero Server Backend: No databases, no proxy servers. All API key variables are entered by visitors, saved in their browser's private localStorage, and executed directly to GitHub/Google endpoints.
2. No Hardcoded Keys: Your source code is 100% clean of API keys. No secrets are committed or stored on servers.
3. Local Rate Limiting Guard: Even if your API keys are loaded, the browser strictly rate-limits requests to protect you from unexpected bill spikes or API bans.

---

🕹️ How It Works

graph TD
    User([User's Browser]) --> OS[Retro OS Environment]
    OS --> Graph[Canvas Force Graph Node Mapping]
    OS --> Sounds[Web Audio API sound synthesis]
    OS --> Shader[CRT Post-processing Shader]
    OS --> Guard[Security Guard Rate Limiter]
    
    Guard --> Router[Universal Client AI Router]
    Router --> |Direct Client Call| Gemini[Google Gemini API]
    Router --> |Direct Client Call| OpenRouter[OpenRouter API]
    Router --> |Direct Client Call| OpenAI[OpenAI API]
    Router --> |Direct Client Call| Groq[Groq API]
    
    OS --> |Direct Client Call| GitHub[GitHub API]
    
    subgraph Browser Storage
        Keys[localStorage: API Keys]
        Cache[localStorage: Star Data & Limits]
    end
    
    OS -.-> Keys
    Guard -.-> Cache

Loading

---

📦 Getting Started

Prerequisites

You will need:

1. Node.js (v18+)
2. Google Gemini API Key (optional, but needed for AI mapping): Get one for free at Google AI Studio.
3. GitHub PAT (optional, recommended): Generate a read-only token for public scopes on GitHub Settings.

Running Locally

1. Clone or navigate to the directory:

   git clone https://github.com/yourusername/github-stars-visualizer.git
   cd github-stars-visualizer

2. Install dependencies:

   npm install

3. Launch the development server:

   npm run dev

4. Run unit tests (TDD suite):

   npm test

---

🏗️ Technical Stack

• UI Framework: React 19 + Vite 8
• Graph Renderer: Canvas-based force-graph
• Styling: Vanilla CSS (retro custom bevels & layouts)
• Test Suite: Vitest (15 unit tests verifying rates, routers, and graph builders)
• Sound Synth: Native HTML5 Web Audio API

---

🤝 Contributing

We welcome contributions! Please read our Contributing Guidelines to get started on setting up the local dev environment, styling specifications, and TDD workflow instructions.

---

💎 Credits & Open Source Acknowledgements

This project was built possible by these fantastic open-source libraries, assets, and inspirations:

• Frontend & Tooling: React 19, Vite 8, ESLint
• Data Visualization: force-graph (HTML5 Canvas) by Vasco Asturiano
• Visualization & Physics Inspirations:
  • The R Graph Gallery - Network Analysis
  • Flourish Studio - Network Charts
  • Gephi - Open Graph Viz Platform
  • RawGraphs
  • DAGitty - Directed Acyclic Graphs
• AI Integration: @google/generative-ai SDK
• Icons: Lucide React
• Testing Suite: Vitest 4
• Typography: Google Fonts: VT323 (nostalgic pixel font) and Google Fonts: Courier Prime (monospace console font)
• Visual Style & Retro Design: Classic Windows 95/98 styling and beveled theme designs.

---

📄 License

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