Skip to content

EQUITY_SYSTEM_DOCS.md

Latest commit

 

History

History
734 lines (556 loc) · 16.2 KB

EQUITY_SYSTEM_DOCS.md

File metadata and controls

734 lines (556 loc) · 16.2 KB

🏆 GitForge Equity Tracking & Automation System

Complete Documentation

📋 Table of Contents

  1. Overview
  2. Features
  3. Architecture
  4. Setup Guide
  5. Usage
  6. Automation Workflows
  7. Dashboard & Analytics
  8. Notifications
  9. API Reference
  10. Troubleshooting

🎯 Overview

The GitForge Equity Tracking & Automation System is a comprehensive solution for managing equity distribution, tracking contributor performance, and automating bounty workflows. Built entirely on GitHub Actions and native web technologies, it provides:

  • Real-time equity tracking with automatic updates
  • Live dashboards with beautiful data visualizations
  • Automated notifications via Discord, Twitter, and email
  • Professional analytics and reporting
  • Mobile-responsive design for access anywhere

✨ Features

Core System

🔄 Real-time Equity Tracker

  • Automatic equity allocation on PR merge
  • Live cap table management
  • Contributor equity history
  • Bounty completion tracking

📊 Live Dashboard

  • Beautiful data visualizations using Chart.js
  • Contributor leaderboard with rankings
  • Bounty completion metrics
  • Mobile-responsive design
  • Real-time updates

🤖 Automation Engine

  • Auto-updates on bounty completions
  • Discord/Twitter notifications
  • Weekly progress reports
  • Contributor achievement badges
  • Email notifications

📈 Professional Reporting

  • Equity distribution charts (SVG)
  • Contributor performance analytics
  • Bounty completion statistics
  • Exportable reports (JSON, CSV, Markdown)
  • Time-series analysis

🏗️ Architecture

System Components

GitForge Equity System
│
├── GitHub Actions Workflows
│   ├── equity-tracker.yml       # Main tracking workflow
│   ├── notifications.yml        # Notification system
│   └── analytics-update.yml     # Analytics generation
│
├── Automation Scripts
│   ├── generate-dashboard.js    # Dashboard generation
│   ├── generate-charts.js       # Chart/visualization generation
│   ├── generate-analytics.js    # Analytics calculation
│   ├── weekly-report.js         # Weekly report generation
│   └── post-to-twitter.js       # Twitter integration
│
├── Data Storage
│   ├── EQUITY_TRACKING.json     # Main equity data
│   ├── BOUNTY_CONFIG.json       # Bounty configuration
│   └── analytics/               # Generated analytics
│
└── Frontend
    ├── dashboard.html           # Main dashboard
    ├── analytics.html           # Advanced analytics
    └── assets/charts/           # Generated charts

Data Flow

PR Merged → Workflow Triggered → Equity Updated → Dashboard Generated → Notifications Sent
                                        ↓
                                  Analytics Updated
                                        ↓
                                  Charts Generated

🚀 Setup Guide

Prerequisites

  • GitHub repository with Actions enabled
  • Node.js 20+ (for local testing)
  • Optional: Discord webhook URL
  • Optional: Twitter API credentials

Step 1: Copy Files

Copy all files from this system to your repository:

# Copy workflows
.github/workflows/equity-tracker.yml
.github/workflows/notifications.yml
.github/workflows/analytics-update.yml

# Copy scripts
.github/scripts/generate-dashboard.js
.github/scripts/generate-charts.js
.github/scripts/generate-analytics.js
.github/scripts/weekly-report.js
.github/scripts/post-to-twitter.js

# Copy data files
github/EQUITY_TRACKING.json
github/BOUNTY_CONFIG.json

# Copy dashboards
dashboard.html
analytics.html

Step 2: Configure Secrets

Add these secrets to your repository (Settings → Secrets and variables → Actions):

Required

  • GITHUB_TOKEN - Automatically provided by GitHub

Optional (for notifications)

  • DISCORD_WEBHOOK_URL - Your Discord webhook URL
  • TWITTER_API_KEY - Twitter API key
  • TWITTER_API_SECRET - Twitter API secret
  • TWITTER_ACCESS_TOKEN - Twitter access token
  • TWITTER_ACCESS_SECRET - Twitter access secret
  • NOTIFICATION_EMAIL - Email for notifications
  • MAIL_SERVER - SMTP server address
  • MAIL_PORT - SMTP port
  • MAIL_USERNAME - SMTP username
  • MAIL_PASSWORD - SMTP password

Step 3: Initialize Data

Edit github/EQUITY_TRACKING.json with your initial data:

{
  "total_equity_allocated": 0,
  "total_equity_available": 100,
  "bounties_completed": 0,
  "bounties_pending": 0,
  "last_updated": "2024-01-01T00:00:00Z",
  "contributors": [],
  "active_bounties": []
}

Step 4: Enable GitHub Pages

  1. Go to Settings → Pages
  2. Source: Deploy from a branch
  3. Branch: main / (root)
  4. Save

Your dashboards will be available at:

  • https://yourusername.github.io/yourrepo/dashboard.html
  • https://yourusername.github.io/yourrepo/analytics.html

💡 Usage

Creating a Bounty

  1. Create a new issue with the bounty label
  2. Include equity information in the issue body: 
    Equity: 3%
  3. The system will automatically track this bounty

Claiming a Bounty

Contributors can claim bounties by:

  1. Commenting on the issue
  2. Creating a PR that references the issue
  3. Adding bounty label to the PR

Completing a Bounty

When a PR with the bounty label is merged:

  1. ✅ Equity is automatically allocated
  2. 📊 Dashboard is updated
  3. 📢 Notifications are sent
  4. 🏅 Achievement badges are awarded
  5. 📈 Analytics are recalculated

🔄 Automation Workflows

Equity Tracker Workflow

Trigger: PR merge, issue close, schedule (every 6 hours), manual

Actions:

  1. Checks for bounty completion
  2. Updates equity data
  3. Generates dashboard
  4. Creates visualizations
  5. Commits changes
  6. Sends notifications

Notifications Workflow

Trigger: PR opened/closed, issue opened/closed/labeled

Actions:

  1. Discord notification for new bounties
  2. Discord notification for completions
  3. Twitter posts for major milestones
  4. Achievement badge awards
  5. Email notifications

Analytics Update Workflow

Trigger: PR merge, schedule (every 12 hours), manual

Actions:

  1. Calculates comprehensive analytics
  2. Generates reports (JSON, CSV, Markdown)
  3. Updates analytics dashboard
  4. Commits analytics data

Weekly Report Workflow

Trigger: Schedule (weekly), manual

Actions:

  1. Generates weekly summary
  2. Creates detailed report
  3. Posts to GitHub Discussions
  4. Sends to Discord/Twitter

📊 Dashboard & Analytics

Main Dashboard (dashboard.html)

Features:

  • Real-time equity metrics
  • Top contributors leaderboard
  • Active bounties list
  • Equity distribution chart
  • Progress tracking
  • Mobile-responsive design

Metrics Displayed:

  • Total equity allocated
  • Total contributors
  • Bounties completed
  • Equity available

Advanced Analytics (analytics.html)

Features:

  • Multi-tab interface
  • Comprehensive metrics
  • Interactive charts
  • Time-series analysis
  • Contributor rankings
  • Velocity metrics
  • Distribution analysis
  • Projections

Tabs:

  1. Overview - Key metrics and trends
  2. Contributors - Detailed contributor table
  3. Velocity - Activity metrics (7d, 30d)
  4. Distribution - Equity distribution stats
  5. Projections - Future estimates

Generated Charts

Located in assets/charts/:

  1. equity-distribution.svg - Bar chart of top contributors
  2. equity-pie-chart.svg - Pie chart of equity distribution
  3. equity-timeline.svg - Timeline of equity allocation

📢 Notifications

Discord Integration

Setup:

  1. Create a Discord webhook in your server
  2. Add webhook URL to repository secrets as DISCORD_WEBHOOK_URL
  3. Notifications will be sent automatically

