Contribution Hub API

A unified API for aggregating developer contributions across multiple platforms

• About The Project
• Architecture
• Getting Started
  • Prerequisites
  • Installation
• Usage
  • Authentication
  • API Endpoints
• Roadmap
• Contributing
• License
• Contact

(back to top)

ContributionAPI is a powerful microservices-based platform that aggregates developer contributions from multiple sources including GitHub, Azure DevOps, and other development platforms. It provides a unified API interface to retrieve comprehensive contribution data, enabling developers and organizations to get a holistic view of coding activity across different platforms.

• Multi-Platform Aggregation: Seamlessly combines contributions from GitHub, Azure DevOps, and more
• Microservices Architecture: Scalable and maintainable service-oriented design
• Firebase Integration: Secure user data storage and management
• Secret Management: Secure API key and token management
• Rich Data: Detailed contribution breakdowns including commits, pull requests, and work items
• High Performance: Optimized caching and concurrent data fetching
• Secure: Token-based authentication with read-only access patterns

(back to top)

ContributionAPI follows a microservices architecture pattern.

---
title: Contribution Hub - CI/CD & VPS Deployment Architecture
---

graph TB
    %% CI/CD Pipeline
    subgraph "CI/CD Pipeline - GitHub Actions"
        GA[GitHub Actions] --> GB[Build Docker Images]
        GB --> GC[Push to GHCR]
        GC --> GD[SSH Deploy to VPS]
    end
    
    %% CI/CD Flow
    GD -.-> |Deploy via SSH| VPS
    GC -.-> |Push Images| GHCR
    GHCR -.-> |Pull Images| VPS
    
    %% Users & Domain
    U[Users] --> CD[chm.proxzima.dev]
    CD --> CR[Caddy Server]

    %% VPS Deployment Infrastructure
    subgraph "VPS Deployment / Caddy Reverse Proxy + TLS"
        subgraph "Docker Compose Services"
            subgraph "Frontend Container"
                FR[Frontend App<br/>contribution-manager-app]
                FR -.-> |Token Management| J2[Token Management UI]
                FR -.-> |User Management| J1[User Registration/Login]
            end
            subgraph "Backend Containers"
                C[Contribution.Hub API<br/>backend-hub]
                D[Provider Factory]
                E[Contribution.AzureDevOps API<br/>backend-azuredevops]
                F[Contribution.GitHub API<br/>backend-github]
                G[Contribution.Provider API<br/>backend-provider]
                DB[Valkey Cache]
            end
        end
    end
    
    %% External APIs
    E ---> K1
    F ---> K2
    G ---> K3

    C --> D
    D --> E
    D --> F
    D --> G
    CR --> |"/_api/az/* → backend-azuredevops:5000"| E
    CR --> |"/_api/gh/* → backend-github:5000"| F
    CR --> |"/_api/provider/* → backend-provider:5000"| G
    CR --> |"/_api/* → backend-hub:5000"| C
    CR --> |"/ → frontend:3000"| FR
    E --> DB
    F --> DB
    G --> DB
    
    %% Data Access
    C --> I
    C --> H
    
    %% Application Logic Flow
    J2 -.-> I[Google Secret Manager]
    J2 -.-> H
    J1 -.-> H[Firebase Firestore]
    
    %% External Services
    subgraph "External Services"
        K1[Azure DevOps API SDK]
        K2[GitHub GraphQL API]
        K3[Future APIs]
        subgraph "Data & Security Layer"
            H
            I
        end
        subgraph "Container Registry"
            GHCR[GitHub Container Registry<br/>ghcr.io/proxzima/*]
        end
    end
    
    %% Styling
    classDef frontend fill:#e3f2fd,stroke:#1976d2,color:#000
    classDef api fill:#ede7f6,stroke:#7b1fa2,color:#000
    classDef infrastructure fill:#e8f5e9,stroke:#388e3c,color:#000
    classDef data fill:#fff8e1,stroke:#f57c00,color:#000
    classDef external fill:#fce4ec,stroke:#c2185b,color:#000
    classDef cicd fill:#f3e5f5,stroke:#8e24aa,color:#000
    
    class FR,J1,J2 frontend
    class B2,C,D,F,E,G,DB api
    class CD,CR,VPS,GHCR infrastructure
    class H,I data
    class K1,K2,K3 external
    class GA,GB,GC,GD cicd

(back to top)

Follow these steps to get ContributionAPI running locally.

• .NET 9.0 SDK
• Git
• Firebase project with Firestore enabled (Optional)
• Google Cloud project with Secret Manager enabled (Optional)

1. Clone the repository

   git clone https://github.com/PROxZIMA/ContributionAPI.git
   cd ContributionAPI

2. Set up Firebase credentials (Optional)

   # Download your Firebase service account key
   # Place it in src/Contribution.Hub/firebase-credentials.json

3. Configure Google Cloud credentials (Optional)

   # Set up Application Default Credentials
   gcloud auth application-default login
   
   # Or set the environment variable
   export GOOGLE_APPLICATION_CREDENTIALS="path/to/your/service-account-key.json"

4. Configure application settings (Optional)

   # Copy and modify configuration files
   cp src/Contribution.Hub/appsettings.Development.json.example src/Contribution.Hub/appsettings.Development.json
   
   # Edit the configuration with your Firebase project details

5. Restore dependencies and build

   dotnet restore
   dotnet build

6. Run the services

   Option A: Run all services together

   # From VS Code, use the "Run Contribution API" task
   # Or run individually:

   Option B: Run services individually

   # Terminal 1 - Hub Service
   cd src/Contribution.Hub
   dotnet run
   
   # Terminal 2 - Azure DevOps Service
   cd src/Contribution.AzureDevOps
   dotnet run
   
   # Terminal 3 - GitHub Service
   cd src/Contribution.GitHub
   dotnet run

7. Verify installation

   curl http://localhost:5298/health

(back to top)

ContributionAPI uses read-only tokens for secure access to external services.

GitHub Personal Access Token:

1. Go to GitHub Settings → Developer settings → Personal access tokens
   • Or visit https://github.com/settings/tokens/new?scopes=read:user
2. Generate new token (classic) with these scopes:
   • read:user (Read ALL user profile data)

Azure DevOps Personal Access Token:

1. Go to Azure DevOps → User Settings → Personal access tokens
2. Create new token with these permissions:
   • Code: Read
   • Identity: Read
   • Work Items: Read

• Reference: Contribution Hub Manager for existing endpoints and usage.

For detailed API documentation, visit the Swagger UI at http://localhost:5298/swagger when running locally.

(back to top)

• GitHub integration
• Azure DevOps integration
• Firebase Firestore data storage
• Google Secret Manager integration
• Basic contribution aggregation
• RESTful API endpoints

• Support SVG endpoint for contribution graphs
• Support PNG endpoint for contribution graphs
• Add provider specific breakdown
• Set up CI/CD via GitHub Actions to VPS using Docker for hosting

• GitLab integration
• Template for new Providers API
• Bitbucket integration
• Advanced analytics and insights
• GraphQL API support (optional)
• Persistent caching strategies
  • Key-based caching
  • Serve last cache
  • Intelligent cache refresh based on usage
  • Environment based caching configuration

• Real-time contribution streaming
• Machine learning-powered insights
• Team and organization support
• Advanced reporting and dashboards
• Plugin architecture for custom providers

• Jira integration
• Stack Overflow integration
• LinkedIn integration
• Custom provider framework
• Enterprise SSO support

See our Issues page to request features or report bugs.

(back to top)

We welcome contributions from the community! ContributionAPI is an open-source project, and we appreciate any help to make it better.

Please read CONTRIBUTING.md for detailed guidelines.

This project follows our Code of Conduct. By participating, you agree to uphold this code.

Distributed under the MIT License. See LICENSE for more information.

• grubersjoe/react-github-calendar
• grubersjoe/github-contributions-api

PROxZIMA - @PROxZIMA

• Project Repository: https://github.com/PROxZIMA/ContributionAPI
• Issue Tracker: https://github.com/PROxZIMA/ContributionAPI/issues

• Discussions: Use GitHub Discussions for community support
• Bug Reports: Use our issue templates for bug reports
• Feature Requests: Submit feature requests through GitHub Issues

(back to top)