Skip to content

bayue48/gitSdm

BranchesTags

Repository files navigation

gitSdm (Git Software Dependency Map v1.0.0)

AI-Powered Repository Intelligence & Architecture Visualization Platform

TypeScript React Vite License PRs Welcome Build

Repository Graph

✨ Overview

gitSdm transforms how developers understand unfamiliar codebases. Instead of spending hours reading through files and tracing dependencies, gitSdm provides instant, interactive architecture visualization powered by AI.

"The kind of deep insight that normally takes days of reading code — delivered in seconds."

🎯 Value Proposition

Problem Solution
🕒 Hours spent onboarding to new repos ⚡ Instant architecture overview
🔍 Manual dependency tracing 🕸️ Interactive dependency graph
📚 Scattered documentation 🤖 AI-generated code explanations
🧩 Unclear module boundaries 🎯 Visual file classification

🏗️ Architecture

gitSdm/
├── 📁 api/                    # Vercel serverless functions
├── 📁 server/                 # Backend services & router
│   ├── ai/                    # AI provider, prompt & task handlers
│   ├── cache/                 # LRU caching layer
│   ├── config/                # App configuration & env validation
│   ├── github/                # GitHub API client
│   ├── graph/                 # Graph building & layout algorithms
│   ├── parser/                # Dependency & file analysis
│   ├── router/                # Modular backend routers (AI, repo, search)
│   ├── search/                # Semantic search, embeddings & QA engine
│   ├── services/              # Business logic layer
│   └── utils/                 # HTTP, logging utilities
├── 📁 src/                    # Frontend application
│   ├── app/                   # App providers & routing
│   ├── components/            # UI components
│   │   ├── explorer/          # File explorer & code inspector dock
│   │   ├── home/              # Modular landing page sections
│   │   ├── ui/                # shadcn/ui primitives & styling wrapper
│   │   └── viz/               # Visual workspace modules
│   │       ├── ai-sidebar/    # Context-aware chat tabs & tools
│   │       ├── architecture/  # Mermaid configs & interactive generators
│   │       ├── layout/        # Viz sidebar & workspace layout
│   │       ├── learning-path/ # Code learning simulation player
│   │       └── top-nav/       # Branch switcher & stats menus
│   ├── features/              # Feature modules
│   │   ├── ai/                # AI task integration hooks
│   │   └── graph/             # Graph rendering, styles & layout worker
│   │       └── canvas/        # ReactFlow & D3-force engines
│   │           └── force/     # Custom D3 minimap & canvas painters
│   ├── hooks/                 # Custom React hooks
│   ├── lib/                   # Shared API client & utilities
│   ├── pages/                 # Route-level page components
│   ├── stores/                # Zustand global stores (e.g. vizStore)
│   ├── styles/                # Tailwind CSS global styles
│   └── types/                 # TypeScript definitions
├── 📁 public/                 # Static assets (including layout worker)
└── 📁 .agents/                # AI agent configurations

🚀 Quick Start

Prerequisites

  • Bun >= 1.1 (recommended runtime and package manager)
  • Node.js >= 22 (alternative backend support)
  • GitHub Personal Access Token (for API access)

Installation

# Clone the repository
git clone https://github.com/bayue48/gitSdm.git
cd gitSdm

# Install dependencies
bun install

# Copy environment variables
cp .env.example .env

Environment Configuration

Variable Description
GITHUB_TOKEN Optional. Increases GitHub API rate limits for public repos
AI_PROVIDER mock (default), gemini,openai, or anthropic
OPENAI_API_KEY Required when AI_PROVIDER=openai
ANTHROPIC_API_KEY Required when AI_PROVIDER=anthropic
GEMINI_API_KEY Required when AI_PROVIDER=gemini
GEMINI_MODEL Optional when AI_PROVIDER=gemini; defaults to gemini-2.5-flash
GEMINI_API_VERSION Optional when AI_PROVIDER=gemini; defaults to v1alpha
OPENAI_MODEL Optional when AI_PROVIDER=openai; defaults to gpt-4o-mini
ANTHROPIC_MODEL Optional when AI_PROVIDER=anthropic; defaults to claude-3-5-haiku-latest

Development

# Start development server
bun dev

Production Build

# Build for production
bun run build

# Preview production build
bun run preview

Docker Deployment

