{"id":43982244,"url":"https://github.com/mutugading/goapps-shared-proto","last_synced_at":"2026-02-07T09:05:56.434Z","repository":{"id":335604726,"uuid":"1145840975","full_name":"mutugading/goapps-shared-proto","owner":"mutugading","description":null,"archived":false,"fork":false,"pushed_at":"2026-01-31T05:52:45.000Z","size":13,"stargazers_count":2,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-31T19:35:42.373Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Shell","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/mutugading.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":"2026-01-30T09:30:03.000Z","updated_at":"2026-01-31T05:52:49.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/mutugading/goapps-shared-proto","commit_stats":null,"previous_names":["mutugading/goapps-shared-proto"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/mutugading/goapps-shared-proto","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mutugading%2Fgoapps-shared-proto","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mutugading%2Fgoapps-shared-proto/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mutugading%2Fgoapps-shared-proto/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mutugading%2Fgoapps-shared-proto/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mutugading","download_url":"https://codeload.github.com/mutugading/goapps-shared-proto/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mutugading%2Fgoapps-shared-proto/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29190842,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-07T07:37:03.739Z","status":"ssl_error","status_checked_at":"2026-02-07T07:37:03.029Z","response_time":63,"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":[],"created_at":"2026-02-07T09:05:55.692Z","updated_at":"2026-02-07T09:05:56.427Z","avatar_url":"https://github.com/mutugading.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# GoApps Shared Proto\n\n**Single source of truth** for Protocol Buffer definitions used across the GoApps Platform.\n\n---\n\n## 📋 Table of Contents\n\n1. [Overview](#overview)\n2. [Repository Structure](#repository-structure)\n3. [Quick Start](#quick-start)\n4. [Proto Organization](#proto-organization)\n5. [Services](#services)\n6. [Common Types](#common-types)\n7. [Code Generation](#code-generation)\n8. [Buf Configuration](#buf-configuration)\n9. [Validation Rules](#validation-rules)\n10. [REST API Mapping](#rest-api-mapping)\n11. [CI/CD Pipeline](#cicd-pipeline)\n12. [Breaking Changes](#breaking-changes)\n13. [Related Documentation](#related-documentation)\n\n---\n\n## Overview\n\nThis repository contains all Protocol Buffer (`.proto`) definitions for the GoApps microservices ecosystem. It serves as the single source of truth for API contracts between:\n\n- **Backend Services** (Go gRPC servers)\n- **Frontend Application** (Next.js with gRPC client)\n- **API Documentation** (OpenAPI/Swagger)\n\n### GoApps Ecosystem\n\n```\ngoapps/\n├── goapps-shared-proto/   # 📝 Proto definitions (this repo)\n├── goapps-backend/        # 🖥️  Backend microservices\n├── goapps-frontend/       # 🌐 Frontend application\n└── goapps-infra/          # 🔧 Infrastructure as Code\n```\n\n### Generated Outputs\n\n| Target | Output Directory | Plugin |\n|--------|-----------------|--------|\n| Go Structs | `goapps-backend/gen/` | protocolbuffers/go |\n| gRPC Stubs | `goapps-backend/gen/` | grpc/go |\n| REST Gateway | `goapps-backend/gen/` | grpc-ecosystem/gateway |\n| OpenAPI Spec | `goapps-backend/gen/openapi/` | grpc-ecosystem/openapiv2 |\n\n---\n\n## Repository Structure\n\n```\ngoapps-shared-proto/\n│\n├── 📁 common/                    # Shared types across services\n│   └── v1/\n│       └── common.proto          # BaseResponse, Pagination, AuditInfo\n│\n├── 📁 finance/                   # Finance domain protos\n│   └── v1/\n│       └── uom.proto             # UOM service (CRUD, Import, Export)\n│\n├── 📁 iam/                       # IAM domain (future)\n│   └── v1/\n│       └── ...                   # User, Role, Permission\n│\n├── 📁 scripts/\n│   ├── gen-go.sh                 # Generate Go code\n│   └── gen-ts.sh                 # Generate TypeScript types\n│\n├── 📁 .github/\n│   └── workflows/\n│       └── ci.yml                # Lint, breaking check, auto-generate\n│\n├── buf.yaml                      # Buf module configuration\n├── buf.gen.yaml                  # Code generation config\n├── buf.lock                      # Dependency lock file\n├── README.md                     # This file\n├── RULES.md                      # Development conventions\n├── CONTRIBUTING.md               # Contribution guide\n└── LICENSE                       # Proprietary license\n```\n\n---\n\n## Quick Start\n\n### Prerequisites\n\n- **Buf CLI** - [Install](https://buf.build/docs/installation)\n- **Go 1.24+** - For generated code (optional)\n\n### Install Buf\n\n```bash\n# macOS\nbrew install bufbuild/buf/buf\n\n# Linux\nBIN=\"/usr/local/bin\" \u0026\u0026 \\\nVERSION=\"1.47.2\" \u0026\u0026 \\\ncurl -sSL \\\n  \"https://github.com/bufbuild/buf/releases/download/v${VERSION}/buf-$(uname -s)-$(uname -m)\" \\\n  -o \"${BIN}/buf\" \u0026\u0026 \\\nchmod +x \"${BIN}/buf\"\n\n# Verify installation\nbuf --version\n```\n\n### Clone and Setup\n\n```bash\n# Clone repository\ngit clone https://github.com/mutugading/goapps-shared-proto.git\ncd goapps-shared-proto\n\n# Update dependencies\nbuf dep update\n\n# Lint proto files\nbuf lint\n\n# Format proto files\nbuf format -w\n```\n\n---\n\n## Proto Organization\n\n### Package Naming\n\n```\n\u003cdomain\u003e/\u003cversion\u003e/\u003cservice\u003e.proto\n```\n\n| Pattern | Example |\n|---------|---------|\n| `{domain}/v{n}/` | `finance/v1/`, `iam/v1/` |\n| `common/v{n}/` | `common/v1/` (shared types) |\n\n### Versioning Strategy\n\n| Version | Description | Breaking Changes |\n|---------|-------------|------------------|\n| `v1` | Initial stable version | Not allowed |\n| `v2` | Major revision | Allowed (parallel support) |\n| `v1alpha1` | Experimental | Allowed anytime |\n| `v1beta1` | Pre-release | Discouraged |\n\n---\n\n## Services\n\n### Finance Module\n\n#### UOMService\n\nManages Units of Measure (UOM) master data.\n\n| Method | Description | REST Endpoint |\n|--------|-------------|---------------|\n| `CreateUOM` | Create new UOM | `POST /api/v1/finance/uoms` |\n| `GetUOM` | Get UOM by ID | `GET /api/v1/finance/uoms/{uom_id}` |\n| `UpdateUOM` | Update UOM | `PUT /api/v1/finance/uoms/{uom_id}` |\n| `DeleteUOM` | Soft delete UOM | `DELETE /api/v1/finance/uoms/{uom_id}` |\n| `ListUOMs` | List with search/filter | `GET /api/v1/finance/uoms` |\n| `ExportUOMs` | Export to Excel | `GET /api/v1/finance/uoms/export` |\n| `ImportUOMs` | Import from Excel | `POST /api/v1/finance/uoms/import` |\n| `DownloadTemplate` | Get import template | `GET /api/v1/finance/uoms/template` |\n\n**Proto file**: `finance/v1/uom.proto`\n\n#### UOM Message\n\n```protobuf\nmessage UOM {\n  string uom_id = 1;          // UUID\n  string uom_code = 2;        // e.g., \"KG\", \"MTR\", \"PCS\"\n  string uom_name = 3;        // e.g., \"Kilogram\", \"Meter\"\n  UOMCategory uom_category = 4;  // WEIGHT, LENGTH, VOLUME, QUANTITY\n  string description = 5;\n  bool is_active = 6;\n  common.v1.AuditInfo audit = 7;\n}\n```\n\n---\n\n## Common Types\n\nLocated in `common/v1/common.proto`:\n\n### BaseResponse\n\nStandard response wrapper for all API responses.\n\n```protobuf\nmessage BaseResponse {\n  repeated ValidationError validation_errors = 1;\n  string status_code = 2;     // \"200\", \"400\", \"404\", \"500\"\n  bool is_success = 3;\n  string message = 4;\n}\n```\n\n### PaginationRequest / PaginationResponse\n\n```protobuf\nmessage PaginationRequest {\n  int32 page = 1;             // 1-indexed\n  int32 page_size = 2;\n}\n\nmessage PaginationResponse {\n  int32 current_page = 1;\n  int32 page_size = 2;\n  int64 total_items = 3;\n  int32 total_pages = 4;\n}\n```\n\n### AuditInfo\n\nAudit trail for all entities.\n\n```protobuf\nmessage AuditInfo {\n  string created_at = 1;      // ISO 8601\n  string created_by = 2;\n  string updated_at = 3;\n  string updated_by = 4;\n}\n```\n\n---\n\n## Code Generation\n\n### Generate All (Go + OpenAPI)\n\n```bash\n# From goapps-shared-proto directory\n./scripts/gen-go.sh\n```\n\nThis script:\n1. Updates buf dependencies\n2. Formats proto files\n3. Lints proto files\n4. Generates code to `goapps-backend/gen/`\n5. Runs `go mod tidy`\n\n### Generate TypeScript (Optional)\n\n```bash\n./scripts/gen-ts.sh\n```\n\nOr manually with proto-loader:\n\n```bash\ncd ../goapps-frontend\nnpx proto-loader-gen-types \\\n  --longs=String \\\n  --enums=String \\\n  --defaults \\\n  --oneofs \\\n  --grpcLib=@grpc/grpc-js \\\n  --outDir=src/lib/grpc/generated \\\n  ../goapps-shared-proto/**/*.proto\n```\n\n### Generated File Structure\n\n```\ngoapps-backend/gen/\n├── common/\n│   └── v1/\n│       └── common.pb.go\n├── finance/\n│   └── v1/\n│       ├── uom.pb.go           # Messages\n│       ├── uom_grpc.pb.go      # gRPC service\n│       └── uom.pb.gw.go        # REST gateway\n├── openapi/\n│   └── finance/\n│       └── v1/\n│           └── uom.swagger.json\n├── go.mod\n└── go.sum\n```\n\n---\n\n## Buf Configuration\n\n### buf.yaml\n\n```yaml\nversion: v2\nmodules:\n  - path: .\n    name: buf.build/goapps/shared-proto\nbreaking:\n  use:\n    - FILE                    # Breaking change detection strategy\nlint:\n  use:\n    - STANDARD                # Standard lint rules\n  except:\n    - PACKAGE_VERSION_SUFFIX  # Allow finance/v1 instead of finance.v1\ndeps:\n  - buf.build/googleapis/googleapis      # google/api/annotations.proto\n  - buf.build/bufbuild/protovalidate     # buf/validate/validate.proto\n```\n\n### buf.gen.yaml\n\n```yaml\nversion: v2\nmanaged:\n  enabled: true\n  override:\n    - file_option: go_package_prefix\n      value: github.com/mutugading/goapps-backend/gen\n      path: .\nplugins:\n  # Go protobuf structs\n  - remote: buf.build/protocolbuffers/go\n    out: ../goapps-backend/gen\n    opt: paths=source_relative\n  \n  # gRPC service stubs\n  - remote: buf.build/grpc/go\n    out: ../goapps-backend/gen\n    opt: paths=source_relative\n  \n  # gRPC-Gateway for REST API\n  - remote: buf.build/grpc-ecosystem/gateway\n    out: ../goapps-backend/gen\n    opt: paths=source_relative\n  \n  # OpenAPI/Swagger documentation\n  - remote: buf.build/grpc-ecosystem/openapiv2\n    out: ../goapps-backend/gen/openapi\n\ninputs:\n  - directory: .\n    paths:\n      - common\n      - finance\n```\n\n---\n\n## Validation Rules\n\nUsing [buf/validate](https://buf.build/bufbuild/protovalidate):\n\n### String Validation\n\n```protobuf\nimport \"buf/validate/validate.proto\";\n\nmessage CreateUOMRequest {\n  // Required, 1-20 chars, uppercase alphanumeric\n  string uom_code = 1 [(buf.validate.field).string = {\n    min_len: 1\n    max_len: 20\n    pattern: \"^[A-Z][A-Z0-9_]*$\"\n  }];\n  \n  // Required, 1-100 chars\n  string uom_name = 2 [(buf.validate.field).string = {\n    min_len: 1\n    max_len: 100\n  }];\n}\n```\n\n### UUID Validation\n\n```protobuf\nstring uom_id = 1 [(buf.validate.field).string.uuid = true];\n```\n\n### Enum Validation\n\n```protobuf\n// Cannot be UNSPECIFIED (0)\nUOMCategory uom_category = 3 [(buf.validate.field).enum = {\n  not_in: [0]\n}];\n```\n\n### Numeric Validation\n\n```protobuf\n// Page number: minimum 1\nint32 page = 1 [(buf.validate.field).int32.gte = 1];\n\n// Page size: 1-100\nint32 page_size = 2 [(buf.validate.field).int32 = {\n  gte: 1\n  lte: 100\n}];\n```\n\n### Bytes Validation\n\n```protobuf\n// File upload: 1 byte to 10MB\nbytes file_content = 1 [(buf.validate.field).bytes = {\n  min_len: 1\n  max_len: 10485760\n}];\n```\n\n---\n\n## REST API Mapping\n\nUsing [google/api/annotations.proto](https://buf.build/googleapis/googleapis):\n\n### CRUD Mapping\n\n```protobuf\nimport \"google/api/annotations.proto\";\n\nservice UOMService {\n  // Create: POST with body\n  rpc CreateUOM(CreateUOMRequest) returns (CreateUOMResponse) {\n    option (google.api.http) = {\n      post: \"/api/v1/finance/uoms\"\n      body: \"*\"\n    };\n  }\n  \n  // Read: GET with path parameter\n  rpc GetUOM(GetUOMRequest) returns (GetUOMResponse) {\n    option (google.api.http) = {\n      get: \"/api/v1/finance/uoms/{uom_id}\"\n    };\n  }\n  \n  // Update: PUT with path parameter and body\n  rpc UpdateUOM(UpdateUOMRequest) returns (UpdateUOMResponse) {\n    option (google.api.http) = {\n      put: \"/api/v1/finance/uoms/{uom_id}\"\n      body: \"*\"\n    };\n  }\n  \n  // Delete: DELETE with path parameter\n  rpc DeleteUOM(DeleteUOMRequest) returns (DeleteUOMResponse) {\n    option (google.api.http) = {\n      delete: \"/api/v1/finance/uoms/{uom_id}\"\n    };\n  }\n  \n  // List: GET with query parameters\n  rpc ListUOMs(ListUOMsRequest) returns (ListUOMsResponse) {\n    option (google.api.http) = {\n      get: \"/api/v1/finance/uoms\"\n    };\n  }\n}\n```\n\n### Query Parameter Mapping\n\nFor `GET /api/v1/finance/uoms?page=1\u0026page_size=10\u0026search=kg`:\n\n```protobuf\nmessage ListUOMsRequest {\n  int32 page = 1;        // ?page=1\n  int32 page_size = 2;   // ?page_size=10\n  string search = 3;     // ?search=kg\n  UOMCategory category = 4;  // ?category=WEIGHT\n}\n```\n\n---\n\n## CI/CD Pipeline\n\n### Workflow Triggers\n\n| Event | Jobs |\n|-------|------|\n| Push to `main` | Lint → Breaking Check → Generate |\n| Pull Request | Lint → Breaking Check |\n\n### Jobs\n\n#### Lint \u0026 Breaking Changes\n\n```yaml\n- name: Lint proto files\n  run: buf lint\n\n- name: Check breaking changes\n  run: buf breaking --against 'https://github.com/mutugading/goapps-shared-proto.git#branch=main'\n```\n\n#### Auto-Generate (main only)\n\nOn push to main, automatically:\n1. Generates code\n2. Commits to `goapps-backend` repo\n3. Creates commit: `chore(proto): regenerate from shared-proto`\n\n---\n\n## Breaking Changes\n\n### What is a Breaking Change?\n\n| Change Type | Breaking? | Example |\n|-------------|-----------|---------|\n| Remove field | ✅ Yes | Removing `description` field |\n| Rename field | ✅ Yes | `uom_code` → `code` |\n| Change field number | ✅ Yes | `string name = 2` → `string name = 3` |\n| Change field type | ✅ Yes | `string id` → `int64 id` |\n| Add required validation | ✅ Yes | Adding `min_len: 1` |\n| Add field | ❌ No | Adding optional `notes` field |\n| Add enum value | ❌ No | Adding `UOM_CATEGORY_AREA` |\n| Add RPC method | ❌ No | Adding `BulkDeleteUOMs` |\n\n### How to Handle Breaking Changes\n\n1. **Option A: New Version**\n   ```\n   finance/v2/uom.proto  # New version with breaking changes\n   finance/v1/uom.proto  # Keep v1 for backward compatibility\n   ```\n\n2. **Option B: Deprecate and Add**\n   ```protobuf\n   message UOM {\n     reserved 5;              // Reserved old field number\n     reserved \"old_field\";    // Reserved old field name\n     string new_field = 6;    // New field\n   }\n   ```\n\n### Checking Locally\n\n```bash\n# Check against main branch\nbuf breaking --against '.git#branch=main'\n\n# Check against specific commit\nbuf breaking --against '.git#ref=abc123'\n```\n\n---\n\n## Related Documentation\n\n| Document | Path | Description |\n|----------|------|-------------|\n| Development Rules | [RULES.md](./RULES.md) | Proto conventions |\n| Contributing Guide | [CONTRIBUTING.md](./CONTRIBUTING.md) | How to contribute |\n| License | [LICENSE](./LICENSE) | Proprietary license |\n\n### External Resources\n\n- [Buf Documentation](https://buf.build/docs)\n- [Protocol Buffers](https://protobuf.dev)\n- [gRPC Documentation](https://grpc.io/docs)\n- [gRPC-Gateway](https://grpc-ecosystem.github.io/grpc-gateway)\n- [Protovalidate](https://github.com/bufbuild/protovalidate)\n- [Google API Guidelines](https://google.aip.dev)\n\n---\n\n## Support \u0026 Contact\n\n- **Team**: GoApps Platform\n- **Organization**: PT Mutu Gading Tekstil\n- **Repository Issues**: [GitHub Issues](https://github.com/mutugading/goapps-shared-proto/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-shared-proto","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmutugading%2Fgoapps-shared-proto","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmutugading%2Fgoapps-shared-proto/lists"}