Guedes Sueca

Overview

Guedes Sueca was born out of a single fascination: WebSockets. While learning about them I became convinced they were the missing piece in everything I had built before, as constant page refreshing had always been my biggest frustration when developing web applications. I knew I had to get my hands dirty with real-time communication, and I wanted to understand it from the ground up.

Coming in with some background in traditional Sockets from Java, I made a deliberate choice: learn raw WebSockets rather than reach for the popular Socket.io. It was the harder road. Socket.io ships with countless quality-of-life features like rooms, reconnection, and acknowledgements, that simply do not exist in the native protocol, and doing without them forced me to genuinely understand what was happening on the wire.

To give the learning a real purpose I decided to rebuild Sueca, the popular Portuguese card game, entirely from scratch. Its rules are well established and unambiguous, which made it the perfect vehicle: a clear specification to implement, and a genuine reason to finish it, so I could actually play online with my friends, specially in those places where they don’t let us play cards.

The Game & Real-Time Model

The design intentionally started small and opinionated, prioritizing a working game over a bulletproof one:

• Four-Player Sessions: Each game is capped at four players, matching the rules of Sueca. New connections only join the active pool if a seat is free and their nickname isn’t already taken.
• Nickname-Based Identity: Players are identified purely by their chosen nickname. There are no accounts, no logins, and no persisted sessions for anyone who disconnects, a conscious shortcut that kept the scope tight (and, admittedly, caused me headaches later on).
• Server-Authoritative State: All the game logic and rules of Sueca live on the server. Clients simply render whatever state the server hands them.
• Broadcast on Every Action: Whenever a player interacts with the server, whether joining the game or making a move, the server recomputes the game state and pushes it out to every connected client. This meant every player always saw exactly the same, up-to-date board.

Architecture & Technical Choices

The whole system revolves around a single source of truth living on the Node.js server, with lightweight React clients acting purely as views:

• Raw WebSocket Server: Built without Socket.io, the server manages connections, the player pool, and the full ruleset of Sueca by hand parsing messages, validating moves, and enforcing turn order.
• State Synchronization: Rather than sending granular per-event deltas, the server broadcasts the complete game state after every change. It was a simple model to reason about and eliminated an entire category of “out of sync” bugs between clients.
• React & Ant Design Client: The interface was built with React and Ant Design, giving me polished, ready-made components so I could focus my energy on the networking and game logic rather than styling from zero.

Engineering Trade-offs & Challenges

Being my first ever WebSocket server, the learning curve was steep, and a few problems stood out well above the rest:

• Learning the Protocol: Understanding the WebSocket handshake, message framing, and connection lifecycle from first principles, without Socket.io’s abstractions, was the foundational challenge the whole project was built to tackle.
• Implementing Sueca Server-Side: Encoding the complete rules of Sueca (trump suit, following suit, trick-winning, and scoring) into authoritative server logic took real care to get right.
• “Seating” the Players: This was, by far, the worst part. The server holds one canonical view of the table, but each client needs to see themselves in a consistent seat with their teammates and opponents positioned relative to them. Rotating that shared state into four different local perspectives was maddening to get right.
• The Deployment Nightmare: The most popular hosting services are notoriously particular about the WebSocket protocol, and getting a persistent connection to survive in production turned deployment into a genuine ordeal.

Retrospective

Guedes Sueca remains one of my favorite projects to look back on. It’s a 10/10 for me, not because the code is perfect, but because it delivered exactly what I set out to learn and gave me something genuinely fun to play with friends at the end of it.

Working with raw WebSockets can be punishing, and the strictness of hosting providers made the final stretch rougher than it needed to be. But choosing the harder path paid off: I walked away with a real, mechanical understanding of how real-time communication works under the hood, and that mental model has informed everything I’ve built since. Not bad for a week’s work.