Notification Types:

  • 🎯 New bounty available
  • 🎉 Bounty completed
  • 🏆 Achievement unlocked
  • 📊 Weekly report

Twitter Integration

Setup:

  1. Create a Twitter Developer account
  2. Create an app and get API credentials
  3. Add credentials to repository secrets
  4. Install twitter-api-v2 package

Post Types:

  • Bounty completions
  • Major milestones
  • Weekly summaries

Email Notifications

Setup:

  1. Configure SMTP server details in secrets
  2. Add notification email address
  3. Emails sent on bounty completions

🔌 API Reference

Data Files

github/EQUITY_TRACKING.json

Main equity tracking data:

{
  "total_equity_allocated": number,
  "total_equity_available": number,
  "bounties_completed": number,
  "bounties_pending": number,
  "last_updated": "ISO 8601 date",
  "contributors": [
    {
      "github_username": string,
      "bounty_completed": string,
      "equity_earned": number,
      "bounties_completed": number,
      "completion_date": "YYYY-MM-DD",
      "pr_link": string,
      "status": "completed" | "pending",
      "contributor_tier": string
    }
  ],
  "active_bounties": [
    {
      "bounty_id": number,
      "title": string,
      "equity_offer": number,
      "assigned_to": string,
      "status": "available" | "in-progress",
      "issue_link": string
    }
  ]
}

.github/analytics/analytics.json

Comprehensive analytics:

{
  "overview": {
    "total_contributors": number,
    "total_equity_allocated": number,
    "total_equity_available": number,
    "bounties_completed": number,
    "bounties_pending": number,
    "active_bounties": number
  },
  "velocity": {
    "last_7_days": {
      "contributors": number,
      "equity_allocated": number
    },
    "last_30_days": {
      "contributors": number,
      "equity_allocated": number
    },
    "daily_average": {
      "contributors": string,
      "equity": string
    }
  },
  "distribution": {
    "by_tier": {
      "founding": number,
      "core": number,
      "active": number,
      "emerging": number
    },
    "statistics": {
      "average": string,
      "median": string,
      "max": number,
      "min": number
    }
  },
  "top_performers": {
    "by_equity": array,
    "by_bounties": array
  },
  "timeline": {
    "by_month": object,
    "by_week": object
  },
  "projections": {
    "days_to_full_allocation": number,
    "estimated_contributors_at_100": number
  },
  "generated_at": "ISO 8601 date"
}

Accessing Data

From JavaScript

// Load equity data
fetch('github/EQUITY_TRACKING.json')
  .then(response => response.json())
  .then(data => {
    console.log('Total equity allocated:', data.total_equity_allocated);
    console.log('Contributors:', data.contributors);
  });

// Load analytics
fetch('.github/analytics/analytics.json')
  .then(response => response.json())
  .then(data => {
    console.log('Analytics:', data);
  });

From GitHub Actions

- name: Read Equity Data
  run: |
    EQUITY=$(jq '.total_equity_allocated' github/EQUITY_TRACKING.json)
    echo "Total equity: $EQUITY%"

🛠️ Troubleshooting

Common Issues

Workflow Not Triggering

Problem: Equity tracker doesn't run on PR merge

Solutions:

  1. Check that PR has bounty label
  2. Verify PR was actually merged (not just closed)
  3. Check workflow permissions in Settings → Actions
  4. Look at Actions tab for error messages

Dashboard Not Updating

Problem: Dashboard shows old data

Solutions:

  1. Check if workflow completed successfully
  2. Verify GitHub Pages is enabled
  3. Clear browser cache
  4. Check commit history for dashboard.html updates

Notifications Not Sending

Problem: Discord/Twitter notifications not appearing

Solutions:

  1. Verify webhook URL/API credentials are correct
  2. Check that secrets are properly set
  3. Test webhook URL manually
  4. Review workflow logs for errors

Charts Not Generating

Problem: Chart SVGs are missing or broken