The Docker image builds the Vite app, bundles a small Node server, serves static files from dist/, and handles /api/* using the same API router as development/Vercel.

# Build Docker image
docker build -t gitsdm .

# Run container
docker run -p 3000:3000 --env-file .env gitsdm

For minimal setup, GITHUB_TOKEN is optional but recommended. AI features use AI_PROVIDER=mock by default; set the matching API key when using gemini, openai, or anthropic.

Google Cloud Run

# Deploy directly from source
gcloud run deploy gitsdm \
  --source . \
  --region asia-southeast1 \
  --allow-unauthenticated \
  --env-vars-file .env

🧩 Core Features

🔬 Repository Analysis

  • Instant parsing of any public GitHub repository
  • Dependency graph generation with d3-force and dagre layout algorithms
  • File classification by type (component, utility, config, etc.)
  • Module boundary detection for architectural insights

🤖 AI-Powered Insights

  • Architecture summaries via Google Gemini, OpenAI, or Anthropic Claude
  • Code explanations for specific files and modules in Standard and ELI5 (Explain It Like I'm 5) modes
  • Smart file suggestions based on context
  • Learning paths for onboarding to new codebases

🕸️ Interactive Visualization

  • Force-directed graphs with @xyflow/react (React Flow)
  • Real-time filtering by file type, module, or dependency
  • Branch comparison with visual diff
  • High-resolution exports to PNG and PDF for dependency maps
  • Interactive Mermaid flowcharts with SVG and PNG download support

📊 Repository Intelligence

  • Contributor analytics with recharts visualizations
  • Commit timeline and activity patterns
  • Trending repositories discovery
  • File explorer with syntax highlighting via highlight.js
  • Dynamic presets that automatically adjust based on active AI provider configurations

🛠️ Technology Stack

Frontend

Technology Purpose
React 19 UI framework
TypeScript 5.8 Type safety
Vite 6 Build tooling
@xyflow/react 12 Graph visualization
Framer Motion 12 Animations
TanStack React Query 5 Data fetching
Tailwind CSS 4.0 Styling
shadcn/ui 4 Component primitives
Recharts 2 Charts & analytics
Mermaid 11 Diagram generation
html-to-image Element/SVG to image conversion
jsPDF PDF generation library
Lucide React Icon library

Backend

Technology Purpose
Node.js 22 Runtime
Express (via Vercel) API server
Octokit 21 GitHub API client
LRU Cache 11 Response caching
Google GenAI 2.6 AI provider
OpenAI 4 AI provider
Anthropic SDK 0.39 AI provider

Infrastructure

Technology Purpose
Google Cloud Run Deployment platform
Docker Containerization
Bun Package management
Bun Test Testing framework
ESLint 9 Code quality

📖 Usage Guide

1. Analyze a Repository

Enter a GitHub URL → gitSdm fetches & parses → Interactive graph appears

2. Explore Architecture

Click nodes → View file contents → Trace dependencies → Understand modules

3. Get AI Insights

Select "Explain Architecture" → AI analyzes structure → Natural language summary

4. Compare Branches

Select branches → Visual diff → See architectural changes

🧪 Testing

# Run all tests
bun test

# Run with coverage
bun run test:coverage

# Watch mode
bun run test:watch

Test files are co-located with source files (25 test suites):

  • server/ai/provider.test.ts
  • server/ai/service.test.ts
  • server/cache/lru.test.ts
  • server/config/app-config.test.ts
  • server/github/client.test.ts
  • server/github/fetch-tree.test.ts
  • server/github/mock-data.test.ts
  • server/github/parse-url.test.ts
  • server/graph/graph-builder.test.ts
  • server/graph/layout.test.ts
  • server/parser/dependency-analyzer.test.ts
  • server/parser/file-classifier.test.ts
  • server/parser/import-resolver.test.ts
  • server/parser/manifest-parsers/index.test.ts
  • server/search/chunker.test.ts
  • server/search/constants.test.ts
  • server/search/embedding-provider.test.ts
  • server/search/qa-engine.test.ts
  • server/search/search-engine.test.ts
  • server/search/vector-store.test.ts
  • server/services/analyze-repo.test.ts
  • server/services/get-file.test.ts
  • server/services/trending.test.ts
  • server/utils/errors.test.ts
  • server/utils/logger.test.ts

🗺️ Roadmap

Planned Features

  • AI-generated architecture diagrams — High-quality Mermaid flowcharts detailing module boundaries and system workflows.
  • Commit History & Activity — Interactive timeline visualizing author patterns and directory churn over time.
  • Export to PDF / PNG / SVG — High-res canvas snapshots and vector diagram outputs for documentation.
  • Private repository support — Secure OAuth authentication and credential storage to map private codebases.
  • Monorepo-aware dependency grouping — Automatic workspace detection (npm/pnpm/yarn) and cross-package mapping.
  • AI-powered semantic search & Q&A — Context-aware vector search to ask code questions and locate entry points. (Beta)
  • Change impact analysis (Blast Radius) — Visualizer highlighting transitive dependents to predict edit breakages.
  • CI/CD integration — GitHub Action to automatically comment visual architecture diffs on PR updates.
  • Interactive path pruning & editing — Tools to manually prune/group nodes and export tailored subgraphs.
  • Multi-repository mapping — Cross-repo mapping to trace frontend-to-backend API and SDK dependencies.

🤝 Contributing

We welcome contributions! See our contributing guidelines for details.

  1. Fork the repository
  2. Create your feature branch (git checkout -b feature/amazing-feature)
  3. Commit your changes (git commit -m 'Add amazing feature')
  4. Push to the branch (git push origin feature/amazing-feature)
  5. Open a Pull Request

Contribution Ideas

  • Improve graph rendering performance
  • Add new AI providers
  • Improve parser accuracy
  • Create better onboarding flows
  • Enhance repository analytics

🔒 Security

  • API keys are never exposed to the client
  • Environment variables are securely handled
  • Rate limiting prevents abuse
  • GitHub API access follows OAuth best practices

If you discover a vulnerability, please open a private security report.

📄 License

This project is licensed under the MIT License.

See the LICENSE file for more information.

About

AI-powered repository intelligence and architecture visualization platform that helps developers instantly understand unfamiliar GitHub repositories through interactive graphs and AI-generated insights.

gsdm.site

Topics

juaravibecoding juara-vibecoding juara-vibe-coding

Resources

Readme

License

MIT license

Contributing

Contributing
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages