{"id":29364492,"url":"https://github.com/omsingh2003/nimbus","last_synced_at":"2026-04-11T17:43:28.291Z","repository":{"id":288668937,"uuid":"968844998","full_name":"OmSingh2003/Nimbus","owner":"OmSingh2003","description":"Engineered a Go backend for a banking platform with REST/gRPC APIs, PostgreSQL, JWT/PASETO authentication, and Redis for async tasks, deployed with Docker and CI/CD.","archived":false,"fork":false,"pushed_at":"2025-08-20T13:36:45.000Z","size":102288,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-08-20T15:32:36.509Z","etag":null,"topics":["docker","gin","golang","grpc-go","http-server","kubernetes","postgresql","redis"],"latest_commit_sha":null,"homepage":"https://nimbus-online.vercel.app","language":"Go","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/OmSingh2003.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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":"2025-04-18T20:58:28.000Z","updated_at":"2025-08-20T13:36:48.000Z","dependencies_parsed_at":"2025-08-20T15:27:28.108Z","dependency_job_id":null,"html_url":"https://github.com/OmSingh2003/Nimbus","commit_stats":null,"previous_names":["omsingh2003/simple-bank","omsingh2003/vaultguard-api","omsingh2003/nimbus"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/OmSingh2003/Nimbus","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OmSingh2003%2FNimbus","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OmSingh2003%2FNimbus/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OmSingh2003%2FNimbus/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OmSingh2003%2FNimbus/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/OmSingh2003","download_url":"https://codeload.github.com/OmSingh2003/Nimbus/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OmSingh2003%2FNimbus/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279013971,"owners_count":26085429,"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-13T02:00:06.723Z","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":["docker","gin","golang","grpc-go","http-server","kubernetes","postgresql","redis"],"created_at":"2025-07-09T11:00:26.532Z","updated_at":"2026-04-07T21:32:21.722Z","avatar_url":"https://github.com/OmSingh2003.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Nimbus API\n\n[![Go Version](https://img.shields.io/badge/Go-1.23+-blue.svg)](https://golang.org/)\n[![CI Test Status](https://github.com/OmSingh2003/nimbus/actions/workflows/ci-test.yml/badge.svg)](https://github.com/OmSingh2003/nimbus/actions/workflows/ci-test.yml)\n[![Test Coverage](https://img.shields.io/codecov/c/github/OmSingh2003/nimbus)](https://codecov.io/gh/OmSingh2003/nimbus)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\nA robust, full-featured banking backend system built with Go. This project demonstrates modern microservices architecture with REST/gRPC APIs, secure authentication, asynchronous task processing, and comprehensive testing. Prod : Broken -\u003e working on it! Thanks😅\n\n\n##  Features\n\n* **RESTful API:** Built with [Gin](https://github.com/gin-gonic/gin) for core banking operations (accounts, transfers, entries).\n* **gRPC API:** High-performance RPC framework for inter-service communication and client SDK generation.\n* **gRPC Gateway:** Translates RESTful JSON API requests into gRPC messages, allowing one API definition for both. Includes embedded Swagger UI.\n* **Database:** PostgreSQL database integration.\n* **Type-Safe SQL:** Uses [SQLC](https://github.com/sqlc-dev/sqlc) to generate type-safe Go code from SQL queries.\n* **DB Migrations:** Manages database schema changes using [golang-migrate](https://github.com/golang-migrate/migrate).\n* **Authentication:** Secure user authentication using both JWT and PASETO tokens.\n* **Asynchronous Tasks:** Background task processing (e.g., sending verification emails) using Redis and [Asynq](https://github.com/hibiken/asynq).\n* **Dockerized:** Fully containerized application using Docker and Docker Compose for consistent environments.\n* **Configuration:** Centralized configuration management using [Viper](https://github.com/spf13/viper).\n* **Logging:** Structured logging using [Zerolog](https://github.com/rs/zerolog).\n* **CI/CD:** Automated testing and build pipelines (e.g., using GitHub Actions).\n\n##  Tech Stack\n\n* **Language:** [Go](https://golang.org/) (version 1.23+)\n* **API Frameworks:** [Gin](https://github.com/gin-gonic/gin), [gRPC](https://grpc.io/), [gRPC Gateway](https://github.com/grpc-ecosystem/grpc-gateway)\n* **Database:** [PostgreSQL](https://www.postgresql.org/)\n* **ORM/SQL Builder:** [SQLC](https://github.com/sqlc-dev/sqlc)\n* **Migrations:** [golang-migrate](https://github.com/golang-migrate/migrate)\n* **Async Tasks:** [Redis](https://redis.io/), [Asynq](https://github.com/hibiken/asynq)\n* **Authentication:** JWT ([golang-jwt](https://github.com/golang-jwt/jwt)), PASETO ([paseto](https://github.com/o1egl/paseto))\n* **Configuration:** [Viper](https://github.com/spf13/viper)\n* **Logging:** [Zerolog](https://github.com/rs/zerolog)\n* **Containerization:** [Docker](https://www.docker.com/), [Docker Compose](https://docs.docker.com/compose/)\n* **Build/Task Runner:** [Make](https://www.gnu.org/software/make/)\n* **DB Documentation:** [DBML](https://dbml.org/), [dbdocs](https://dbdocs.io/)\n* **Mocking:** [Gomock](https://github.com/golang/mock)\n\n##  Prerequisites \u0026 Tool Installation\n\nEnsure you have the following core tools installed:\n\n* [Go](https://golang.org/doc/install) (version 1.23 or higher)\n* [Docker Desktop](https://docs.docker.com/get-docker/) (includes Docker \u0026 Docker Compose)\n* [Make](https://www.gnu.org/software/make/)\n* Optional DB GUI: [TablePlus](https://tableplus.com/) or similar\n\nInstall project-specific CLI tools:\n\n* **Homebrew (macOS):** If using macOS, [install Homebrew](https://brew.sh/) first.\n* **Migrate CLI:** Manages database migrations.\n    ```bash\n    # Using Homebrew (macOS)\n    brew install golang-migrate\n    # Or build from source (other OS) - see golang-migrate docs\n    ```\n* **SQLC CLI:** Generates Go code from SQL.\n    ```bash\n    # Using Homebrew (macOS)\n    brew install sqlc\n    # Or build from source (other OS) - see sqlc docs\n    ```\n* **buf CLI:** Manages Protobuf files.\n    ```bash\n    # Using Homebrew (macOS)\n    brew install bufbuild/buf/buf\n    # Or see buf installation docs\n    ```\n* **Gomock:** Generates mock code for testing.\n    ```bash\n    go install go.uber.org/mock/mockgen@latest\n    ```\n* **DBML CLI:** Converts DBML to SQL (for schema generation).\n    ```bash\n    npm install -g @dbml/cli\n    # Verify installation\n    dbml2sql --version\n    ```\n* **dbdocs CLI:** Generates database documentation website.\n    ```bash\n    npm install -g dbdocs\n    # Login to dbdocs service (required for hosting)\n    dbdocs login\n    ```\n\n##  Local Development Setup\n\nFollow these steps to set up the project for local development:\n\n1.  **Clone the repository:**\n    ```bash\n    git clone https://github.com/OmSingh2003/nimbus.git\n    cd nimbus\n    ```\n\n2.  **Set up Environment Variables:**\n    Copy the example environment file and update it with your specific configuration.\n    ```bash\n    cp .env.example .env\n    ```\n    * Modify `.env` with your database credentials (use defaults if using `make postgres`), token symmetric keys, Redis address, etc.\n\n3.  **Setup Infrastructure (Docker Network \u0026 Postgres):**\n    This creates a dedicated Docker network and starts a PostgreSQL container.\n    ```bash\n    # Create the docker network (if it doesn't exist)\n    make network\n\n    # Start postgres container\n    make postgres\n    ```\n\n4.  **Create Database:**\n    Connects to the running Postgres container and creates the `vaultguard_api` database.\n    ```bash\n    make createdb\n    ```\n\n5.  **Run Initial Database Migration:**\n    Applies all available migrations to set up the database schema.\n    ```bash\n    make migrateup\n    ```\n\n6.  **Install Go Dependencies:**\n    ```bash\n    go mod tidy\n    ```\n\n7.  **Generate Code (SQLC, Mocks, Protobuf):**\n    This step generates necessary Go code based on SQL queries, Protobuf definitions, and creates mocks for testing.\n    ```bash\n    # Generate Go code from SQL queries in db/query/\n    make sqlc\n\n    # Generate gRPC, gRPC-gateway, and Swagger code from proto files\n    make proto\n\n    # Generate mock code for testing interfaces\n    make mock\n    ```\n\n8.  **Build the Application:**\n    Compiles the Go application binaries.\n    ```bash\n    make build\n    ```\n\n## ▶️ Running the Application\n\n**Using Docker Compose (Recommended):**\n\nThis starts all services (PostgreSQL, Redis, API server, gRPC server, async worker) defined in `docker-compose.yml`.\n\n```bash\ndocker-compose up --build\n```\n\n\u003e The `--build` flag ensures images are rebuilt if code changes\n\n**Using Make (Requires Manual Service Management):**\n\nIf you prefer not to use Docker Compose for the Go services (but still use `make postgres` for the DB):\n\n```bash\n# Start the main API server (REST \u0026 gRPC Gateway)\nmake server\n\n# (In another terminal) Start the asynchronous task worker\nmake worker\n```\n\n**Default Ports:**\n- REST API server: `:8080`\n- gRPC server: `:9090`\n- Asynq web UI (if enabled): `:8081`\n\n##  Running Tests\n\nTo run the test suite:\n\n```bash\nmake test\n```\n\nThis runs `go test -v -cover -short ./...` which includes coverage reporting.\n\n##  Migrations Management\n\nUse Make commands to manage database schema migrations:\n\n**Apply all pending migrations:**\n```bash\nmake migrateup\n```\n\n**Apply the next pending migration:**\n```bash\nmake migrateup1\n```\n\n**Roll back all migrations:**\n```bash\nmake migratedown\n```\n\n**Roll back the last applied migration:**\n```bash\nmake migratedown1\n```\n\n**Create a new migration file:**\n```bash\nmake new_migration name=\u003cmigration_name\u003e\n```\n\n\u003e Replace `\u003cmigration_name\u003e` with a descriptive name (e.g., `add_users_table`)\n\n##  Database Documentation\n\nGenerate and view database documentation using DBML and dbdocs:\n\n**Generate schema SQL file from DBML:**\n```bash\nmake db_schema\n```\n\n**Generate and publish documentation website:**\n```bash\nmake db_docs\n```\n\n\u003e Requires prior `dbdocs login`. Access the DB documentation at the URL provided by the command output.\n\n##  API Documentation (Swagger)\n\nAPI documentation is automatically generated from the Protobuf definitions and served via Swagger UI.\n\nOnce the server is running (using `docker-compose up` or `make server`), access the Swagger UI at:\n\n**http://localhost:8080/swagger/**\n\n##  Deployment (Kubernetes Example)\n\nThese are example steps for setting up prerequisites in a Kubernetes cluster:\n\n**Install Nginx Ingress Controller:**\n```bash\n# Example for AWS, check provider docs for others\nkubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/controller-v0.48.1/deploy/static/provider/aws/deploy.yaml\n```\n\n**Install Cert-Manager:**\n```bash\n# For automatic TLS certificate management\nkubectl apply -f https://github.com/jetstack/cert-manager/releases/download/v1.4.0/cert-manager.yaml\n```\n\n\u003e **Note:** Ensure you use versions compatible with your cluster. These are examples.\n\n## 🏗️ Project Structure\n\n```\n.\n├── api/                 # Gin handlers, middleware, server setup\n├── db/                  # Database migrations and SQLC queries/schema\n├── doc/                 # Documentation files (DBML, Swagger)\n├── gapi/                # gRPC handlers, interceptors, server setup\n├── mail/                # Mail sending logic\n├── pb/                  # Generated Protobuf Go code\n├── proto/               # Protobuf definition files\n├── token/               # JWT/PASETO token generation and verification\n├── util/                # Utility functions (config, logging, etc.)\n├── val/                 # Validation logic\n├── worker/              # Asynq task definitions and processor setup\n├── .env                 # Environment variables (not in repo)\n├── .env.example         # Example environment variables\n├── Dockerfile           # Docker build instructions\n├── docker-compose.yml   # Docker Compose service definitions\n├── go.mod               # Go module dependencies\n├── Makefile             # Make targets for common tasks\n└── main.go              # Main application entry point\n```\n\n##  CI/CD\n\nThis project uses GitHub Actions for continuous integration. The workflow includes:\n\n- Running linters (`golangci-lint`)\n- Running unit tests with coverage\n- Building the application\n- Security scanning\n\n##  Contributing\n\nContributions are welcome! Please follow these guidelines:\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Make your changes\n4. Add tests for new functionality\n5. Ensure all tests pass (`make test`)\n6. Commit your changes (`git commit -m 'Add amazing feature'`)\n7. Push to the branch (`git push origin feature/amazing-feature`)\n8. Open a Pull Request\n\nPlease follow standard Go practices and ensure code coverage is maintained.\n\n##  License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fomsingh2003%2Fnimbus","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fomsingh2003%2Fnimbus","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fomsingh2003%2Fnimbus/lists"}