{"id":28449015,"url":"https://github.com/sarasouza18/pixwave","last_synced_at":"2026-04-02T18:52:39.092Z","repository":{"id":296127263,"uuid":"867276587","full_name":"sarasouza18/PixWave","owner":"sarasouza18","description":"PixWave is a PHP microservice wallet system that processes payments via PIX using two gateways, ensuring high availability and fallback. It uses MySQL for records, Redis for caching, SNS for messaging, Docker and Kubernetes for orchestration, and centralizes logs with Logstash and Elasticsearch.","archived":false,"fork":false,"pushed_at":"2025-05-29T04:16:07.000Z","size":44578,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-06-06T14:02:28.630Z","etag":null,"topics":["docker","kubernetes","laravel","payment-gateway","payment-integration","php","phpunit","sns"],"latest_commit_sha":null,"homepage":"","language":"PHP","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/sarasouza18.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}},"created_at":"2024-10-03T18:58:19.000Z","updated_at":"2024-10-15T02:13:42.000Z","dependencies_parsed_at":"2025-05-29T04:42:54.697Z","dependency_job_id":null,"html_url":"https://github.com/sarasouza18/PixWave","commit_stats":null,"previous_names":["sarasouza18/pixwave"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/sarasouza18/PixWave","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sarasouza18%2FPixWave","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sarasouza18%2FPixWave/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sarasouza18%2FPixWave/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sarasouza18%2FPixWave/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sarasouza18","download_url":"https://codeload.github.com/sarasouza18/PixWave/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sarasouza18%2FPixWave/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":262888902,"owners_count":23380119,"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","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":["docker","kubernetes","laravel","payment-gateway","payment-integration","php","phpunit","sns"],"created_at":"2025-06-06T14:00:36.874Z","updated_at":"2025-12-30T22:07:08.092Z","avatar_url":"https://github.com/sarasouza18.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# PixWave\n\n**PixWave** is a scalable and high-performance digital wallet microservice designed to handle real-time payments via **PIX**, using a **multi-gateway architecture**. The system integrates multiple payment gateways, including **Mercado Pago** and **Gerencianet**, ensuring reliability and seamless fallback capabilities. By dynamically selecting the most available gateway at any given moment, PixWave minimizes downtime and ensures continuous payment processing.\n\nThe architecture is built to be **resilient, modular, and scalable**, using **Docker** for containerization, **Kubernetes** for orchestration, **Redis** for caching, **SNS** for asynchronous messaging, and the **ELK stack** (Logstash, Elasticsearch, Kibana) for centralized logging and real-time monitoring of system performance.\n\n## 🚀 Key Features\n\n- **Multi-gateway architecture** with real-time gateway selection and automatic fallback.\n- **Asynchronous job processing** with retry mechanisms for handling failed transactions and long-running tasks.\n- **Centralized logging and real-time monitoring** using the **ELK stack** (Elasticsearch, Logstash, Kibana).\n- **Scalability and resilience** powered by Docker and Kubernetes, ensuring the system can handle high loads and remain operational under stress.\n\n---\n\n## 📊 System Architecture\n\n### 1. **Microservice-Based Architecture**\n\nPixWave follows a **microservice-based architecture**, where key components—such as payment processing, user management, and transaction monitoring—are decoupled into independent services. This design enables scaling individual services independently and maintaining them without affecting the entire system.\n\n- **Laravel** is used as the backend framework to manage payment transactions, user interactions, and API requests.\n- **Docker** containerizes each service, ensuring consistency across development, testing, and production environments.\n- **Kubernetes** orchestrates the deployment and management of these containers, providing features like automatic scaling, self-healing, and load balancing.\n\n### 2. **Payment Processing**\n\nThe core of PixWave is its payment processing module, designed to handle real-time PIX transactions with high availability and fault tolerance. The system integrates two primary payment gateways: **Mercado Pago** and **Gerencianet**, and uses a smart gateway selection mechanism.\n\n#### 2.1. **Multi-Gateway System with Fallback**\n\n- The system first attempts to process payments via the primary gateway (either Mercado Pago or Gerencianet).\n- **Redis** stores the availability status of each gateway, enabling fast retrieval and decision-making.\n- If the primary gateway is unavailable, the system immediately switches to the fallback gateway, ensuring continuous payment processing with minimal downtime.\n\n#### 2.2. **Transaction Management**\n\n- All transactions are logged in **MySQL**, including details like transaction amount, user ID, gateway used, status (success, failed, or pending), and timestamps.\n- **Enum-based status management** standardizes transaction statuses across different gateways for consistency in the database.\n- **Job queues** handle payment processing asynchronously, allowing users to initiate payments without waiting for the entire process to complete.\n\n---\n\n### 3. **Job and Retry Mechanisms**\n\nThe **Job system** in PixWave is critical for handling tasks like payment processing and retries. By dispatching jobs for payment requests asynchronously, PixWave provides a non-blocking experience for users and increases overall system responsiveness.\n\n#### 3.1. **Job Handling**\n\n- When a payment is requested, a **job** is dispatched to process the transaction asynchronously, contacting the relevant payment gateway to submit the transaction and retrieve the result.\n- Jobs are processed in parallel, ensuring efficient handling of large volumes of payments.\n\n#### 3.2. **Retry Mechanism**\n\n- If a payment attempt fails due to gateway issues, the system retries up to **3 times** before marking the transaction as failed.\n- After all retry attempts, the system switches to the fallback gateway and retries the payment.\n- If the fallback also fails, the transaction is logged as failed, and alerts may be sent via **SNS** for further investigation.\n\n---\n\n### 4. **Caching with Redis**\n\nPixWave uses **Redis** for caching to enhance performance and reduce the load on the primary database.\n\n- **Gateway availability**: Cached in Redis, allowing the system to quickly determine which payment gateway to use without making redundant API calls.\n- **Transaction lookups**: Recently processed transactions are cached, enabling fast lookup and reducing unnecessary queries to the MySQL database.\n\n---\n\n### 5. **Centralized Logging and Monitoring**\n\n**Logstash** and **Elasticsearch** are used to manage centralized logging, providing real-time insights into system events, errors, and performance metrics.\n\n- **Logstash** collects logs from all services (Laravel, job queues, payment gateways) and sends them to **Elasticsearch** for indexing.\n- **Elasticsearch** enables powerful querying for system health checks and troubleshooting.\n- **Kibana** offers a graphical dashboard for exploring logs, tracking errors, and visualizing system performance.\n\n---\n\n### 6. **Message Queue and Asynchronous Notifications**\n\nPixWave uses **SNS (Simple Notification Service)** for messaging between microservices and for sending notifications to external systems.\n\n- When a transaction is processed, notifications are sent to external systems (e.g., user apps or third-party services) via SNS, ensuring that the system stays responsive even under high traffic.\n- Internal messaging between system components is handled via **SQL** and **SNS**, ensuring decoupled communication between services.\n\n---\n\n## 🛠️ Installation Instructions\n\n### 1. **Clone the Repository**\n\nTo begin, clone the PixWave repository to your local machine:\n\n```bash\ngit clone https://github.com/your-repository/pixwave.git\ncd pixwave\n```\n\n### 2. **Set Up Environment Variables**\n\nCopy the `.env.example` file to `.env` and configure your environment variables. These variables include database credentials, payment gateway credentials (Mercado Pago and Gerencianet), and API keys for other services:\n\n```bash\ncp .env.example .env\n```\n\nUpdate the following values in the `.env` file:\n\n- `DB_HOST`, `DB_PORT`, `DB_DATABASE`, `DB_USERNAME`, `DB_PASSWORD` – MySQL database settings.\n- `MERCADOPAGO_ACCESS_TOKEN` – Mercado Pago access token.\n- `GERENCIANET_CLIENT_ID`, `GERENCIANET_CLIENT_SECRET`, `GERENCIANET_PIX_KEY` – Gerencianet API credentials.\n- `SNS_API_KEY` – Your SNS API key for notifications.\n- `LOGSTASH_HOST` – Host for Logstash service (for centralized logging).\n\n### 3. **Install Dependencies**\n\nRun the following command to install all required dependencies:\n\n```bash\ncomposer install\n```\n\n### 4. **Set Up Docker**\n\nMake sure you have **Docker** installed on your machine. Then, use **Docker Compose** to build and run the necessary containers:\n\n```bash\ndocker-compose up --build\n```\n\nThis command will start up the following services:\n- **Laravel App** (PHP backend)\n- **MySQL** (Relational database)\n- **Redis** (Cache)\n- **Elasticsearch \u0026 Logstash** (Centralized logging)\n- **Kibana** (Log analysis interface)\n\n### 5. **Run Migrations and Seeders**\n\nAfter the containers are up and running, execute the migrations to set up the database schema and seed some initial data:\n\n```bash\ndocker exec -it laravel_app php artisan migrate --seed\n```\n\n### 6. **Generate Application Key**\n\nGenerate the application encryption key, which is used by Laravel for secure encryption:\n\n```bash\ndocker exec -it laravel_app php artisan key:generate\n```\n\n### 7. **Run the Application**\n\nWith everything set up, you can now access the application. By default, the application will be available at `http://localhost`:\n\n```bash\ndocker-compose up\n```\n\nVisit `http://localhost` in your browser to interact with the PixWave system.\n\n---\n\n## 🧪 Running Tests\n\nPixWave includes a comprehensive test suite. To run the tests, ensure that you are inside the Docker container or have a local environment set up. Run the following command:\n\n```bash\ndocker exec -it laravel_app php artisan test\n```\n\nThis will execute the unit and feature tests to ensure the functionality of the payment system, including job processing, gateway fallback, and transaction history management.\n\n---\n\n## 🤖 Troubleshooting\n\n- **Port Conflicts**: If you encounter port conflicts (e.g., Redis or MySQL already running on your system), update the `docker-compose.yml` file to change the default port mappings.\n- **Permission Errors**: If permission issues arise when trying to write to logs or storage, ensure that the `storage/` and `bootstrap/cache/` directories are writable by running:\n\n  ```bash\n  sudo chmod -R 775 storage\n  sudo chmod -R 775 bootstrap/cache\n  ```\n\n- **Container Restarts**: If containers are restarting or failing to run, check the logs for detailed error messages:\n\n  ```bash\n  docker-compose logs\n  ```\n\n---\n\n## 💻 Technologies Used\n\n### 1. **Backend Framework**\n\n- **Laravel**: Used to develop the core payment processing logic and API interactions.\n\n### 2. **Database**\n\n- **MySQL**: Relational database for storing transaction details, user data, and gateway information.\n\n### 3. **Cache**\n\n- **Redis**: Caching layer for optimizing response times and reducing load on the primary database.\n\n### 4. **Messaging**\n\n- **SNS (Simple Notification Service)**: Used for sending asynchronous notifications and internal messaging between services.\n\n### 5. **Job Queue**\n\n- **Laravel Jobs**: Manages background job processing, including payment transactions and retries.\n\n### \n\n6. **Containerization and Orchestration**\n\n- **Docker**: Ensures consistency across environments by containerizing the application.\n- **Kubernetes**: Handles container orchestration, scaling, and health checks for services.\n\n### 7. **Logging and Monitoring**\n\n- **Logstash \u0026 Elasticsearch**: Collects and indexes logs for real-time monitoring and analysis.\n- **Kibana**: Provides a visual interface for exploring logs and tracking system performance.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsarasouza18%2Fpixwave","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsarasouza18%2Fpixwave","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsarasouza18%2Fpixwave/lists"}