{"id":50697286,"url":"https://github.com/linuxfoundation/lfx-v2-survey-service","last_synced_at":"2026-06-09T07:30:44.923Z","repository":{"id":336490434,"uuid":"1139437941","full_name":"linuxfoundation/lfx-v2-survey-service","owner":"linuxfoundation","description":"LFX v2 Platform Survey Service","archived":false,"fork":false,"pushed_at":"2026-06-05T20:26:57.000Z","size":642,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-05T22:13:42.805Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":false,"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/linuxfoundation.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-22T00:42:54.000Z","updated_at":"2026-06-03T22:20:35.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/linuxfoundation/lfx-v2-survey-service","commit_stats":null,"previous_names":["linuxfoundation/lfx-v2-survey-service"],"tags_count":16,"template":false,"template_full_name":null,"purl":"pkg:github/linuxfoundation/lfx-v2-survey-service","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/linuxfoundation%2Flfx-v2-survey-service","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/linuxfoundation%2Flfx-v2-survey-service/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/linuxfoundation%2Flfx-v2-survey-service/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/linuxfoundation%2Flfx-v2-survey-service/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/linuxfoundation","download_url":"https://codeload.github.com/linuxfoundation/lfx-v2-survey-service/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/linuxfoundation%2Flfx-v2-survey-service/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34096950,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-09T02:00:06.510Z","response_time":63,"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":[],"created_at":"2026-06-09T07:30:44.426Z","updated_at":"2026-06-09T07:30:44.918Z","avatar_url":"https://github.com/linuxfoundation.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# LFX V2 Survey Service\n\nA proxy service that provides a REST API wrapper around the ITX survey system, built using the Goa framework.\n\n## Overview\n\nThe LFX V2 Survey Service acts as a secure intermediary between LFX Platform V2 and the ITX survey backend. It handles authentication, authorization, ID mapping between v1 and v2 systems, and provides a clean REST API interface for survey management.\n\n**Proxy Architecture**: This service is a stateless HTTP proxy that translates LFX v2 REST API calls into ITX API calls. All survey data is stored and managed by the ITX service and SurveyMonkey. The proxy handles:\n\n- **Authentication Translation**: JWT (Heimdall) → OAuth2 M2M (Auth0)\n- **Field Mapping**: `project_uid` (v2 UUID) → `project_id` (v1 Salesforce ID)\n- **Authorization**: Fine-grained access control via OpenFGA\n- **Path Translation**: Shorter proxy paths (`/surveys/{id}`) → ITX paths (`/v2/surveys/{id}/schedule`)\n\nThe service also processes real-time NATS events to sync v1 survey data to the v2 indexer and FGA. See [Event Processing Documentation](docs/event-processing.md) for details.\n\nFor a complete reference of all data types, tags, access control config, and parent references sent to the indexer, see [Indexer Contract](docs/indexer-contract.md).\n\nSee [ITX Proxy Implementation Architecture](docs/itx-proxy-implementation.md) for detailed information.\n\n## Features\n\n- **Survey Scheduling**: Schedule surveys to be sent to committee members\n- **JWT Authentication**: Secure authentication via Heimdall JWT tokens\n- **OAuth2 M2M**: Machine-to-machine authentication with ITX using Auth0\n- **ID Mapping**: Automatic v1/v2 ID translation via NATS\n- **Event Processing**: Real-time sync of v1 survey data to v2 indexer and FGA (see [Event Processing](docs/event-processing.md))\n- **OpenFGA Authorization**: Fine-grained access control\n- **OpenAPI Spec**: Auto-generated from Goa design\n- **Kubernetes Ready**: Includes Helm charts with health checks and probes\n\n## Architecture\n\n```\n┌──────────────┐     JWT      ┌──────────────────┐    OAuth2    ┌──────────┐\n│   LFX V2     │─────────────▶│  Survey Service  │─────────────▶│   ITX    │\n│   Clients    │              │  (This Service)  │              │  API     │\n└──────────────┘              └──────────────────┘              └──────────┘\n                                       │\n                                       │ NATS\n                                       ▼\n                                  ┌─────────┐\n                                  │   ID    │\n                                  │ Mapper  │\n                                  └─────────┘\n```\n\n## API Endpoints\n\nThe service provides 15 REST API endpoints for survey management:\n\n### Survey Management\n\n- `POST /surveys` - Create and schedule a new survey for a single committee\n- `GET /surveys/{survey_uid}` - Get survey details\n- `PUT /surveys/{survey_uid}` - Update survey (when status is 'disabled')\n- `DELETE /surveys/{survey_uid}` - Delete survey (when status is 'disabled')\n- `POST /surveys/{survey_uid}/bulk_resend` - Bulk resend survey emails to select recipients\n- `GET /surveys/{survey_uid}/preview_send` - Preview recipients affected by a resend\n- `POST /surveys/{survey_uid}/send_missing_recipients` - Send survey to committee members who haven't received it\n- `DELETE /surveys/{survey_uid}/recipient_group` - Remove a recipient group from survey\n\n### Survey Responses\n\n- `DELETE /surveys/{survey_uid}/responses/{response_id}` - Delete survey response\n- `POST /surveys/{survey_uid}/responses/{response_id}/resend` - Resend survey email to specific user\n\n### Exclusions Management\n\n- `POST /surveys/exclusion` - Create survey or global exclusion\n- `DELETE /surveys/exclusion` - Delete survey or global exclusion\n- `GET /surveys/exclusion/{exclusion_id}` - Get exclusion by ID\n- `DELETE /surveys/exclusion/{exclusion_id}` - Delete exclusion by ID\n\n### Utilities\n\n- `POST /surveys/validate_email` - Validate email template body and subject\n\n### API Documentation\n\n**Survey Service OpenAPI Spec**:\n\n- [Dev](https://lfx-api.dev.v2.cluster.linuxfound.info/_survey/openapi3.yaml)\n- [Production](https://lfx-api.v2.cluster.lfx.dev/_survey/openapi3.yaml)\n\nOr import `gen/http/openapi.yaml` into [Swagger Editor](https://editor.swagger.io/) when running locally.\n\n**ITX API Docs** (upstream):\n\n- [Dev](https://api.dev.itx.linuxfoundation.org/explore/?urls.primaryName=v2)\n- [Staging](https://api.stg.itx.linuxfoundation.org/explore/?urls.primaryName=v2)\n- [Production](https://api.prod.itx.linuxfoundation.org/explore/?urls.primaryName=v2)\n\nFor detailed API contracts showing request/response schemas and differences between the proxy API and ITX API:\n\n- [Survey Management API Contracts](docs/api-contracts/itx-surveys-api.md)\n- [Survey Responses API Contracts](docs/api-contracts/itx-survey-responses-api.md)\n- [Exclusions API Contracts](docs/api-contracts/itx-exclusions-api.md)\n- [ITX Proxy Implementation Architecture](docs/itx-proxy-implementation.md)\n\n## Prerequisites\n\n- Go 1.25.4 or later\n- Docker (for containerization)\n- Kubernetes cluster (for deployment)\n- Helm 3 (for deployment)\n- Access to ITX API\n- Auth0 M2M credentials with RSA private key\n- NATS server (for ID mapping)\n\n## Development Setup\n\n### Install Dependencies\n\n```bash\nmake deps\n```\n\nThis installs:\n\n- `goa` CLI for code generation\n- `golangci-lint` for linting\n\n### Generate Code\n\n```bash\nmake apigen\n```\n\nThis generates server/client code from the Goa design in `api/survey/v1/design/`.\n\n### Build\n\n```bash\nmake build\n```\n\nBinary is output to `bin/survey-api`.\n\n### Run\n\nCopy `.env.example` to `.env`, fill in the required values (see the `REQUIRED` comments, credentials from 1Password), then source it and run:\n\n```bash\ncp .env.example .env\n# edit .env and set ITX_CLIENT_ID and ITX_CLIENT_PRIVATE_KEY\nsource .env\n\nmake run\n# or for debug logging\nmake debug\n```\n\nThe service will start on port 8080 by default.\n\n### Testing\n\n```bash\nmake test\n```\n\n### Linting and Formatting\n\n```bash\nmake lint\nmake fmt\n```\n\n## Kubernetes Deployment\n\n### Install with Helm\n\n#### Create Kubernetes Secret\n\nBefore installing the chart, you must create a Kubernetes secret with the required credentials. Get the values from the **LFX Platform Chart Values Secrets - Local Development** note in the **LFX V2** vault in 1Password.\n\n```bash\nkubectl create secret generic lfx-v2-survey-service -n lfx \\\n  --from-literal=ITX_CLIENT_ID=\"\u003cfrom-1password\u003e\" \\\n  --from-file=ITX_CLIENT_PRIVATE_KEY=/path/to/private.key\n```\n\n#### Install from GHCR (no local code changes)\n\nTo install the latest published image directly from GHCR without any local modifications:\n\n```bash\nmake helm-install\n```\n\n#### Install with Local Code Changes\n\nCopy the local values example file:\n\n```bash\ncp charts/lfx-v2-survey-service/values.local.example.yaml charts/lfx-v2-survey-service/values.local.yaml\n```\n\nAfter making code changes, build the Docker image:\n\n```bash\nmake docker-build\n```\n\nInstall the chart using your local image:\n\n```bash\nmake helm-install-local\n```\n\n**Chart Versioning**: The chart version in `Chart.yaml` is set to `0.0.1` and should not be manually incremented. During the release process, the chart version is dynamically set to match the Git tag version (e.g., tag `v0.1.6` results in chart version `0.1.6`).\n\n### Configure Secrets\n\nThe service requires Auth0 credentials stored in AWS Secrets Manager:\n\n1. Create a secret in AWS Secrets Manager at path:\n   `/cloudops/managed-secrets/auth0/LFX_V2_Surveys_Service`\n\n2. Add the following keys:\n   - `client_id` - Auth0 client ID\n   - `client_private_key` - RSA private key in raw PEM format (not base64)\n\n3. The External Secrets Operator will sync these to Kubernetes automatically\n\n### Verify Deployment\n\n```bash\nkubectl get pods -n lfx -l app=lfx-v2-survey-service\nkubectl logs -n lfx -l app=lfx-v2-survey-service\n```\n\n## Project Structure\n\n```\n.\n├── api/                      # Goa design files\n│   └── survey/v1/design/     # API design (DSL)\n├── cmd/                      # Application entry points\n│   └── survey-api/           # Main service binary\n│       └── eventing/         # Event processing handlers\n├── gen/                      # Generated code (from Goa)\n├── internal/                 # Private application code\n│   ├── domain/               # Domain interfaces and types\n│   ├── infrastructure/       # Infrastructure implementations\n│   │   ├── auth/             # JWT authentication\n│   │   ├── eventing/         # Event processing infrastructure\n│   │   ├── idmapper/         # ID mapping (NATS)\n│   │   └── proxy/            # ITX proxy client\n│   ├── logging/              # Structured logging\n│   ├── middleware/           # HTTP middleware\n│   └── service/              # Business logic\n├── pkg/                      # Public packages\n│   ├── constants/            # Shared constants\n│   └── models/itx/           # ITX API models\n├── docs/                     # Documentation\n│   ├── api-contracts/        # API contract documentation\n│   ├── event-processing.md   # Event processing guide\n│   ├── indexer-contract.md   # Indexer data types \u0026 access control reference\n│   └── itx-proxy-implementation.md  # Architecture guide\n├── charts/                   # Helm charts\n│   └── lfx-v2-survey-service/\n├── Dockerfile                # Container image\n├── Makefile                  # Build automation\n└── go.mod                    # Go module definition\n```\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines on development setup, code style, how to add new endpoints, commit conventions, and the pull request process.\n\n## License\n\nCopyright The Linux Foundation and each contributor to LFX.\n\nLicensed under the MIT License. See [LICENSE](LICENSE) for details.\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flinuxfoundation%2Flfx-v2-survey-service","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flinuxfoundation%2Flfx-v2-survey-service","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flinuxfoundation%2Flfx-v2-survey-service/lists"}