ITX Meeting Proxy Service

The ITX Meeting Proxy Service is a lightweight stateless proxy that forwards meeting-related requests to the ITX Zoom API service. It provides a thin authentication and authorization layer for the Linux Foundation's LFX platform.

🚀 Quick Start

For Deployment (Helm)

# Install the proxy service
helm upgrade --install lfx-v2-meeting-service ./charts/lfx-v2-meeting-service \
  --namespace lfx \
  --create-namespace \
  --set image.tag=latest \
  --set app.environment.ITX_BASE_URL.value="https://api.itx.linuxfoundation.org" \
  --set app.environment.ITX_CLIENT_ID.value="your-client-id" \
  --set-file app.environment.ITX_CLIENT_PRIVATE_KEY.value=path/to/private.key

For Local Development

Prerequisites
- Go 1.24+ installed
- Make installed

Clone and Setup

git clone https://github.com/linuxfoundation/lfx-v2-meeting-service.git
cd lfx-v2-meeting-service

# Install dependencies
make deps

Configure Environment

# Copy the example environment file and configure it
cp .env.example .env
# Edit .env with ITX credentials

Required environment variables:

ITX_ENABLED=true
ITX_BASE_URL=https://api.dev.itx.linuxfoundation.org
ITX_CLIENT_ID=your-client-id
ITX_CLIENT_PRIVATE_KEY="$(cat path/to/private.key)"
ITX_AUTH0_DOMAIN=linuxfoundation-dev.auth0.com
ITX_AUDIENCE=https://api.dev.itx.linuxfoundation.org/

Run the Service

# Run with default settings
make run

# Or run with debug logging
make debug

🏗️ Architecture

The service is a stateless HTTP proxy built using a clean architecture pattern:

API Layer: Goa-generated HTTP handlers and OpenAPI specifications
Service Layer: Request validation and ITX client orchestration
Domain Layer: Core request/response models
Infrastructure Layer: ITX HTTP client with OAuth2 authentication

Key Features

Stateless Proxy: No data persistence, all state managed by ITX service
ITX Meeting Operations: Create, read, update, delete meetings via ITX
ITX Registrant Operations: Manage meeting registrants via ITX
ITX Past Meeting Operations: Full CRUD operations for past meeting records via ITX
ITX Past Meeting Summary Operations: Retrieve and update AI-generated meeting summaries
ITX Meeting Attachment Operations: Full CRUD operations for meeting attachments with presigned URL support
ITX Past Meeting Attachment Operations: Full CRUD operations for past meeting attachments with presigned URL support
JWT Authentication: Secure API access via Heimdall integration
ID Mapping: Optional v1/v2 ID translation via NATS (can be disabled)
OpenAPI Documentation: Auto-generated API specifications

📁 Project Structure

lfx-v2-meeting-service/
├── cmd/                           # Application entry points
│   └── meeting-api/               # Main API server
├── charts/                        # Helm chart for Kubernetes deployment
│   └── lfx-v2-meeting-service/
├── design/                        # Goa API design files
│   ├── meeting-svc.go             # Service definition
│   └── itx_types.go               # ITX type definitions
├── gen/                           # Generated code (DO NOT EDIT)
│   ├── http/                      # HTTP transport layer
│   └── meeting_service/           # Service interfaces
├── internal/                      # Private application code
│   ├── domain/                    # Business domain layer
│   │   ├── models/                # Domain models
│   │   ├── errors.go              # Domain-specific errors
│   │   ├── itx_proxy.go           # ITX proxy interface
│   │   └── id_mapper.go           # ID mapper interface
│   ├── infrastructure/            # Infrastructure layer
│   │   ├── auth/                  # JWT authentication
│   │   ├── proxy/                 # ITX HTTP client
│   │   └── idmapper/              # NATS-based ID mapping
│   ├── middleware/                # HTTP middleware
│   └── service/                   # Service layer implementation
│       ├── auth_service.go        # Auth service
│       └── itx/                   # ITX services
├── pkg/                           # Public packages
│   ├── models/itx/                # ITX request/response models
│   └── utils/                     # Utility functions
├── Dockerfile                     # Container build configuration
├── Makefile                       # Build and development commands
└── go.mod                         # Go module definition

🛠️ Development

Prerequisites

Go 1.24+
Make
Git

Getting Started

Install Dependencies
```
make deps
```
Generate API Code
```
make apigen
```
Generates HTTP transport, client, and OpenAPI documentation from design files.
Build the Application
```
make build
```
Creates the binary in bin/meeting-api.

Development Workflow

Running the Service

# Run with default settings
make run

# Run with debug logging
make debug

# Build and run binary
make build
./bin/meeting-api

Code Quality

Always run these before committing:

# Format code
make fmt

# Run linter
make lint

# Run all tests
make test

# Check everything (format + lint + tests)
make check

API Development

When modifying the API:

Update Design Files in design/ directory
Regenerate Code:
```
make apigen
```
Verify Generation:
```
make verify
```
Run Tests to ensure nothing breaks:
```
make test
```

Available Make Targets

Target	Description
`make all`	Complete build pipeline (clean, deps, apigen, fmt, lint, test, build)
`make deps`	Install dependencies and tools
`make apigen`	Generate API code from design files
`make build`	Build the binary
`make run`	Run the service locally
`make debug`	Run with debug logging
`make test`	Run unit tests
`make test-verbose`	Run tests with verbose output
`make test-coverage`	Generate HTML coverage report
`make lint`	Run code linter
`make fmt`	Format code
`make check`	Verify formatting and run linter
`make verify`	Ensure generated code is up to date
`make clean`	Remove build artifacts
`make docker-build`	Build Docker image
`make helm-install`	Install Helm chart
`make helm-uninstall`	Uninstall Helm chart

🧪 Testing

Running Tests

# Run all tests
make test

# Run with verbose output
make test-verbose

# Generate coverage report
make test-coverage

🚀 Deployment

Helm Chart

The service includes a Helm chart for Kubernetes deployment.

Prerequisites: Kubernetes Secret

Before installing the chart, create the meeting-secrets secret in the lfx namespace. The auth0_client_id and auth0_client_private_key values are in 1Password under the LFX V2 vault, in the note LFX Platform Chart Values Secrets - Local Development.

kubectl create secret generic meeting-secrets -n lfx \
  --from-literal=auth0_client_id="<client-id-from-1password>" \
  --from-file=auth0_client_private_key=./path/to/private.key

Option 1: Install from GHCR (no local code changes)

Use this if you just want to run the service without modifying its code. The image is pulled directly from the container registry:

make helm-install

# Or using Helm directly
helm upgrade --install lfx-v2-meeting-service ./charts/lfx-v2-meeting-service \
  --namespace lfx \
  --create-namespace

Option 2: Install from a Local Build (active development)

Use this if you are making changes to the service code. First, copy the example local values file (it is gitignored):

cp charts/lfx-v2-meeting-service/values.local.example.yaml \
   charts/lfx-v2-meeting-service/values.local.yaml

Then, whenever you make a code change and want to apply it:

# Rebuild the local image
make docker-build

# Install/upgrade the chart using the local image
make helm-install-local

# Or using Helm directly
helm upgrade --install lfx-v2-meeting-service ./charts/lfx-v2-meeting-service \
  --namespace lfx \
  --create-namespace \
  --values ./charts/lfx-v2-meeting-service/values.local.yaml

Docker

# Build Docker image
make docker-build

# Run with Docker
docker run -p 8080:8080 \
  -e ITX_ENABLED=true \
  -e ITX_BASE_URL=https://api.itx.linuxfoundation.org \
  -e ITX_CLIENT_ID=your-client-id \
  -e ITX_CLIENT_PRIVATE_KEY="$(cat path/to/private.key)" \
  linuxfoundation/lfx-v2-meeting-service:latest

📖 API Documentation

The service automatically generates OpenAPI documentation:

OpenAPI 2.0: gen/http/openapi.yaml
OpenAPI 3.0: gen/http/openapi3.yaml
JSON formats: Also available in gen/http/

Access the documentation at: http://localhost:8080/openapi.json

Available Endpoints

Health Checks

Endpoint	Method	Description
`/livez`	GET	Liveness check
`/readyz`	GET	Readiness check

ITX Meeting Operations

Endpoint	Method	Description
`/itx/meetings`	POST	Create meeting via ITX
`/itx/meetings/{meeting_id}`	GET	Get meeting details
`/itx/meetings/{meeting_id}`	PUT	Update meeting
`/itx/meetings/{meeting_id}`	DELETE	Delete meeting
`/itx/meetings/{meeting_id}/join_link`	GET	Get join link for user
`/itx/meetings/{meeting_id}/responses`	POST	Submit meeting RSVP (accepted/declined/maybe)
`/itx/meetings/{meeting_id}/occurrences/{occurrence_id}`	PATCH	Update occurrence
`/itx/meetings/{meeting_id}/occurrences/{occurrence_id}`	DELETE	Delete occurrence
`/itx/meeting_count`	GET	Get meeting count

ITX Registrant Operations

Endpoint	Method	Description
`/itx/meetings/{meeting_id}/registrants`	POST	Add registrant
`/itx/meetings/{meeting_id}/registrants`	GET	List registrants
`/itx/meetings/{meeting_id}/registrants/{registrant_uid}`	GET	Get registrant
`/itx/meetings/{meeting_id}/registrants/{registrant_uid}`	PATCH	Update registrant
`/itx/meetings/{meeting_id}/registrants/{registrant_uid}`	PUT	Update registrant status
`/itx/meetings/{meeting_id}/registrants/{registrant_uid}`	DELETE	Delete registrant

ITX Past Meeting Operations

Endpoint	Method	Description
`/itx/past_meetings`	POST	Create past meeting
`/itx/past_meetings/{past_meeting_id}`	GET	Get past meeting
`/itx/past_meetings/{past_meeting_id}`	PUT	Update past meeting
`/itx/past_meetings/{past_meeting_id}`	DELETE	Delete past meeting

ITX Meeting Attachment Operations

Endpoint	Method	Description
`/itx/meetings/{meeting_id}/attachments`	POST	Create meeting attachment
`/itx/meetings/{meeting_id}/attachments/{attachment_id}`	GET	Get attachment metadata
`/itx/meetings/{meeting_id}/attachments/{attachment_id}`	PUT	Update attachment
`/itx/meetings/{meeting_id}/attachments/{attachment_id}`	DELETE	Delete attachment
`/itx/meetings/{meeting_id}/attachments/presign`	POST	Generate presigned upload URL
`/itx/meetings/{meeting_id}/attachments/{attachment_id}/download`	GET	Get download URL

ITX Past Meeting Attachment Operations

Endpoint	Method	Description
`/itx/past_meetings/{meeting_and_occurrence_id}/attachments`	POST	Create past meeting attachment
`/itx/past_meetings/{meeting_and_occurrence_id}/attachments/{attachment_id}`	GET	Get attachment metadata
`/itx/past_meetings/{meeting_and_occurrence_id}/attachments/{attachment_id}`	PUT	Update attachment
`/itx/past_meetings/{meeting_and_occurrence_id}/attachments/{attachment_id}`	DELETE	Delete attachment
`/itx/past_meetings/{meeting_and_occurrence_id}/attachments/presign`	POST	Generate presigned upload URL
`/itx/past_meetings/{meeting_and_occurrence_id}/attachments/{attachment_id}/download`	GET	Get download URL

🔧 Configuration

The service can be configured via environment variables:

Required Configuration

Variable	Description	Example
`ITX_BASE_URL`	Base URL for ITX service	`https://api.itx.linuxfoundation.org`
`ITX_CLIENT_ID`	OAuth2 client ID for ITX	`your-client-id`
`ITX_CLIENT_PRIVATE_KEY`	RSA private key in PEM format for ITX OAuth2 M2M authentication	`"$(cat path/to/private.key)"`
`ITX_AUTH0_DOMAIN`	Auth0 domain for ITX OAuth2	`linuxfoundation.auth0.com`
`ITX_AUDIENCE`	OAuth2 audience for ITX	`https://api.itx.linuxfoundation.org/`

