Table of Contents

1. About The Project
   • System Architecture Flow
   • Architecture & Package-by-Feature Layout
   • Built With
2. Getting Started
   • Prerequisites
   • Environment Configuration
   • Docker Containerization (Recommended)
   • Local Development
3. Usage & API Endpoints
4. Roadmap
5. Contributing
6. License
7. Contact

About The Project

git-to-feed is a production-ready, event-driven Go microservice designed under Clean Architecture and Package-by-Feature principles. It listens to GitHub repository Webhooks (Pull Requests and Releases), enriches event contexts, formats payloads using LLMs (Google Gemini AI) guided by curated Few-Shot Examples, and notifies an interactive Discord Bot for Human-in-the-Loop approval before live publication to LinkedIn.

System Architecture Flow

flowchart TD
    GH["GitHub Webhook"] -->|"HMAC Verified"| WH["Webhook Handler"]
    WH --> PIPE["Pipeline Gemini AI"]
    PIPE --> BOT["Discord Bot"]
    BOT -->|"Approve / Reject"| APP["Approval Engine"]
    APP -->|"Published"| LI["LinkedIn API"]

(back to top)

Architecture & Package-by-Feature Layout

The codebase strictly decouples business domain logic from infrastructure, storage, and transport layers.

git-to-feed/
├── cmd/
│   └── api/                  # Main HTTP API Entrypoint
├── internal/
│   ├── approval/             # Approval Feature Module (Entities, Use Cases, Repositories, HTTP Handlers)
│   ├── pipeline/             # Content Generation Pipeline (ContextBuilder, PromptBuilder, GeminiLLMClient, Anti-Cringe, Few-Shot)
│   ├── publisher/            # LinkedIn Publisher Feature Module (Entities, Use Cases, HTTP Client, Mocks)
│   ├── webhook/              # GitHub Ingestion Feature Module (Payload Parser, HMAC Validation)
│   └── platform/             # Infrastructure & Platform Adapters
│       ├── config/           # Environment Configuration & godotenv Loader
│       ├── discord/          # Interactive Discord Bot (discordgo WebSocket & Embed Buttons)
│       ├── http/             # HTTP Server Router & Endpoint Wire-up
│       └── storage/          # Database Drivers (PostgreSQL/Supabase & SQL Auto-Migrations Engine)
├── supabase/
│   └── migrations/           # SQL Database Schema Migrations (.sql)
├── .github/                  # GitHub Workflows, Templates & Community Guidelines
├── CODE_OF_CONDUCT.md        # Community Contributor Covenant Standards
├── CONTRIBUTING.md           # Contribution Guidelines & Template Specifications
├── Dockerfile                # Multi-stage Production Docker Build
├── docker-compose.yml        # Orchestration Config
├── LICENSE                   # MIT Open-Source License Terms
├── ROADMAP_EVOLUTION.md      # Future Architectural Roadmap & Evolution Specifications
└── SECURITY.md               # Responsible Vulnerability Disclosure Policy

(back to top)

Built With

• 
• 
• 
• 
• 

(back to top)

Getting Started

Follow these steps to set up and run git-to-feed.

Prerequisites

• Docker & Docker Compose (Recommended for production & local execution)
• Go 1.22+ (Optional for local Go CLI development)

Environment Configuration

Create a .env file in the root directory (refer to .env.example):

PORT=":8080"
GITHUB_WEBHOOK_SECRET="your-github-webhook-secret"
LINKEDIN_ACCESS_TOKEN="your-linkedin-access-token"
LINKEDIN_AUTHOR_URN="urn:li:person:your-author-urn"
DATABASE_URL="postgres://postgres.[PROJECT-REF]:[PASSWORD]@aws-0-[REGION].pooler.supabase.com:5432/postgres?sslmode=require"
DISCORD_BOT_TOKEN="your-discord-bot-token"
DISCORD_CHANNEL_ID="your-discord-channel-id"
GEMINI_API_KEY="your-google-gemini-api-key"
GEMINI_MODEL_NAME="gemini-3.5-flash-lite"

Docker Containerization (Recommended)

Run the application stack using Docker Compose:

docker-compose up --build -d

Or build and run using Docker CLI directly:

docker build -t git-to-feed:latest .
docker run -d -p 8080:8080 --env-file .env git-to-feed:latest

Local Development

For building and testing directly with the Go toolchain:

# Download Go module dependencies
go mod download

# Run the API server locally
go run cmd/api/main.go

# Run unit tests & static analysis
go vet ./...
go test -v ./...

(back to top)

Usage & API Endpoints

The microservice exposes clean REST HTTP endpoints and granular OpenStatus component health monitoring:

(back to top)

Roadmap

• Universal Multi-Repository Webhook Ingestion (pull_request, release)
• Google Gemini AI Integration with Curated Few-Shot Engineering
• Anti-Cringe & Payload Sanitization Filters
• Interactive Discord Bot for Human-in-the-Loop Approvals
• Automatic PostgreSQL Schema Migration Engine (supabase/migrations)
• Granular OpenStatus Health Monitoring Sub-Endpoints
• Open-Source Governance Suite (LICENSE, CONTRIBUTING, CODE_OF_CONDUCT, SECURITY)
• Automated CI/CD Workflows (GitHub Actions)
• Event Batching & Aggregation Engine (Frequency Windows)

See ROADMAP_EVOLUTION.md for full architectural roadmap specifications.

(back to top)

Contributing

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

Please review our Contributing Guidelines and Code of Conduct for details on Git Flow, Conventional Commits, Gitmojis, and Pull Request templates.

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'feat: :sparkles: add AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request using templates in .github/PULL_REQUEST_TEMPLATE/

(back to top)

License

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

For security vulnerabilities and disclosure, please refer to our Security Policy.

(back to top)

Contact

hawksxo - @hawksxo

Project Link: https://github.com/hawksxo/git-to-feed

(back to top)