Solutions:

  1. Check Node.js version (should be 20+)
  2. Verify assets/charts/ directory exists
  3. Check script execution logs
  4. Ensure equity data is valid JSON

Debug Mode

Enable debug logging in workflows:

- name: Debug
  run: |
    echo "Equity data:"
    cat github/EQUITY_TRACKING.json
    echo "Analytics:"
    cat .github/analytics/analytics.json

Manual Workflow Trigger

Test workflows manually:

  1. Go to Actions tab
  2. Select workflow
  3. Click "Run workflow"
  4. Choose branch and run

📚 Best Practices

Equity Allocation

  • Start conservative: Begin with smaller equity amounts
  • Be consistent: Use similar amounts for similar work
  • Document criteria: Clear guidelines for equity amounts
  • Review regularly: Adjust based on contribution value

Bounty Management

  • Clear descriptions: Detailed bounty requirements
  • Realistic equity: Match equity to effort required
  • Quick review: Merge PRs promptly to maintain momentum
  • Communicate: Keep contributors informed

Data Management

  • Regular backups: Export data periodically
  • Validate changes: Review equity updates before committing
  • Monitor analytics: Track trends and adjust strategy
  • Archive reports: Keep historical reports for reference

🎨 Customization

Styling

Edit dashboard colors in dashboard.html:

:root {
    --primary: #6366f1;
    --secondary: #8b5cf6;
    --success: #10b981;
    /* Add your colors */
}

Notification Messages

Customize messages in .github/workflows/notifications.yml:

- name: Custom Message
  run: |
    MESSAGE="Your custom message here"
    # Send notification

Analytics Metrics

Add custom metrics in .github/scripts/generate-analytics.js:

// Add your custom calculations
const customMetric = calculateCustomMetric(equityData);
analytics.custom = customMetric;

🚀 Advanced Features

API Integration

Create a REST API endpoint:

// api/equity.js (for Vercel/Netlify)
export default function handler(req, res) {
  const equity = require('../github/EQUITY_TRACKING.json');
  res.status(200).json(equity);
}

Webhooks

Set up webhooks for external integrations:

- name: Send Webhook
  run: |
    curl -X POST https://your-api.com/webhook \
      -H "Content-Type: application/json" \
      -d '{"event": "bounty_completed", "data": {...}}'

Custom Badges

Generate dynamic badges:

// Generate badge SVG
const badge = `<svg>...</svg>`;
fs.writeFileSync('badge.svg', badge);

📊 Performance

Optimization Tips

  1. Caching: Use GitHub Actions cache for dependencies
  2. Parallel execution: Run independent tasks in parallel
  3. Incremental updates: Only regenerate changed data
  4. Lazy loading: Load charts on demand in dashboard

Monitoring

Track workflow execution times:

  • Check Actions tab for duration
  • Monitor API rate limits
  • Review storage usage

🔐 Security

Best Practices

  1. Never commit secrets to repository
  2. Use environment variables for sensitive data
  3. Limit workflow permissions to minimum required
  4. Review PR changes before merging
  5. Validate input data in scripts

Access Control

Configure branch protection:

  • Require PR reviews
  • Require status checks
  • Restrict who can merge

📞 Support

Getting Help

  • Documentation: Read this guide thoroughly
  • Issues: Check existing GitHub issues
  • Discussions: Ask in GitHub Discussions
  • Discord: Join community Discord server

Contributing

Contributions welcome! Please:

  1. Fork the repository
  2. Create a feature branch
  3. Submit a pull request
  4. Follow code style guidelines

📝 License

This system is open source and available under the MIT License.

🎉 Conclusion

You now have a professional equity tracking and automation system that rivals funded startups! This system provides:

✅ Real-time equity tracking
✅ Beautiful live dashboards
✅ Automated notifications
✅ Professional analytics
✅ Mobile-responsive design
✅ Comprehensive documentation

Next Steps:

  1. Complete setup following this guide
  2. Create your first bounty
  3. Test the automation
  4. Customize to your needs
  5. Share with your community

Make GitForge look like a funded startup! 🚀

Generated by GitForge Equity System v1.0