Authentication Configuration

Variable	Description	Default
`JWKS_URL`	JWKS URL for JWT verification	`http://lfx-platform-heimdall.lfx.svc.cluster.local:4457/.well-known/jwks`
`JWT_AUDIENCE`	JWT token audience	`lfx-v2-meeting-service`
`JWT_AUTH_DISABLED_MOCK_LOCAL_PRINCIPAL`	Mock principal for local dev	`""`

Optional Configuration

Variable	Description	Default
`LOG_LEVEL`	Log level (debug, info, warn, error)	`info`
`LOG_ADD_SOURCE`	Add source location to logs	`true`
`LFX_ENVIRONMENT`	LFX environment (dev, staging, prod)	`prod`
`ID_MAPPING_DISABLED`	Disable v1/v2 ID mapping	`false`
`NATS_URL`	NATS server URL (for ID mapping)	`nats://lfx-platform-nats.lfx.svc.cluster.local:4222`

ID Mapping

The service supports optional ID mapping between v1 and v2 systems via NATS:

Enabled (default): Set ID_MAPPING_DISABLED=false and provide NATS_URL
Disabled: Set ID_MAPPING_DISABLED=true to pass IDs through unchanged

Tracing Configuration

The service supports distributed tracing via OpenTelemetry:

Variable	Description	Default
`OTEL_SERVICE_NAME`	Service name for traces	`lfx-v2-meeting-service`
`OTEL_EXPORTER_OTLP_ENDPOINT`	OTLP collector endpoint	`""`
`OTEL_TRACES_EXPORTER`	Traces exporter (otlp/none)	`none`
`OTEL_TRACES_SAMPLE_RATIO`	Sampling ratio (0.0-1.0)	`1.0`

🤝 Contributing

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Make changes and ensure tests pass (make test)
Run quality checks (make check)
Commit changes (git commit -m 'Add amazing feature')
Push to branch (git push origin feature/amazing-feature)
Create a Pull Request

Code Standards

Follow Go conventions and best practices
Maintain test coverage
Write clear, self-documenting code
Update documentation for API changes
Run make check before committing

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

Name		Name	Last commit message	Last commit date
Latest commit History 586 Commits
.github/workflows		.github/workflows
charts/lfx-v2-meeting-service		charts/lfx-v2-meeting-service
cmd/meeting-api		cmd/meeting-api
design		design
docs		docs
gen		gen
internal		internal
pkg		pkg
.env.example		.env.example
.gitignore		.gitignore
.gitleaks.toml		.gitleaks.toml
.ko.yaml		.ko.yaml
.mega-linter.yml		.mega-linter.yml
.yamllint		.yamllint
CLAUDE.md		CLAUDE.md
CODEOWNERS		CODEOWNERS
Dockerfile		Dockerfile
LICENSE		LICENSE
LICENSE-docs		LICENSE-docs
Makefile		Makefile
README.md		README.md
SECURITY.md		SECURITY.md
go.mod		go.mod
go.sum		go.sum
revive.toml		revive.toml

Folders and files

Latest commit

History

Repository files navigation

ITX Meeting Proxy Service

🚀 Quick Start

For Deployment (Helm)

For Local Development

🏗️ Architecture

Key Features

📁 Project Structure

🛠️ Development

Prerequisites

Getting Started

Development Workflow

Running the Service

Code Quality

API Development

Available Make Targets

🧪 Testing

Running Tests

🚀 Deployment

Helm Chart

Prerequisites: Kubernetes Secret

Option 1: Install from GHCR (no local code changes)

Option 2: Install from a Local Build (active development)

Docker

📖 API Documentation

Available Endpoints

Health Checks

ITX Meeting Operations

ITX Registrant Operations

ITX Past Meeting Operations

ITX Meeting Attachment Operations

ITX Past Meeting Attachment Operations

🔧 Configuration

Required Configuration

Authentication Configuration

Optional Configuration

ID Mapping

Tracing Configuration

🤝 Contributing

Code Standards

📄 License

About

Resources

License

Licenses found

Security policy

Uh oh!

Stars

Watchers

Forks

Releases 63

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages