{"id":43980463,"url":"https://github.com/mutugading/goapps-backend","last_synced_at":"2026-04-16T03:02:33.366Z","repository":{"id":335604731,"uuid":"1145840626","full_name":"mutugading/goapps-backend","owner":"mutugading","description":"This repository contains backend microservices for the GoApps platform. Each service follows Clean Architecture principles and exposes both gRPC and REST APIs.","archived":false,"fork":false,"pushed_at":"2026-04-08T09:08:46.000Z","size":24091,"stargazers_count":3,"open_issues_count":0,"forks_count":2,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-08T11:15:24.003Z","etag":null,"topics":["clean-architecture","ddd-patterns","go","golang","grpc","microservice","protobuf","protocol-buffers"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mutugading.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","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,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-01-30T09:29:31.000Z","updated_at":"2026-04-08T09:08:48.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/mutugading/goapps-backend","commit_stats":null,"previous_names":["mutugading/goapps-backend"],"tags_count":12,"template":false,"template_full_name":null,"purl":"pkg:github/mutugading/goapps-backend","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mutugading%2Fgoapps-backend","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mutugading%2Fgoapps-backend/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mutugading%2Fgoapps-backend/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mutugading%2Fgoapps-backend/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mutugading","download_url":"https://codeload.github.com/mutugading/goapps-backend/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mutugading%2Fgoapps-backend/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31749763,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-13T09:16:15.125Z","status":"ssl_error","status_checked_at":"2026-04-13T09:16:05.023Z","response_time":93,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["clean-architecture","ddd-patterns","go","golang","grpc","microservice","protobuf","protocol-buffers"],"created_at":"2026-02-07T09:01:38.406Z","updated_at":"2026-04-13T11:01:17.372Z","avatar_url":"https://github.com/mutugading.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# GoApps Backend\n\nBackend microservices platform for **GoApps** built with Go, gRPC, and Clean Architecture principles.\n\n---\n\n## 📋 Table of Contents\n\n1. [Overview](#overview)\n2. [Architecture](#architecture)\n3. [Technology Stack](#technology-stack)\n4. [Repository Structure](#repository-structure)\n5. [Quick Start](#quick-start)\n6. [Services](#services)\n7. [Development](#development)\n8. [Testing](#testing)\n9. [CI/CD Pipeline](#cicd-pipeline)\n10. [Deployment](#deployment)\n11. [API Documentation](#api-documentation)\n12. [Troubleshooting](#troubleshooting)\n13. [Related Documentation](#related-documentation)\n\n---\n\n## Overview\n\nThis repository contains backend microservices for the GoApps platform. Each service follows Clean Architecture principles and exposes both gRPC and REST APIs.\n\n### GoApps Ecosystem\n\n```\ngoapps/\n├── goapps-backend/        # 🖥️  Backend microservices (this repo)\n├── goapps-infra/          # 🔧 Infrastructure as Code\n├── goapps-frontend/       # 🌐 Frontend application (Next.js)\n└── goapps-shared-proto/   # 📝 Protocol Buffer definitions\n```\n\n| Repository | Description | Tech Stack |\n|------------|-------------|------------|\n| `goapps-backend` | Microservices APIs | Go 1.24, gRPC, PostgreSQL, Redis |\n| `goapps-infra` | Infrastructure as Code | Kubernetes, Kustomize, Helm, ArgoCD |\n| `goapps-frontend` | Web Application | Next.js 15, React, TypeScript |\n| `goapps-shared-proto` | API Contracts | Protocol Buffers, Buf |\n\n---\n\n## Architecture\n\n### High-Level Architecture\n\n```\n┌──────────────────────────────────────────────────────────────────────────────┐\n│                            GoApps Backend                                     │\n├──────────────────────────────────────────────────────────────────────────────┤\n│                                                                              │\n│  ┌────────────────────────────────────────────────────────────────────────┐  │\n│  │                         EXTERNAL CLIENTS                               │  │\n│  │  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐                    │  │\n│  │  │   Next.js   │  │   Mobile    │  │   External  │                    │  │\n│  │  │  Frontend   │  │    Apps     │  │   Services  │                    │  │\n│  │  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘                    │  │\n│  └─────────┼────────────────┼────────────────┼───────────────────────────┘  │\n│            │                │                │                               │\n│            │    gRPC-Web    │     gRPC       │    REST/gRPC                 │\n│            ▼                ▼                ▼                               │\n│  ┌────────────────────────────────────────────────────────────────────────┐  │\n│  │                      INGRESS / LOAD BALANCER                           │  │\n│  │                   (NGINX Ingress Controller)                           │  │\n│  └────────────────────────────────────────────────────────────────────────┘  │\n│            │                                                                 │\n│            ▼                                                                 │\n│  ┌────────────────────────────────────────────────────────────────────────┐  │\n│  │                       MICROSERVICES                                    │  │\n│  │                                                                        │  │\n│  │  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐        │  │\n│  │  │ Finance Service │  │   IAM Service   │  │  Other Services │        │  │\n│  │  │   (gRPC+REST)   │  │   (gRPC+REST)   │  │   (gRPC+REST)   │        │  │\n│  │  │                 │  │                 │  │                 │        │  │\n│  │  │  Port 50051     │  │  Port 50052     │  │  Port 5005x     │        │  │\n│  │  │  Port 8080      │  │  Port 8081      │  │  Port 808x      │        │  │\n│  │  └────────┬────────┘  └────────┬────────┘  └────────┬────────┘        │  │\n│  └───────────┼────────────────────┼────────────────────┼─────────────────┘  │\n│              │                    │                    │                     │\n│              ▼                    ▼                    ▼                     │\n│  ┌────────────────────────────────────────────────────────────────────────┐  │\n│  │                       DATA LAYER                                       │  │\n│  │                                                                        │  │\n│  │  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐   │  │\n│  │  │ PostgreSQL  │  │    Redis    │  │  RabbitMQ   │  │   Oracle    │   │  │\n│  │  │ (Primary)   │  │   (Cache)   │  │  (Queue)    │  │  (Legacy)   │   │  │\n│  │  └─────────────┘  └─────────────┘  └─────────────┘  └─────────────┘   │  │\n│  └────────────────────────────────────────────────────────────────────────┘  │\n│                                                                              │\n│  ┌────────────────────────────────────────────────────────────────────────┐  │\n│  │                     OBSERVABILITY                                      │  │\n│  │                                                                        │  │\n│  │  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐                    │  │\n│  │  │ Prometheus  │  │   Jaeger    │  │    Loki     │                    │  │\n│  │  │  (Metrics)  │  │  (Tracing)  │  │   (Logs)    │                    │  │\n│  │  └─────────────┘  └─────────────┘  └─────────────┘                    │  │\n│  └────────────────────────────────────────────────────────────────────────┘  │\n└──────────────────────────────────────────────────────────────────────────────┘\n```\n\n### Clean Architecture\n\nEach service follows Clean Architecture with 4 layers:\n\n```mermaid\ngraph TB\n    subgraph \"Service Architecture\"\n        subgraph \"Delivery Layer\"\n            GRPC[gRPC Handlers]\n            HTTP[HTTP Gateway]\n        end\n        \n        subgraph \"Application Layer\"\n            UC[Use Cases]\n            DTO[DTOs/Mappers]\n        end\n        \n        subgraph \"Domain Layer\"\n            ENT[Entities]\n            VO[Value Objects]\n            REPO[Repository Interfaces]\n            ERR[Domain Errors]\n        end\n        \n        subgraph \"Infrastructure Layer\"\n            PG[PostgreSQL Repo]\n            REDIS[Redis Cache]\n            CFG[Config]\n            TRACE[Tracing]\n        end\n    end\n    \n    GRPC --\u003e UC\n    HTTP --\u003e UC\n    UC --\u003e ENT\n    UC --\u003e REPO\n    PG -.-\u003e REPO\n    REDIS -.-\u003e REPO\n```\n\n### Dependency Flow\n\n```\n┌─────────────────────────────────────────────────────────────────────────────┐\n│                         DEPENDENCY DIRECTION                                │\n│                                                                             │\n│   External World                                                            │\n│        │                                                                    │\n│        ▼                                                                    │\n│   ┌─────────────────┐                                                       │\n│   │    Delivery     │  ← Handles HTTP/gRPC requests                        │\n│   │  (grpc, http)   │  ← Depends on Application layer                      │\n│   └────────┬────────┘                                                       │\n│            │                                                                │\n│            ▼                                                                │\n│   ┌─────────────────┐                                                       │\n│   │   Application   │  ← Contains business logic (use cases)               │\n│   │   (use cases)   │  ← Depends on Domain layer                           │\n│   └────────┬────────┘                                                       │\n│            │                                                                │\n│            ▼                                                                │\n│   ┌─────────────────┐                                                       │\n│   │     Domain      │  ← Core business entities and rules                  │\n│   │(entities, repos)│  ← NO external dependencies                          │\n│   └────────┬────────┘                                                       │\n│            │                                                                │\n│            ▼                                                                │\n│   ┌─────────────────┐                                                       │\n│   │ Infrastructure  │  ← Implements domain interfaces                      │\n│   │(postgres, redis)│  ← Can depend on external packages                   │\n│   └─────────────────┘                                                       │\n│                                                                             │\n│   KEY: Inner layers MUST NOT depend on outer layers                         │\n└─────────────────────────────────────────────────────────────────────────────┘\n```\n\n---\n\n## Technology Stack\n\n### Core\n\n| Component | Version | Description |\n|-----------|---------|-------------|\n| Go | 1.24 | Programming language |\n| gRPC | 1.78.0 | RPC framework |\n| gRPC-Gateway | 2.27.7 | REST API from gRPC |\n| Protocol Buffers | 3.x | Interface definition |\n| Buf | v2 | Protobuf management |\n\n### Database \u0026 Storage\n\n| Component | Version | Description |\n|-----------|---------|-------------|\n| PostgreSQL | 18 | Primary database |\n| pgx | 5.8.0 | PostgreSQL driver |\n| Redis | 7 | Caching layer |\n| go-redis | 9.17.3 | Redis client |\n\n### Observability\n\n| Component | Description |\n|-----------|-------------|\n| zerolog | Structured logging |\n| OpenTelemetry | Distributed tracing |\n| Prometheus client | Metrics exposure |\n\n### Development\n\n| Tool | Version | Description |\n|------|---------|-------------|\n| golangci-lint | v2.3.0 | Code linting (20+ linters) |\n| golang-migrate | v4.18.1 | Database migrations |\n| testify | 1.11.1 | Testing assertions |\n| excelize | 2.8.1 | Excel file processing |\n\n---\n\n## Repository Structure\n\n```\ngoapps-backend/\n│\n├── 📁 services/                     # Microservices\n│   └── finance/                     # Finance service\n│       ├── cmd/                     # Entry points\n│       │   └── server/              # Main server\n│       │       └── main.go\n│       ├── internal/                # Private code\n│       │   ├── domain/              # Domain layer\n│       │   │   └── uom/             # UOM domain\n│       │   │       ├── entity.go        # Domain entity\n│       │   │       ├── value_object.go  # Value objects\n│       │   │       ├── repository.go    # Repository interface\n│       │   │       └── errors.go        # Domain errors\n│       │   ├── application/         # Application layer\n│       │   │   └── uom/             # UOM use cases\n│       │   │       ├── service.go       # Business logic\n│       │   │       ├── dto.go           # Data transfer objects\n│       │   │       └── mapper.go        # Entity ↔ DTO mapping\n│       │   ├── infrastructure/      # Infrastructure layer\n│       │   │   ├── config/          # Configuration\n│       │   │   ├── postgres/        # PostgreSQL implementation\n│       │   │   ├── redis/           # Redis caching\n│       │   │   ├── tracing/         # OpenTelemetry setup\n│       │   │   └── audit/           # Audit logging\n│       │   └── delivery/            # Delivery layer\n│       │       ├── grpc/            # gRPC handlers\n│       │       └── httpdelivery/    # HTTP gateway\n│       ├── pkg/                     # Shared utilities\n│       │   ├── logger/              # Logging helpers\n│       │   ├── circuitbreaker/      # Circuit breaker\n│       │   ├── response/            # Response helpers\n│       │   └── safeconv/            # Safe type conversions\n│       ├── migrations/              # Database migrations\n│       │   └── postgres/\n│       ├── deployments/             # Deployment configs\n│       │   ├── docker-compose.yaml\n│       │   └── kubernetes/\n│       ├── tests/                   # Tests\n│       │   ├── e2e/                 # End-to-end tests\n│       │   └── loadtest/            # Load tests\n│       ├── docs/                    # Service docs\n│       ├── Dockerfile               # Multi-stage build\n│       ├── Makefile                 # Service-specific targets\n│       ├── config.yaml              # Default config\n│       ├── go.mod\n│       └── go.sum\n│\n├── 📁 gen/                          # Generated code\n│   ├── common/v1/                   # Common proto types\n│   ├── finance/v1/                  # Finance proto types\n│   ├── openapi/                     # OpenAPI specs\n│   ├── go.mod\n│   └── go.sum\n│\n├── 📁 deploy/                       # Deployment assets\n│\n├── 📁 .github/                      # GitHub Actions\n│   ├── workflows/\n│   │   ├── finance-service.yml     # Finance CI/CD\n│   │   └── release-please.yml      # Release automation\n│   ├── ISSUE_TEMPLATE/\n│   └── PULL_REQUEST_TEMPLATE.md\n│\n├── .golangci.yml                    # Linter configuration\n├── .gitignore\n├── Makefile                         # Root Makefile\n├── README.md                        # This file\n├── RULES.md                         # Development rules\n├── CONTRIBUTING.md                  # Contribution guide\n└── LICENSE                          # Proprietary license\n```\n\n---\n\n## Quick Start\n\n### Prerequisites\n\n- **Go 1.24+** - [Download](https://go.dev/dl/)\n- **Docker \u0026 Docker Compose** - For local development\n- **Buf CLI** - Protocol buffer management\n- **golangci-lint** - Code linting\n- **golang-migrate** - Database migrations\n\n### Install Tools\n\n```bash\n# Install Buf CLI\n# See: https://buf.build/docs/installation\n\n# Install golangci-lint\ncurl -sSfL https://raw.githubusercontent.com/golangci/golangci-lint/HEAD/install.sh | sh -s -- -b $(go env GOPATH)/bin v2.3.0\n\n# Install golang-migrate\ngo install -tags 'postgres' github.com/golang-migrate/migrate/v4/cmd/migrate@latest\n```\n\n### Setup Development Environment\n\n```bash\n# 1. Clone repository\ngit clone https://github.com/mutugading/goapps-backend.git\ncd goapps-backend\n\n# 2. Generate proto code (if needed)\nmake proto\n\n# 3. Start infrastructure\ncd services/finance\ndocker compose -f deployments/docker-compose.yaml up -d postgres redis\n\n# 4. Run migrations\nexport DATABASE_URL=\"postgres://finance:finance123@localhost:5434/finance_db?sslmode=disable\"\nmake finance-migrate\n\n# 5. Run service\nmake finance-run\n```\n\n### Verify Installation\n\n```bash\n# Check gRPC endpoint\ngrpcurl -plaintext localhost:50051 list\n\n# Check HTTP endpoint\ncurl http://localhost:8080/healthz\n\n# Check metrics\ncurl http://localhost:8080/metrics\n```\n\n---\n\n## Services\n\n### Finance Service\n\nThe Finance Service manages financial data including Units of Measure (UOM).\n\n| Property | Value |\n|----------|-------|\n| **Path** | `services/finance` |\n| **gRPC Port** | 50051 |\n| **HTTP Port** | 8080 |\n| **Metrics** | `/metrics` on HTTP port |\n| **Health** | `/healthz` on HTTP port |\n\n#### API Endpoints\n\n**gRPC Services:**\n- `UOMService.CreateUOM` - Create new unit of measure\n- `UOMService.GetUOM` - Get UOM by ID\n- `UOMService.ListUOMs` - List all UOMs with filtering\n- `UOMService.UpdateUOM` - Update existing UOM\n- `UOMService.DeleteUOM` - Soft delete UOM\n- `UOMService.ImportUOMs` - Bulk import from Excel\n- `UOMService.ExportUOMs` - Export to Excel\n\n**REST Endpoints (via gRPC-Gateway):**\n```\nPOST   /api/v1/finance/uom\nGET    /api/v1/finance/uom/{id}\nGET    /api/v1/finance/uom\nPUT    /api/v1/finance/uom/{id}\nDELETE /api/v1/finance/uom/{id}\nPOST   /api/v1/finance/uom/import\nGET    /api/v1/finance/uom/export\n```\n\n#### Configuration\n\nEnvironment variables override `config.yaml`:\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `APP_ENV` | development | Environment (development/staging/production) |\n| `DATABASE_HOST` | localhost | PostgreSQL host |\n| `DATABASE_PORT` | 5434 | PostgreSQL port |\n| `DATABASE_USER` | finance | Database user |\n| `DATABASE_PASSWORD` | - | Database password |\n| `DATABASE_NAME` | finance_db | Database name |\n| `REDIS_HOST` | localhost | Redis host |\n| `REDIS_PORT` | 6379 | Redis port |\n| `TRACING_ENABLED` | true | Enable OpenTelemetry |\n| `JAEGER_ENDPOINT` | localhost:4317 | Jaeger collector |\n\n---\n\n## Development\n\n### Makefile Targets\n\n**Root Makefile:**\n\n```bash\nmake help              # Show all targets\nmake proto             # Generate proto code\nmake lint              # Run golangci-lint\nmake lint-fix          # Auto-fix lint issues\nmake test              # Run all tests\nmake test-coverage     # Run tests with coverage\nmake clean             # Clean build artifacts\n```\n\n**Finance Service:**\n\n```bash\nmake finance-run       # Run service locally\nmake finance-build     # Build binary\nmake finance-migrate   # Run DB migrations\nmake finance-seed      # Run seeders\nmake finance-docker    # Build Docker image\n```\n\n### Code Generation\n\nProto files are in `goapps-shared-proto`. To regenerate:\n\n```bash\n# From goapps-backend root\nmake proto\n\n# Or from goapps-shared-proto\ncd ../goapps-shared-proto\n./scripts/gen-go.sh\n```\n\nGenerated code is placed in `gen/` directory.\n\n### Database Migrations\n\n```bash\n# Create new migration\nmigrate create -ext sql -dir services/finance/migrations/postgres -seq add_new_table\n\n# Run migrations\nexport DATABASE_URL=\"postgres://user:pass@host:port/db?sslmode=disable\"\nmigrate -path services/finance/migrations/postgres -database \"$DATABASE_URL\" up\n\n# Rollback last migration\nmigrate -path services/finance/migrations/postgres -database \"$DATABASE_URL\" down 1\n```\n\n---\n\n## Testing\n\n### Test Categories\n\n| Type | Directory | Command | Description |\n|------|-----------|---------|-------------|\n| Unit | `internal/` | `go test -short ./internal/...` | Isolated component tests |\n| Integration | `internal/infrastructure/` | `go test ./internal/infrastructure/...` | Database/Redis tests |\n| E2E | `tests/e2e/` | `go test ./tests/e2e/...` | Full API tests |\n| Load | `tests/loadtest/` | Custom | Performance tests |\n\n### Running Tests\n\n```bash\n# Unit tests only\ngo test -v -race -short ./...\n\n# All tests (requires running PostgreSQL/Redis)\ngo test -v -race ./...\n\n# With coverage\ngo test -v -race -coverprofile=coverage.out ./...\ngo tool cover -html=coverage.out -o coverage.html\n\n# Specific package\ngo test -v ./internal/domain/uom/...\n```\n\n### Integration Test Setup\n\nIntegration tests require PostgreSQL and Redis:\n\n```bash\n# Start test infrastructure\ndocker compose -f deployments/docker-compose.yaml up -d postgres redis\n\n# Run migrations\nmigrate -path migrations/postgres \\\n  -database \"postgres://finance:finance123@localhost:5434/finance_db_test?sslmode=disable\" \\\n  up\n\n# Run integration tests\nINTEGRATION_TEST=true go test -v ./internal/infrastructure/...\n```\n\n---\n\n## CI/CD Pipeline\n\n### Workflow Overview\n\n```mermaid\ngraph LR\n    subgraph \"CI Pipeline\"\n        A[Push/PR] --\u003e B[Lint]\n        A --\u003e C[Test]\n        B --\u003e D{Pass?}\n        C --\u003e D\n        D --\u003e|Yes| E[Build]\n        D --\u003e|No| F[Fail]\n        E --\u003e G[Docker Build]\n    end\n    \n    subgraph \"CD Pipeline\"\n        G --\u003e H[E2E Tests]\n        H --\u003e I[Deploy Staging]\n        I --\u003e J[Deploy Production]\n    end\n```\n\n### Jobs\n\n| Job | Trigger | Description |\n|-----|---------|-------------|\n| `lint` | Push/PR | golangci-lint validation |\n| `test` | Push/PR | Unit + integration tests |\n| `build` | After lint+test | Compile binary |\n| `docker` | Push to main | Build \u0026 push to GHCR |\n| `e2e` | After docker | End-to-end tests |\n| `deploy-staging` | After e2e | Auto-deploy via ArgoCD |\n| `deploy-production` | After staging | Manual approval required |\n\n### Self-Hosted Runners\n\nDeployments use self-hosted runners in VPS:\n\n```yaml\nruns-on: [self-hosted, staging, goapps-runner]\n```\n\n---\n\n## Deployment\n\n### Container Registry\n\nImages are pushed to GitHub Container Registry:\n\n```\nghcr.io/mutugading/finance-service:latest\nghcr.io/mutugading/finance-service:\u003csha\u003e\nghcr.io/mutugading/finance-service:main\n```\n\n### Kubernetes\n\nKubernetes manifests are in `goapps-infra` repository:\n\n```\ngoapps-infra/services/finance-service/\n├── base/\n│   ├── deployment.yaml\n│   ├── service.yaml\n│   └── hpa.yaml\n└── overlays/\n    ├── staging/\n    └── production/\n```\n\n### ArgoCD\n\nServices are auto-synced via ArgoCD:\n\n1. Push to `main` triggers Docker build\n2. New image pushed to GHCR\n3. ArgoCD detects new image tag\n4. Auto-sync deploys to staging\n5. Manual sync deploys to production\n\n---\n\n## API Documentation\n\n### OpenAPI / Swagger\n\nOpenAPI specs are generated from proto files:\n\n```\ngen/openapi/\n├── finance/v1/uom.swagger.json\n└── common/v1/common.swagger.json\n```\n\n### Proto Definitions\n\nSource proto files in `goapps-shared-proto`:\n\n```protobuf\n// finance/v1/uom.proto\nservice UOMService {\n  rpc CreateUOM(CreateUOMRequest) returns (CreateUOMResponse);\n  rpc GetUOM(GetUOMRequest) returns (GetUOMResponse);\n  rpc ListUOMs(ListUOMsRequest) returns (ListUOMsResponse);\n  rpc UpdateUOM(UpdateUOMRequest) returns (UpdateUOMResponse);\n  rpc DeleteUOM(DeleteUOMRequest) returns (DeleteUOMResponse);\n}\n```\n\n### gRPC Reflection\n\ngRPC reflection is enabled. Use grpcurl to explore:\n\n```bash\n# List services\ngrpcurl -plaintext localhost:50051 list\n\n# Describe service\ngrpcurl -plaintext localhost:50051 describe finance.v1.UOMService\n\n# Call method\ngrpcurl -plaintext -d '{\"code\": \"KG\", \"name\": \"Kilogram\"}' \\\n  localhost:50051 finance.v1.UOMService/CreateUOM\n```\n\n---\n\n## Troubleshooting\n\n### Common Issues\n\n#### Cannot connect to database\n\n```bash\n# Check PostgreSQL is running\ndocker ps | grep postgres\n\n# Test connection\npsql -h localhost -p 5434 -U finance -d finance_db\n\n# Check logs\ndocker logs \u003cpostgres-container-id\u003e\n```\n\n#### gRPC connection refused\n\n```bash\n# Check service is running\nlsof -i :50051\n\n# Check logs\ntail -f /path/to/service.log\n\n# Test with grpcurl\ngrpcurl -plaintext localhost:50051 list\n```\n\n#### Migration failed\n\n```bash\n# Check migration status\nmigrate -path migrations/postgres -database \"$DATABASE_URL\" version\n\n# Force version (use with caution)\nmigrate -path migrations/postgres -database \"$DATABASE_URL\" force \u003cversion\u003e\n\n# Check migration files\nls -la migrations/postgres/\n```\n\n#### Lint errors\n\n```bash\n# Run with verbose output\ngolangci-lint run -v ./...\n\n# Fix auto-fixable issues\ngolangci-lint run --fix ./...\n\n# Check specific linter\ngolangci-lint run --enable=errcheck ./...\n```\n\n### Useful Commands\n\n```bash\n# Check service health\ncurl http://localhost:8080/healthz\n\n# View metrics\ncurl http://localhost:8080/metrics | grep go_\n\n# Tail logs (with zerolog pretty print)\ngo run cmd/server/main.go 2\u003e\u00261 | jq\n\n# Profile CPU\ngo tool pprof http://localhost:8080/debug/pprof/profile?seconds=30\n\n# Profile memory\ngo tool pprof http://localhost:8080/debug/pprof/heap\n```\n\n---\n\n## Related Documentation\n\n| Document | Path | Description |\n|----------|------|-------------|\n| Development Rules | [RULES.md](./RULES.md) | Coding conventions |\n| Contributing Guide | [CONTRIBUTING.md](./CONTRIBUTING.md) | How to contribute |\n| License | [LICENSE](./LICENSE) | Proprietary license |\n\n### Issue Templates\n\n| Template | Description |\n|----------|-------------|\n| [🐛 Bug Report](.github/ISSUE_TEMPLATE/bug_report.md) | Report bugs or issues |\n| [✨ Feature Request](.github/ISSUE_TEMPLATE/feature_request.md) | Request new features |\n| [🚀 New Service](.github/ISSUE_TEMPLATE/new_service.md) | Request new microservice |\n\n### External Resources\n\n- [Go Documentation](https://go.dev/doc/)\n- [gRPC Documentation](https://grpc.io/docs/)\n- [Buf Documentation](https://buf.build/docs/)\n- [Clean Architecture](https://blog.cleancoder.com/uncle-bob/2012/08/13/the-clean-architecture.html)\n\n---\n\n## Support \u0026 Contact\n\n- **Team**: GoApps Backend\n- **Organization**: PT Mutu Gading Tekstil\n- **Repository Issues**: [GitHub Issues](https://github.com/mutugading/goapps-backend/issues)\n\n---\n\n## License\n\nThis project is proprietary software. See the [LICENSE](./LICENSE) file for details.\n\n**© 2024-2026 PT Mutu Gading Tekstil. All Rights Reserved.**\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmutugading%2Fgoapps-backend","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmutugading%2Fgoapps-backend","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmutugading%2Fgoapps-backend/lists"}