{"id":32672152,"url":"https://github.com/al0olo/bills","last_synced_at":"2026-05-02T22:35:52.446Z","repository":{"id":321390435,"uuid":"1085640322","full_name":"Al0olo/bills","owner":"Al0olo","description":"A microservices-based subscription billing system built with NestJS, Prisma, and PostgreSQL.","archived":false,"fork":false,"pushed_at":"2025-10-29T12:20:04.000Z","size":26,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-10-29T12:29:45.718Z","etag":null,"topics":["design-first","microservices","nestjs","nx-workspace","payments"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Al0olo.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"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}},"created_at":"2025-10-29T10:12:16.000Z","updated_at":"2025-10-29T12:23:50.000Z","dependencies_parsed_at":null,"dependency_job_id":"a2e13fa0-6f3a-46b3-a26c-07bac316cd80","html_url":"https://github.com/Al0olo/bills","commit_stats":null,"previous_names":["al0olo/bills"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/Al0olo/bills","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Al0olo%2Fbills","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Al0olo%2Fbills/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Al0olo%2Fbills/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Al0olo%2Fbills/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Al0olo","download_url":"https://codeload.github.com/Al0olo/bills/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Al0olo%2Fbills/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":282092841,"owners_count":26612896,"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-11-01T02:00:06.759Z","response_time":61,"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":["design-first","microservices","nestjs","nx-workspace","payments"],"created_at":"2025-11-01T04:00:30.441Z","updated_at":"2026-05-02T22:35:52.433Z","avatar_url":"https://github.com/Al0olo.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Bills - Subscription \u0026 Payment Microservices Platform\n\n\u003e **Production-Ready** | **100% Test Coverage** | **Fully Automated CI/CD**\n\nA microservices-based subscription billing system built with NestJS, Prisma, and PostgreSQL. Features comprehensive testing, automated CI/CD pipeline, and multi-platform Docker support.\n\n[![Tests](https://img.shields.io/badge/tests-562%20passing-brightgreen)](RELEASE-NOTES.md)\n[![Coverage](https://img.shields.io/badge/coverage-100%25-brightgreen)](RELEASE-NOTES.md)\n[![CI/CD](https://img.shields.io/badge/CI%2FCD-GitHub%20Actions-blue)](.github/workflows/ci.yml)\n[![Docker](https://img.shields.io/badge/docker-multi--platform-blue)](docker/)\n\n---\n\n## 🎯 Project Overview\n\nThis project implements a production-ready subscription billing system with two decoupled microservices:\n\n1. **Subscription Service** - User management, plans, subscriptions, and payment orchestration\n2. **Payment Service** - Payment processing simulation and webhook notifications\n\n### ✨ Key Features\n\n- **🏗️ Microservices Architecture** - Independent services with separate databases and schemas\n- **🚀 CI/CD Pipeline** - Automated testing, building, and deployment with GitHub Actions\n- **🧪 Comprehensive Testing** - 562 tests with 100% pass rate (unit + integration + E2E)\n- **🐳 Multi-Platform Docker** - Images for linux/amd64 and linux/arm64\n- **🔐 Security First** - JWT authentication, API keys, HMAC signatures, idempotency\n- **📚 Complete Documentation** - OpenAPI/Swagger, architecture diagrams, and guides\n- **🔄 Event-Driven** - Webhook system with exponential backoff retry logic\n- **💾 Transaction Management** - ACID compliance with Prisma ORM\n- **📦 Monorepo** - Nx workspace with shared libraries and utilities\n- **⚡ Performance** - Optimized builds, caching, and parallel execution\n\n---\n\n## 📊 Project Status\n\n| Metric | Status |\n|--------|--------|\n| **Version** | v1.0.0 (Production Ready) |\n| **Test Suites** | 31 passed ✅ |\n| **Total Tests** | 562 passed (100%) ✅ |\n| **Unit Tests** | 487 passed ✅ |\n| **Integration Tests** | 74 passed ✅ |\n| **E2E Tests** | 1 passed ✅ |\n| **CI/CD** | Fully Automated ✅ |\n| **Docker Images** | Multi-platform ✅ |\n| **Documentation** | Complete ✅ |\n\n---\n\n## 📚 Documentation\n\nComprehensive documentation is available in the [`docs/`](./docs) directory:\n\n| Document | Description |\n|----------|-------------|\n| **[System Architecture](./docs/system-architecture.md)** | Architecture diagrams, communication patterns, security |\n| **[Database Design](./docs/database-design.md)** | Complete schema, ERDs, transaction boundaries |\n| **[API Design](./docs/api-design.md)** | API specifications with examples and sequence diagrams |\n| **[Testing Guide](./docs/TESTING.md)** | Testing strategies and best practices |\n| **[CI/CD Guide](./docs/CI-CD.md)** | Complete CI/CD pipeline documentation |\n| **[Release Notes](./RELEASE-NOTES.md)** | Detailed release information |\n| **[Changelog](./CHANGELOG.md)** | Version history and changes |\n\n### 🔍 API Documentation\n\n- **Subscription Service Swagger:** http://localhost:3000/api\n- **Payment Service Swagger:** http://localhost:3001/api\n\n\u003e **Note:** API endpoints are documented in OpenAPI/Swagger format. Access the interactive documentation when services are running.\n\n---\n\n## 🏗️ Architecture\n\n```\n┌──────────────────┐          ┌──────────────────┐\n│  Subscription    │◄────────►│    Payment       │\n│  Service         │ Webhooks │    Service       │\n│  (Port 3000)     │          │    (Port 3001)   │\n│                  │          │                  │\n│  • Users         │          │  • Payments      │\n│  • Plans         │          │  • Simulation    │\n│  • Subscriptions │          │  • Webhooks      │\n│  • Auth          │          │  • Idempotency   │\n└────────┬─────────┘          └────────┬─────────┘\n         │                             │\n         ▼                             ▼\n┌──────────────────┐          ┌──────────────────┐\n│   PostgreSQL     │          │   PostgreSQL     │\n│ subscription-db  │          │   payment-db     │\n│ (schema-based)   │          │ (schema-based)   │\n└──────────────────┘          └──────────────────┘\n```\n\n### 🛠️ Technology Stack\n\n| Component | Technology | Version |\n|-----------|-----------|---------|\n| **Monorepo** | Nx | 22.0.2 |\n| **Package Manager** | pnpm | 10.12.4 |\n| **Runtime** | Node.js | 20+ |\n| **Framework** | NestJS | 11.1.8 |\n| **ORM** | Prisma | 6.18.0 |\n| **Database** | PostgreSQL | 15 |\n| **Authentication** | JWT | passport-jwt |\n| **Testing** | Jest | 30.2.0 |\n| **API Docs** | Swagger/OpenAPI | 3.0 |\n| **CI/CD** | GitHub Actions | Latest |\n| **Containerization** | Docker | Latest |\n| **Container Registry** | GitHub Container Registry (ghcr.io) | - |\n\n---\n\n## 🚀 Quick Start\n\n### Prerequisites\n\n- **Node.js** 20+\n- **pnpm** 10.12.4+\n- **Docker** \u0026 Docker Compose (for containerized setup)\n- **PostgreSQL** 15+ (for local development without Docker)\n\n### 🎬 Installation\n\n```bash\n# Clone the repository\ngit clone https://github.com/al0olo/bills.git\ncd bills\n\n# Install dependencies\npnpm install\n\n# Generate Prisma clients\npnpm prisma:generate\n\n# Set up environment variables (optional for unit tests)\ncp .env.example .env\n```\n\n### 🐳 Docker Setup (Recommended)\n\n```bash\n# Start all services with Docker Compose\ndocker-compose up -d\n\n# View logs\ndocker-compose logs -f\n\n# Stop all services\ndocker-compose down\n```\n\n### 💻 Local Development (Without Docker)\n\n```bash\n# Start PostgreSQL\ndocker run -d --name bills-postgres \\\n  -e POSTGRES_USER=foodizone \\\n  -e POSTGRES_PASSWORD=foodizone_password \\\n  -e POSTGRES_DB=foodizone \\\n  -p 5432:5432 postgres:15-alpine\n\n# Run database migrations\npnpm prisma:migrate:subscription\npnpm prisma:migrate:payment\n\n# Seed the database (optional)\npnpm seed\n\n# Start services in development mode\npnpm dev\n```\n\n### 🌐 Accessing Services\n\n| Service | URL | Description |\n|---------|-----|-------------|\n| **Subscription Service** | http://localhost:3000 | Main API |\n| **Subscription API Docs** | http://localhost:3000/api | Swagger UI |\n| **Payment Service** | http://localhost:3001 | Payment API |\n| **Payment API Docs** | http://localhost:3001/api | Swagger UI |\n\n---\n\n## 📦 Project Structure\n\n```\nbills/\n├── .github/\n│   └── workflows/\n│       ├── ci.yml                    # Main CI/CD pipeline\n│       └── ci-local.yml              # Local testing workflow\n├── apps/\n│   ├── subscription-service/         # Subscription microservice\n│   │   ├── src/\n│   │   │   ├── auth/                # Authentication \u0026 JWT\n│   │   │   ├── users/               # User management\n│   │   │   ├── plans/               # Subscription plans\n│   │   │   ├── subscriptions/       # Subscription lifecycle\n│   │   │   ├── webhooks/            # Webhook handlers\n│   │   │   ├── payment-client/      # Payment service client\n│   │   │   ├── prisma/              # Prisma service\n│   │   │   └── common/              # Guards, interceptors, filters\n│   │   ├── prisma/\n│   │   │   ├── schema.prisma        # Database schema\n│   │   │   ├── migrations/          # Database migrations\n│   │   │   └── seed.ts              # Database seeding\n│   │   └── test-utils/              # Test configuration\n│   └── payment-service/              # Payment microservice\n│       ├── src/\n│       │   ├── payments/            # Payment processing\n│       │   ├── webhook/             # Webhook delivery\n│       │   ├── prisma/              # Prisma service\n│       │   └── common/              # Guards, interceptors\n│       ├── prisma/\n│       │   ├── schema.prisma        # Database schema\n│       │   └── migrations/          # Database migrations\n│       └── test-utils/              # Test configuration\n├── libs/\n│   ├── testing/                     # Shared test utilities\n│   │   ├── src/lib/\n│   │   │   ├── test-auth.helper.ts  # Auth testing helpers\n│   │   │   ├── test-fixtures.ts     # Test data factories\n│   │   │   ├── test-db.helper.ts    # Database helpers\n│   │   │   ├── mock-services.ts     # Service mocks\n│   │   │   └── assertions.helper.ts # Custom matchers\n│   │   └── types/                   # Type declarations\n│   ├── shared-types/                # Common TypeScript types\n│   ├── shared-schemas/              # Shared DTOs\n│   └── common-utils/                # Utility functions\n├── docs/                            # Documentation\n│   ├── README.md                    # Documentation index\n│   ├── system-architecture.md       # Architecture details\n│   ├── database-design.md           # Database design\n│   ├── api-design.md                # API specifications\n│   ├── TESTING.md                   # Testing guide\n│   └── CI-CD.md                     # CI/CD documentation\n├── docker/\n│   ├── subscription.Dockerfile      # Subscription service image\n│   └── payment.Dockerfile           # Payment service image\n├── scripts/\n│   ├── validate-ci.sh               # CI validation script\n│   └── test-ci-local.sh             # Local CI testing\n├── docker-compose.yml               # Docker Compose configuration\n├── docker-compose.test.yml          # Test environment setup\n├── RELEASE-NOTES.md                 # Release documentation\n├── CHANGELOG.md                     # Version history\n├── nx.json                          # Nx workspace config\n├── pnpm-workspace.yaml              # pnpm workspace config\n└── package.json                     # Root package config\n```\n\n---\n\n## 🧪 Testing\n\n### Test Coverage\n\n```\nSubscription Service:\n├── Unit Tests:        402/402 passing (100%) ✅\n├── Integration Tests:  56/56  passing (100%) ✅\n└── E2E Tests:           1/1   passing (100%) ✅\n\nPayment Service:\n├── Unit Tests:        85/85  passing (100%) ✅\n└── Integration Tests: 18/18  passing (100%) ✅\n\nTotal: 562 tests passing (100%)\n```\n\n### Running Tests\n\n```bash\n# Run all unit tests (fast, no database needed)\npnpm test\n\n# Run all tests for specific service\npnpm nx run subscription-service:test\npnpm nx run payment-service:test\n\n# Run integration tests (requires PostgreSQL)\ndocker-compose -f docker-compose.test.yml up -d postgres-test\npnpm test:integration\n\n# Run with coverage\npnpm test:cov\n\n# Run E2E tests\npnpm test:e2e\n\n# Run all tests (unit + integration + E2E)\npnpm test:all\n```\n\n### Test Features\n\n- ✅ **Zero external dependencies** for unit tests\n- ✅ **Lazy-loaded bcrypt** for cross-platform compatibility\n- ✅ **Shared test utilities** in `@bills/testing` library\n- ✅ **Custom Jest matchers** for domain-specific assertions\n- ✅ **Test fixtures and factories** for data generation\n- ✅ **Database cleanup helpers** for integration tests\n- ✅ **Parallel execution** for faster test runs\n\n---\n\n## 🔄 CI/CD Pipeline\n\n### Pipeline Stages\n\nThe GitHub Actions workflow includes 3 main stages:\n\n```\n┌─────────────────┐\n│  1. Unit Tests  │  Runs in parallel for both services\n│  ~2-3 min each  │  No database required\n└────────┬────────┘\n         │\n         ▼\n┌─────────────────┐\n│ 2. Integration  │  Runs in parallel with PostgreSQL\n│  Tests          │  Real database connections\n│  ~3-5 min each  │  Separate schemas per service\n└────────┬────────┘\n         │\n         ▼\n┌─────────────────┐\n│ 3. Docker Build │  Builds and pushes images\n│  \u0026 Push         │  Multi-platform support\n│  ~3-4 min each  │  Published to ghcr.io\n└─────────────────┘\n\nTotal Time: ~10-12 minutes\n```\n\n### Triggers\n\n- **Push** to `main` or `develop` branches\n- **Pull requests** to `main` or `develop`\n- **Manual** workflow dispatch\n\n### Docker Images\n\nImages are automatically published to GitHub Container Registry:\n\n```bash\n# Pull latest images\ndocker pull ghcr.io/[owner]/bills-subscription-service:latest\ndocker pull ghcr.io/[owner]/bills-payment-service:latest\n\n# Pull specific version\ndocker pull ghcr.io/[owner]/bills-subscription-service:v1.0.0\ndocker pull ghcr.io/[owner]/bills-payment-service:sha-abc123\n```\n\n### CI/CD Features\n\n- ✅ **Automated testing** on every push\n- ✅ **Parallel execution** for faster builds\n- ✅ **Smart caching** (dependencies + Docker layers)\n- ✅ **Multi-platform builds** (amd64 + arm64)\n- ✅ **Automatic versioning** (branch, SHA, latest tags)\n- ✅ **Code coverage** reporting (optional)\n\nFor detailed CI/CD documentation, see [docs/CI-CD.md](docs/CI-CD.md)\n\n---\n\n## 🔐 Security Features\n\n- **JWT Authentication** - Secure token-based user authentication\n- **API Key Authentication** - Service-to-service communication\n- **Idempotency Keys** - Prevent duplicate payment operations\n- **HMAC Webhook Signatures** - SHA-256 signature verification\n- **Input Validation** - Comprehensive DTO validation with class-validator\n- **Rate Limiting** - Throttle decorator (100 requests/minute)\n- **SQL Injection Prevention** - Prisma parameterized queries\n- **Transaction Isolation** - ACID compliance with proper boundaries\n- **CORS Configuration** - Configured for specific origins\n- **Environment Variables** - Sensitive data externalized\n- **Password Hashing** - bcrypt with configurable rounds\n\n---\n\n## 🗄️ Database Management\n\n```bash\n# Create a new migration\npnpm prisma:migrate:dev --name migration_name\n\n# Apply migrations to production\npnpm prisma:migrate:deploy\n\n# Generate Prisma clients\npnpm prisma:generate\n\n# Seed the database\npnpm seed\n\n# Open Prisma Studio (Database GUI)\npnpm prisma:studio\n\n# Push schema changes (for development)\npnpm prisma db push\n```\n\n### Database Architecture\n\n- **Separate databases** per service for isolation\n- **Schema-based separation** for testing (subscription-test, payments-test)\n- **Prisma migrations** for version control\n- **Transaction support** with Prisma's executeTransaction\n- **Connection pooling** configured for production\n\n---\n\n## 🔄 Key Workflows\n\n### Create Subscription Flow\n\n1. User registers/logs in → JWT token issued\n2. User browses available plans\n3. User creates subscription with `planId` + `Idempotency-Key`\n4. Subscription created in PENDING status\n5. Payment initiation request sent to Payment Service\n6. Payment Service processes payment (simulated 80% success rate)\n7. Payment Service sends webhook to Subscription Service\n8. Subscription status updated (ACTIVE or CANCELLED)\n9. User notified of subscription status\n\n### Webhook Retry Strategy\n\nExponential backoff with 6 attempts:\n\n| Attempt | Delay | Total Elapsed |\n|---------|-------|---------------|\n| 1 | Immediate | 0s |\n| 2 | 30 seconds | 30s |\n| 3 | 2 minutes | 2m 30s |\n| 4 | 10 minutes | 12m 30s |\n| 5 | 30 minutes | 42m 30s |\n| 6 | 1 hour | 1h 42m 30s |\n\nAfter 6 failed attempts, webhook marked as FAILED and requires manual intervention.\n\n---\n\n## 🛠️ Development\n\n### Code Quality\n\n```bash\n# Lint code\npnpm lint\n\n# Format code with Prettier\npnpm format\n\n# Type checking\npnpm type-check\n\n# Run all quality checks\npnpm lint \u0026\u0026 pnpm type-check \u0026\u0026 pnpm test\n```\n\n### Local Testing with act (Optional)\n\nTest GitHub Actions workflows locally:\n\n```bash\n# Install act (macOS)\nbrew install act\n\n# Validate workflows\n./scripts/validate-ci.sh\n\n# Test workflows locally\n./scripts/test-ci-local.sh quick\n```\n\n---\n\n## 📈 Monitoring \u0026 Health Checks\n\n```bash\n# Health check endpoints\ncurl http://localhost:3000/health    # Subscription service\ncurl http://localhost:3001/health    # Payment service\n\n# Database connectivity\ncurl http://localhost:3000/health/db\n```\n\n### Metrics Tracked\n\n- Request rate and response times\n- Error rates and types\n- Payment success/failure rates\n- Webhook delivery success rates\n- Database query performance\n- Test execution times\n\n---\n\n## 🌍 Environment Variables\n\n### Subscription Service\n\n```env\nPORT=3000\nNODE_ENV=production\nDATABASE_URL=postgresql://user:pass@localhost:5432/foodizone?schema=subscriptions\nJWT_SECRET=your-secret-key-minimum-32-characters\nJWT_REFRESH_SECRET=your-refresh-secret-key-32-chars\nJWT_EXPIRES_IN=1h\nJWT_REFRESH_EXPIRES_IN=7d\nPAYMENT_SERVICE_URL=http://payment-service:3001\nPAYMENT_SERVICE_API_KEY=your-api-key\nWEBHOOK_SECRET=your-webhook-secret-32-characters\n```\n\n### Payment Service\n\n```env\nPORT=3001\nNODE_ENV=production\nDATABASE_URL=postgresql://user:pass@localhost:5432/foodizone?schema=payments\nAPI_KEY=your-api-key\nSUBSCRIPTION_SERVICE_WEBHOOK_URL=http://subscription-service:3000/v1/webhooks/payment\nWEBHOOK_SECRET=your-webhook-secret-32-characters\nPAYMENT_SUCCESS_RATE=80\nPAYMENT_PROCESSING_DELAY_MS=1000\n```\n\n\u003e **Note:** For testing, environment variables have sensible defaults and `.env.test` is optional.\n\n---\n\n## 🤝 Contributing\n\n### Workflow\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Make your changes\n4. Add/update tests\n5. Update documentation\n6. Run quality checks (`pnpm lint \u0026\u0026 pnpm test`)\n7. Commit your changes (`git commit -m 'feat: add amazing feature'`)\n8. Push to the branch (`git push origin feature/amazing-feature`)\n9. Open a Pull Request\n\n### Code Standards\n\n- Follow NestJS best practices\n- Write comprehensive tests (aim for 100% coverage)\n- Update documentation for new features\n- Use TypeScript strict mode\n- Follow commit message conventions (conventional commits)\n\n---\n\n## 📝 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n---\n\n## 🎉 Acknowledgments\n\n- **NestJS Team** - Excellent framework and documentation\n- **Prisma Team** - Powerful ORM with great TypeScript support\n- **GitHub** - CI/CD with Actions and Container Registry\n- **Open Source Community** - Amazing tools and libraries\n\n---\n\n## 📞 Support\n\n- **Documentation:** See `docs/` directory\n- **Issues:** [Create an issue](https://github.com/al0olo/bills/issues)\n- **CI/CD Help:** See [CI/CD Guide](docs/CI-CD.md)\n- **Release Notes:** See [RELEASE-NOTES.md](RELEASE-NOTES.md)\n\n---\n\n## 🚀 Production Checklist\n\n- [x] All tests passing (562/562) ✅\n- [x] CI/CD pipeline configured ✅\n- [x] Docker images building successfully ✅\n- [x] Multi-platform support (amd64 + arm64) ✅\n- [x] Environment variables documented ✅\n- [x] API documentation complete (Swagger) ✅\n- [x] Database migrations ready ✅\n- [x] Security measures implemented ✅\n- [x] Comprehensive documentation ✅\n- [x] Health checks configured ✅\n\n---\n\n**Version:** 1.0.0  \n**Status:** ✅ Production Ready  \n**Last Updated:** November 3, 2025\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fal0olo%2Fbills","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fal0olo%2Fbills","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fal0olo%2Fbills/lists"}