App WebSockets

08/23/2025

Problem Statement

We need to implement WebSocket support in our application to enable real-time communication between the client and server. The current polling mechanism is inefficient and clunky.

The APIs that already have access to the Cognito context, but the BetService will also need to be able to leverage the live bets and a way to persist connections for the active user sessions.

Proposed Solution

We use aws cognito for authentication so I plan can adapt that example to the official AWS Example The proposed solution introduces an additional Lambda Functions (WebSocketAPI), Bet API, RDS Proxy, PostgresSQL, Notifications and BetTracker (EC2 instance) and rest integrated to the original architecture.

Architectural & Technical Details

Edit this diagram is a Lucid chart

  • WebSocket API
    • In the WebSocket-enabled version, I’ve introduced a dedicated WebSocket API so clients (Web, Mobile, Dev Panel) can maintain persistent connections.
  • Connection Lifecycle Management
    • On connect, I authenticate the user (via Cognito) and insert their connectionId and metadata into the database (through RDS Proxy).
    • On disconnect, I remove the connectionId so we don’t target inactive users.
  • Bet API
    • New route handler for events like fight_created, fight_accepted, and fight_completed.
    • This Lambda queries active connections from the database and sends messages back to clients via API Gateway’s postToConnection.
  • Database Changes
    • While the original database design only handled bets and user/session data, I now also persist WebSocket connectionId mappings.
  • With WebSockets, the fightEvent Lambda also pushes messages to Notifications (via SNS), allowing real-time to connected clients.

Next Steps

After the design is finalized there should be some in-depth analysis on CDK so we can align on infrastructure as code.

Action Items

  • I’ve already pushed a PR that shows the WebSocket architecture changes.

  • Following are actionable items:

    • Create WebSocket API in API Gateway.

    • New WebSocket API in API Gateway.

    • Lambda handlers for $connect, $disconnect, and fightEvent.

    • RDS schema update for storing connectionId.

    • Write integration tests for connection lifecycle and event broadcasting.

Open Questions

  • How is this going to work with our microservices? Because It makes sense to me to have most of this exist in the UserService/CognitoManager (I think that this CognitoManager should have been put in the UserService anyways so we’re kind of reaching a 3rd degree of separation that is starting to hurt my brain)

Approvals

You need architectural approval from Trace Carrasco & product approval from Filip Pacyna / Troy Lenihan

  • Trace Carrasco
  • Filip Pacyna/Troy Lenihan