The Architecture Has Three Different Kinds of Concurrency#

I found it useful to separate the problem into three concurrency domains.

1
stdin
2
network socket

Lesson 1 - A Network Client Has to Listen in Two Directions#

A blocking command-line client is easy to imagine:

1
read user input
2
send request
3
wait for reply
4
repeat

That model assumes every message from the server is a direct reply to the most recent request.

A multiplayer game breaks that assumption.

If another human player makes a move, the server can send a message even though the local user did not just type anything. A game can also end because the other player resigns or disconnects.

So the client really has two independent flows.

One path reads commands from stdin.

The other continuously reads messages from the TCP connection.

The client itself should remain relatively thin. It does not need to understand the whole board. It only needs enough local state to decide whether commands such as move, hint, or resign are currently meaningful.

For example:

1
game in progress?
2
my turn?
3
my colour?

The authoritative chess position belongs on the server side.

This gave me a useful distributed-systems rule:

A client should store only the state it needs to provide its interface. The authoritative state should live where decisions are validated.

Lesson 2 - Text Protocols Are Excellent for Debugging#

The client and server communicate over TCP using a line-oriented text protocol.

Typical messages can be thought of as:

1
start computer white
2
start human either
3
move e2e4
4
hint best
5
hint all
6
board
7
resign

and responses as:

1
started white
2
ok
3
moved e7e5
4
check
5
moves ...
6
gameover ...

For a student project, a text protocol has a major advantage: it is observable.

I can connect with a simple terminal tool and manually send commands.

That lets me test the server independently from my own client implementation.

This is an underrated design property.

When both sides of a protocol are being developed at the same time, a human-readable wire format makes it much easier to answer:

Is the problem in the client, the server, or the protocol?

Binary protocols may be more compact, but debuggability has real engineering value.

Lesson 3 - One Thread Per Client Is Simple Until State Becomes Shared#

The server accepts incoming TCP connections and creates one handler thread for each client.

That is conceptually straightforward:

1
accept connection
2
    ↓
3
spawn handler thread
4
    ↓
5
read command
6
process command
7
send response
8
repeat

The difficulty appears when threads stop being independent.

Two client threads may refer to the same human-vs-human game.

Many client threads may need the same Stockfish process.

Several threads may access the waiting-player list.

At that point, the important question is no longer:

How many threads do I have?

It becomes:

Which data can be touched by more than one thread?

Every shared object needs a clearly defined synchronization policy.

A large mutex around everything may be correct but unnecessarily restrictive.

No mutex at all may work in simple tests and fail unpredictably under simultaneous connections.

The architecture gets much easier to reason about when shared resources are listed explicitly:

1
connected-client registry
2
human-matchmaking pool
3
shared Game objects
4
Stockfish stdin/stdout transaction

Lesson 4 - A Single Chess Engine Becomes a Serialized Service#

One of the most interesting constraints was that the server uses one Stockfish process even while supporting multiple clients and games.

That means the engine cannot safely be treated as if every client thread owns its own private chess library.

Suppose two threads do this at the same time:

1
Thread A:
2
position <game A>
3
go ...
4

5
Thread B:
6
position <game B>
7
go ...

If those command sequences interleave, the response no longer has an unambiguous owner.

The engine interaction therefore has to be treated as a transaction:

1
lock engine
2
set game context
3
send UCI command
4
read complete response
5
unlock engine

The engine lock is not merely protecting a file descriptor.

It protects the semantic integrity of a request-response conversation.

That distinction matters.

Many concurrency bugs happen because programmers lock individual writes but forget that a protocol operation consists of several ordered writes and reads.

Lesson 5 - Pipes Turn a Program into a Service#

Stockfish runs as a child process.

The server creates two pipes:

1
server -> Stockfish stdin
2
Stockfish stdout -> server

then forks, redirects file descriptors in the child, and launches the engine.

The startup sequence also has a small protocol of its own.

Conceptually:

1
start process
2
    ↓
3
isready
4
    ↓
5
readyok
6
    ↓
7
uci
8
    ↓
9
uciok

This was one of the parts of the project I liked most because it connects several Unix concepts that can otherwise feel unrelated:

1
pipe()
2
fork()
3
dup / descriptor redirection
4
exec()
5
FILE* or descriptor I/O
6
process lifecycle

The result is effectively a local service boundary.

Stockfish could have been a library, but using a process gives useful isolation:

• the engine has its own address space;
• it can be replaced independently;
• communication is constrained to a documented protocol;
• engine termination can be detected through the pipe.

Lesson 6 - FEN Is a Better Game-State Boundary Than a Thread#

A common mistake in threaded applications is to associate state too strongly with the thread currently executing.

A thread is only an execution context.

The chess game itself has a longer lifetime.

A useful game object needs to know things such as:

1
in progress or finished
2
white player
3
black player
4
current / final board state
5
whose turn is next

The board state can be represented using FEN (Forsyth-Edwards Notation).

This creates a useful separation:

1
Client
2
    = communication endpoint
3

4
Thread
5
    = code currently handling the endpoint
6

7
Game
8
    = shared application state
9

10
FEN
11
    = serializable chess position

For a human-vs-human game, two client threads can point at the same Game.

Neither thread is the game.

That lesson generalizes well beyond chess.

In concurrent servers, long-lived domain state should usually be represented explicitly rather than hidden inside thread-local control flow.

Lesson 7 - The Engine Can Be Reconstructed from State#

Because the server stores the board as FEN, the single Stockfish instance can be switched between games.

Before asking the engine a question, the server can reconstruct the relevant position:

1
position fen <current FEN>

and then issue a query.

This is what makes sharing one engine practical.

The engine is not trusted as the only copy of the application state.

Instead:

1
server game state
2
      ↓
3
reconstruct Stockfish context
4
      ↓
5
ask question
6
      ↓
7
parse response
8
      ↓
9
update server game state

That architecture is much safer than allowing the child process to become an undocumented global state store.

It also resembles how stateless backend services are designed: send enough context with each transaction that the service can answer correctly.

Lesson 8 - Move Validation Is a Pipeline, Not a Boolean Function#

A move such as:

1
e2e4

looks like it should produce:

1
valid / invalid

But the full server operation is richer.

A useful conceptual sequence is:

1
1. load the current FEN
2
2. apply the proposed move in the engine context
3
3. inspect the resulting board
4
4. determine whether the state changed
5
5. count legal replies
6
6. determine check / checkmate / stalemate
7
7. if playing the computer, request its best response
8
8. update FEN
9
9. notify the relevant client or clients

The UCI interface gives several tools for different parts of that process.

1
check
2
checkmate
3
stalemate

Lesson 9 - Matchmaking Is a Shared-State Problem#

Computer games are comparatively easy because one client owns one game.

Human matchmaking introduces a waiting pool.

A player can request:

1
white
2
black
3
either

The server has to find a compatible waiting client and create one shared game.

This means matchmaking requires a data structure that exists outside any single client thread.

Conceptually:

1
Client A asks for white
2
    ↓
3
search waiting pool
4
    ↓
5
compatible black/either player?
6
    ↓
7
yes -> create game and notify both
8
no  -> record Client A as waiting

The subtle part is that another client thread may modify the same pool at the same time.

So matchmaking is simultaneously:

1
application logic
2
+
3
concurrency control

I found this to be a good example of why race conditions are often really domain-state races, not just low-level memory races.

Lesson 10 - Disconnects Are Part of the Game Protocol#

A socket closing is a transport event.

In a multiplayer game, it also has application meaning.

If one human player disconnects during a game, the other player needs to be told that the game is over.

So cleanup is not simply:

1
close(fd);
2
return;

The server may need to:

1
mark the game finished
2
notify the opponent
3
remove the client from matchmaking
4
release client resources
5
close the socket
6
terminate only that handler thread

This is another systems lesson that I found useful:

Resource cleanup and application-state cleanup are not always the same thing.

Closing the file descriptor handles the operating-system resource.

It does not automatically repair the application state that referenced that connection.

Lesson 11 - SIGPIPE Is a Networking Design Issue, Not an Edge Case#

Writing to a closed pipe or socket can generate SIGPIPE.

If the default action is allowed to terminate the process, one disconnected client could accidentally kill the whole server.

Similarly, failure of the Stockfish pipe means something very different from failure of one client connection.

The failure policy should reflect the ownership boundary:

1
client socket failure
2
    -> terminate one client session
3
    -> server continues
4

5
Stockfish process failure
6
    -> shared engine unavailable
7
    -> all games lose engine service
8
    -> notify clients and terminate server

This is a clean example of failure domains.

The scope of recovery should match the scope of the failed resource.

Lesson 12 - Blocking Is Good When There Is Nothing to Do#

Concurrent programs sometimes become complicated because developers try too hard to make everything continuously active.

A server thread waiting for work should often simply block.

Examples include:

1
accept()
2
read()
3
fgets()
4
getline()

A blocked thread consumes almost no CPU while waiting for an event.

The bad alternative is:

1
check socket
2
nothing there
3
check again
4
check again
5
sleep a little
6
check again

Busy waiting adds latency, wastes CPU, and makes the server harder to reason about.

This project reinforced an important Unix programming habit:

If progress depends on external input, block on the object that will deliver that input.

A Data Model I Would Use#

If I were structuring the project again, I would make the major domain objects explicit.

1
socket / FILE streams
2
selected game mode
3
requested colour
4
current Game pointer
5
connection state

1
white client or computer
2
black client or computer
3
FEN
4
in-progress flag
5
finished state

1
listener
2
client collection
3
waiting-player collection
4
engine connection
5
engine mutex
6
shared-state mutexes

1
child PID
2
write stream
3
read stream
4
transaction lock

The Architecture I Would Prefer Today#

I would still keep the overall thread-per-client model because it matches the scale of the problem well.

But I would make a few design rules explicit.

1
is this move valid?
2
what is the resulting FEN?
3
what are the legal moves?
4
what is the best move?
5
is the side in check?

What I Would Improve in a Second Version#

1
client threads
2
    ↓
3
engine-request queue
4
    ↓
5
single engine worker
6
    ↓
7
Stockfish

1
START_GAME
2
BOARD_REQUEST
3
HINT_BEST
4
HINT_ALL
5
MOVE
6
RESIGN

1
game_start()
2
game_apply_move()
3
game_resign()
4
game_disconnect()
5
game_finish()

1
connected clients
2
waiting players
3
active games
4
engine request latency
5
commands per client
6
lock wait time

1
malformed commands
2
rapid reconnects
3
two clients moving at nearly the same time
4
disconnect during a game
5
engine failure
6
human colour matching

Final Thoughts#

This project looked like a chess application, but most of the difficult reasoning had nothing to do with chess strategy.

The real questions were:

• Who owns the board state?
• How do several client threads share one engine?
• How should two human clients be paired?
• What must be protected by synchronization?
• Which failures affect one session and which affect the whole service?
• How do I preserve state when the executing thread changes?
• Where should protocol parsing stop and domain logic begin?

Those questions appear in many real systems.

A database server, build service, multiplayer game, hardware-control daemon, or model-serving backend can all have the same underlying shape:

1
many clients
2
    ↓
3
concurrent request handling
4
    ↓
5
shared domain state
6
    ↓
7
serialized access to a limited resource

The most useful lesson I kept from the project is:

Concurrency becomes manageable when state ownership is explicit and communication boundaries are designed before the threads are added.

The threads themselves are not the architecture.

The architecture is the set of rules that determines how those threads are allowed to interact.