{"id":31675038,"url":"https://github.com/courierx-dev/courierx","last_synced_at":"2026-01-20T17:31:53.918Z","repository":{"id":315058249,"uuid":"1057910077","full_name":"courierX-dev/courierx","owner":"courierX-dev","description":"Multi-provider email delivery service with intelligent routing and automatic failover","archived":false,"fork":false,"pushed_at":"2025-09-16T12:47:56.000Z","size":695,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-09-16T13:40:57.845Z","etag":null,"topics":["api","aws-ses","docker","email","email-delivery","mailgun","multi-provider","nestjs","nodejs","prisma","resend","sendgrid","smtp","typescript","webhook"],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/courierX-dev.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":null,"patreon":null,"open_collective":null,"ko_fi":null,"tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"otechie":null,"lfx_crowdfunding":null,"custom":null}},"created_at":"2025-09-16T11:19:48.000Z","updated_at":"2025-09-16T12:48:00.000Z","dependencies_parsed_at":"2025-09-16T13:41:33.956Z","dependency_job_id":"577510fa-e628-46c1-8b48-e1dc41fb422b","html_url":"https://github.com/courierX-dev/courierx","commit_stats":null,"previous_names":["courierx-dev/courierx"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/courierX-dev/courierx","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/courierX-dev%2Fcourierx","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/courierX-dev%2Fcourierx/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/courierX-dev%2Fcourierx/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/courierX-dev%2Fcourierx/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/courierX-dev","download_url":"https://codeload.github.com/courierX-dev/courierx/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/courierX-dev%2Fcourierx/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":278891743,"owners_count":26063856,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-08T02:00:06.501Z","response_time":56,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api","aws-ses","docker","email","email-delivery","mailgun","multi-provider","nestjs","nodejs","prisma","resend","sendgrid","smtp","typescript","webhook"],"created_at":"2025-10-08T04:59:20.455Z","updated_at":"2026-01-20T17:31:53.896Z","avatar_url":"https://github.com/courierX-dev.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# CourierX\n\n\u003e **Multi-provider email delivery service with intelligent routing and automatic failover**\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Ruby](https://img.shields.io/badge/Ruby-3.4+-red.svg)](https://www.ruby-lang.org/)\n[![Go](https://img.shields.io/badge/Go-1.22+-00ADD8.svg)](https://golang.org/)\n[![CI](https://github.com/courierX-dev/courierx/actions/workflows/ci.yml/badge.svg)](https://github.com/courierX-dev/courierx/actions)\n\nCourierX is a production-ready email delivery platform that intelligently routes emails across multiple providers with automatic failover, comprehensive webhook handling, and enterprise-grade features.\n\n## ✨ Features\n\n- 🚀 **Multi-Provider Support** - SendGrid, Mailgun, AWS SES, SMTP, Postmark, Resend\n- 🔄 **Intelligent Routing** - Automatic failover with priority-based selection\n- 📊 **Real-time Tracking** - Webhook processing with delivery status updates\n- 🔒 **Enterprise Security** - API key auth, JWT tokens, encrypted credentials\n- 🏢 **Multi-Tenant** - Complete tenant isolation with product-level config\n- ⚡ **High Performance** - Go-powered email engine with connection pooling\n- 🐳 **Docker Ready** - One-command deployment with Docker Compose\n\n## 🏗️ Architecture\n\n```\n┌──────────────────┐    ┌──────────────────┐    ┌─────────────────┐\n│   Next.js UI     │    │   Rails API      │    │   Go Core       │\n│   Dashboard      │───▶│  Control Plane   │───▶│  Email Engine   │\n│   (TypeScript)   │    │  (API-only)      │    │  (High perf)    │\n└──────────────────┘    └──────────────────┘    └─────────────────┘\n         │                       │                         │\n         │                       │                         ▼\n         │                       │                 ┌─────────────────┐\n         │                       │                 │   Providers     │\n         ▼                       ▼                 │  SendGrid       │\n┌──────────────────┐    ┌──────────────────┐     │  Mailgun        │\n│   Your App       │    │   PostgreSQL     │     │  AWS SES        │\n│  (API Client)    │    │   + Redis        │     │  SMTP           │\n└──────────────────┘    └──────────────────┘     │  Postmark       │\n                                                  │  Resend         │\n                                                  └─────────────────┘\n```\n\n**Tech Stack:**\n- **Frontend**: Next.js 14 + TypeScript (Dashboard UI, real-time analytics)\n- **API**: Rails 7.1+ API-only (Authentication, multi-tenancy, business logic)\n- **Engine**: Go 1.21+ (High-performance email sending, provider management)\n- **Database**: PostgreSQL 15+ (with encryption for sensitive data)\n- **Cache/Queue**: Redis 7+ (background jobs, rate limiting)\n- **Infrastructure**: Docker, Kubernetes\n\n**Why This Stack?**\n- ✅ **Easy to hire for**: Massive talent pools for React, Rails, and Go\n- ✅ **Industry standard**: Modern, well-documented technologies\n- ✅ **Separation of concerns**: UI, API, and email engine are decoupled\n- ✅ **Best tool for each job**: Next.js for rich UI, Rails for API, Go for performance\n\n## 🚀 Quick Start\n\n### Development Setup with Docker (Recommended)\n\n```bash\n# Clone repository\ngit clone https://github.com/courierX-dev/courierx.git\ncd courierx\n\n# Start all services with Docker Compose\ncd infra \u0026\u0026 docker compose up -d\n\n# Check that all containers are running\ndocker compose ps\n\n# Services will be available at:\n# - Rails Control Plane: http://localhost:4000\n# - Go Core Engine:      http://localhost:8080\n# - Sidekiq:             (background job processing)\n# - PostgreSQL:          localhost:5432\n# - Redis:               localhost:6379\n```\n\n### Native Development (without full Docker)\n\nIf you prefer to run Rails and Go natively (faster for development):\n\n```bash\n# Start only databases in Docker\n./infra/scripts/setup-dev-light.sh\n\n# Then run Rails in one terminal:\ncd control-plane \u0026\u0026 bundle install \u0026\u0026 rails db:create db:migrate \u0026\u0026 rails server -p 4000\n\n# And Go in another terminal:\ncd apps/core-go \u0026\u0026 go run .\n```\n\n### Using the API\n\n```bash\n# Register a new account\ncurl -X POST http://localhost:4000/api/v1/auth/register \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"tenant\": {\"name\": \"My Company\"},\n    \"user\": {\n      \"email\": \"admin@mycompany.com\",\n      \"password\": \"secure_password\",\n      \"first_name\": \"John\",\n      \"last_name\": \"Doe\"\n    }\n  }'\n\n# Create a product and get API key\ncurl -X POST http://localhost:4000/api/v1/products \\\n  -H \"Authorization: Bearer YOUR_JWT_TOKEN\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"name\": \"My App\", \"rate_limit\": 1000}'\n\n# Send an email\ncurl -X POST http://localhost:4000/api/v1/messages/send \\\n  -H \"Authorization: Bearer YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"to\": \"user@example.com\",\n    \"from\": \"sender@yourdomain.com\",\n    \"subject\": \"Hello from CourierX\",\n    \"html\": \"\u003cp\u003eYour email content here\u003c/p\u003e\"\n  }'\n```\n\n## 🔧 Supported Providers\n\n| Provider | Status | Features |\n|----------|--------|----------|\n| **SendGrid** | ✅ | API, Webhooks, Templates |\n| **Mailgun** | ✅ | API, Webhooks, Domains |\n| **AWS SES** | ✅ | API, SNS Webhooks |\n| **SMTP** | ✅ | Generic SMTP with connection pooling |\n| **Postmark** | ✅ | Modern email API |\n| **Resend** | ✅ | Developer-friendly API |\n\n## 📖 Documentation\n\n- **[Development Milestones](./docs/MILESTONES.md)** - Project roadmap with story points\n- **[Implementation Guide](./docs/IMPLEMENTATION_GUIDE.md)** - Step-by-step development guide\n- **[Story Details](./docs/STORY_DETAILS.md)** - Detailed acceptance criteria\n- **[Setup Guide](./SETUP_COMPLETE.md)** - Complete setup instructions\n- **[PR Automation](./docs/PR_AUTOMATION.md)** - Automated PR management\n\n## 🛠️ Development\n\n### Prerequisites\n\n- **Ruby 3.4+** (Rails 8.1 requires Ruby 3.4)\n- **Go 1.22+**\n- **Docker \u0026 Docker Compose** (for containerized development)\n- PostgreSQL 15+ (included in Docker)\n- Redis 7+ (included in Docker)\n\n### Project Structure\n\n```\ncourierx/\n├── apps/\n│   ├── core-go/           # Go email sending engine\n│   └── dashboard/         # Next.js dashboard (coming in Milestone 4)\n├── control-plane/         # Rails API (API-only, no views)\n├── infra/                 # Infrastructure \u0026 deployment\n│   ├── docker/           # Dockerfiles\n│   ├── kubernetes/       # K8s manifests\n│   └── scripts/          # Deployment scripts\n└── docs/                 # Documentation\n```\n\n**Key Architectural Decisions:**\n- **Rails**: API-only mode (no views, no asset pipeline)\n- **Next.js**: Separate app for dashboard, connects via REST API\n- **Go**: Standalone service, communicates with Rails via HTTP\n- **All services**: Can be deployed independently\n\n### Running Services\n\n```bash\n# Start all services (from project root)\ncd infra \u0026\u0026 docker compose up -d\n\n# View logs\ndocker compose logs -f\n\n# View logs for specific service\ndocker compose logs -f control-plane\n\n# Stop all services\ndocker compose down\n\n# Restart a specific service\ndocker compose restart control-plane\n\n# Run Rails console\ndocker compose exec control-plane bundle exec rails console\n\n# Run Go tests\ncd apps/core-go \u0026\u0026 go test ./...\n\n# Run Rails tests\ncd control-plane \u0026\u0026 bundle exec rspec\n```\n\n### Database Migrations\n\n```bash\n# Create migration\ncd control-plane\nbundle exec rails generate migration AddFieldToModel field:type\n\n# Run migrations\nbundle exec rails db:migrate\n\n# Seed database\nbundle exec rails db:seed\n```\n\n## 🚢 Deployment\n\n### Production Deployment\n\n```bash\n# Set up environment variables\ncp .env.example .env.production\n# Edit .env.production with your production values\n\n# Deploy with script\n./infra/scripts/deploy.sh\n```\n\n### Environment Variables\n\nRequired for production:\n- `DATABASE_URL` - PostgreSQL connection string\n- `REDIS_URL` - Redis connection string\n- `JWT_SECRET` - Secret for JWT token signing\n- `ENCRYPTION_KEY` - Key for encrypting provider credentials\n- `SECRET_KEY_BASE` - Rails secret key base\n- `GO_CORE_SECRET` - Shared secret for Rails-Go communication\n\nProvider credentials:\n- `SENDGRID_API_KEY`\n- `MAILGUN_API_KEY` \u0026 `MAILGUN_DOMAIN`\n- `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_REGION`\n\n### Deployment Options\n\n- **Docker Compose** - Included configuration for multi-container deployment\n- **Kubernetes** - K8s manifests in `infra/kubernetes/`\n- **Cloud Platforms** - Deploy to AWS, GCP, Azure, DigitalOcean\n- **Heroku/Railway/Render** - Platform-specific configurations available\n\n## 📊 Project Status\n\n**Current Phase**: Foundation \u0026 Core Infrastructure (Milestone 1)\n\n### Completed ✅\n- Project structure established\n- Docker configurations complete\n- Deployment scripts ready\n- Comprehensive documentation (milestones, implementation guide)\n\n### In Progress 🚧\n- Rails core models (Milestone 1.1)\n\n### Planned ⏳\n- Authentication \u0026 authorization (Milestone 1.2)\n- Go provider system (Milestone 1.3)\n- Next.js dashboard (Milestone 4)\n\nSee [MILESTONES.md](./docs/MILESTONES.md) for full roadmap (380 story points / 10 sprints).\n\n## 🤝 Contributing\n\nWe welcome contributions! Please follow these steps:\n\n1. Read [MILESTONES.md](./docs/MILESTONES.md) to understand the project roadmap\n2. Check [IMPLEMENTATION_GUIDE.md](./docs/IMPLEMENTATION_GUIDE.md) for development guidelines\n3. Pick a story from the milestones or create an issue\n4. Fork, create a branch, and submit a PR\n\n### Development Workflow\n\n1. Create feature branch: `git checkout -b feature/CP-001-description`\n2. Make changes following the implementation guide\n3. Write tests (\u003e80% coverage required)\n4. Run linters: `bundle exec rubocop` (Rails), `golangci-lint run` (Go)\n5. Submit PR with story reference\n\n## 🧪 Testing\n\n```bash\n# Rails tests\ncd control-plane\nbundle exec rspec\n\n# Go tests\ncd apps/core-go\ngo test ./... -v\n\n# Integration tests\n# (Start all services first)\ncd control-plane\nbundle exec rspec spec/integration/\n```\n\n## 📄 License\n\nMIT License - see [LICENSE](./LICENSE) for details.\n\n## 🆘 Support\n\n- 🐛 [Issues](https://github.com/courierX-dev/courierx/issues) - Bug reports\n- 💬 [Discussions](https://github.com/courierX-dev/courierx/discussions) - Questions \u0026 support\n- 📚 [Documentation](./docs) - Detailed guides\n\n---\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003eBuilt with ❤️ for developers who need reliable email delivery\u003c/strong\u003e\n\u003c/p\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcourierx-dev%2Fcourierx","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcourierx-dev%2Fcourierx","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcourierx-dev%2Fcourierx/lists"}