# jfpmonteiro/sok architecture

> Architecture diagram of the GitHub repository jfpmonteiro/sok, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jfpmonteiro/sok
- Repository: https://github.com/jfpmonteiro/sok

## Overview

1. **What this repository is**
   - `sok` is a small C codebase centered on a core socket-related library or abstraction in `sok.c` / `sok.h`.
   - The rest of the tree is mostly test and example programs that exercise that core code in different network scenarios.

2. **Core package boundary**
   - `sok.h` is the public interface boundary for the library.
   - `sok.c` is the implementation boundary behind that interface.
   - Any diagram should treat these two files as the central reusable component, with the test programs depending on them rather than each other.

3. **Build and project orchestration**
   - The top-level `Makefile` is the primary build entry point.
   - Each test subdirectory also has its own `Makefile`, so the repo is organized as a main library plus independently buildable test targets.
   - `doc.conf` indicates there is a documentation/configuration layer separate from the build/runtime path.

4. **Test suite structure**
   - `tests/` contains three scenario-specific areas: `simple`, `http`, and `rfi`.
   - These look like executable-level integration tests or demos rather than unit tests.
   - The architecture should show them as clients/servers that validate the library under different protocol or transport conditions.

5. **Simple test scenario**
   - `tests/simple` contains both `client.c` and `server.c`, plus a `certificate.crt` and `privateKey.key`.
   - This strongly suggests a secure client/server handshake or encrypted transport example.
   - The certificate and key are runtime inputs to the server side, so this folder represents a self-contained TLS-style test environment.

6. **HTTP test scenario**
   - `tests/http` contains `server.c` and its own `Makefile`.
   - This looks like a protocol-specific server example layered on top of the core `sok` functionality.
   - In an architecture diagram, this is best shown as a higher-level application built on the socket layer, likely intended to demonstrate HTTP handling over that transport.

7. **RFI test scenario**
   - `tests/rfi` contains `client.c`, `server.c`, and `rfi.h`.
   - The presence of its own header suggests this test has an internal protocol or shared test-specific contract separate from the main library header.
   - Treat this as another integration harness with a dedicated client/server pair and a small local API.

8. **Data flow pattern**
   - The dominant runtime pattern is bidirectional network communication between a client process and a server process.
   - The core library sits underneath these processes, providing the socket behavior they share.
   - In the `simple` case, the server additionally depends on certificate material for secure setup.

9. **Dependency layout**
   - Tests depend on the core library; the core library does not depend on test code.
   - `tests/rfi/rfi.h` is local to that test subtree and should be shown as an internal helper boundary, not part of the public library API.
   - The certificate and private key are deployment artifacts for the test environment, not code dependencies.

10. **Likely repository intent**
   - This repo appears to be a compact networking library with example programs demonstrating usage across multiple scenarios.
   - The examples are organized by protocol or concern rather than by layer, which is useful for an architecture diagram showing “core library” versus “scenario-specific executables.”

11. **What to emphasize in a diagram**
   - Central reusable library: `sok.c` + `sok.h`
   - Separate executable/test nodes: `tests/simple`, `tests/http`, `tests/rfi`
   - Client/server communication paths
   - Security assets in `tests/simple` as runtime server inputs
   - Build boundaries via the top-level and per-test `Makefile`s

Main entry points: [`sok.h`](https://github.com/jfpmonteiro/sok/blob/master/sok.h) (sok.h), [`Makefile`](https://github.com/jfpmonteiro/sok/tree/master/Makefile) (Makefile), [`tests/simple/server.c`](https://github.com/jfpmonteiro/sok/blob/master/tests/simple/server.c) (Server), [`tests/simple/Makefile`](https://github.com/jfpmonteiro/sok/tree/master/tests/simple/Makefile) (Makefile)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_build["Build & docs"]
  node_makefile_root["Makefile<br/>build entry"]
  node_doc_conf["doc.conf<br/>docs config<br/>[doc.conf]"]
end

subgraph group_core["Core library"]
  node_sok_h["sok.h<br/>public API<br/>[sok.h]"]
  node_sok_c["sok.c<br/>library impl<br/>[sok.c]"]
end

subgraph group_simple["Simple test"]
  node_simple_makefile["Makefile<br/>test build"]
  node_simple_client(("Client<br/>[client.c]"))
  node_simple_server(("Server<br/>[server.c]"))
  node_simple_cert["Cert<br/>runtime asset<br/>[certificate.crt]"]
  node_simple_key["Key<br/>runtime asset<br/>[privateKey.key]"]
end

subgraph group_http["HTTP test"]
  node_http_makefile["Makefile<br/>test build"]
  node_http_server(("HTTP Server<br/>protocol server<br/>[server.c]"))
end

subgraph group_rfi["RFI test"]
  node_rfi_client(("Client<br/>[client.c]"))
  node_rfi_server(("Server<br/>[server.c]"))
  node_rfi_h["rfi.h<br/>local contract<br/>[rfi.h]"]
end

node_makefile_root -->|"builds"| node_sok_c
node_makefile_root -->|"installs"| node_sok_h
node_makefile_root -.->|"delegates"| node_simple_makefile
node_makefile_root -.->|"delegates"| node_http_makefile
node_simple_makefile -->|"builds"| node_simple_client
node_simple_makefile -->|"builds"| node_simple_server
node_simple_client -->|"uses"| node_sok_h
node_simple_server -->|"uses"| node_sok_h
node_simple_server -->|"loads"| node_simple_cert
node_simple_server -->|"loads"| node_simple_key
node_http_makefile -->|"builds"| node_http_server
node_http_server -->|"uses"| node_sok_h
node_rfi_client -->|"uses"| node_sok_h
node_rfi_server -->|"uses"| node_sok_h
node_rfi_client -->|"shares"| node_rfi_h
node_rfi_server -->|"shares"| node_rfi_h
node_sok_c -->|"implements"| node_sok_h

click node_makefile_root "https://github.com/jfpmonteiro/sok/tree/master/Makefile"
click node_doc_conf "https://github.com/jfpmonteiro/sok/blob/master/doc.conf"
click node_sok_h "https://github.com/jfpmonteiro/sok/blob/master/sok.h"
click node_sok_c "https://github.com/jfpmonteiro/sok/blob/master/sok.c"
click node_simple_makefile "https://github.com/jfpmonteiro/sok/tree/master/tests/simple/Makefile"
click node_simple_client "https://github.com/jfpmonteiro/sok/blob/master/tests/simple/client.c"
click node_simple_server "https://github.com/jfpmonteiro/sok/blob/master/tests/simple/server.c"
click node_simple_cert "https://github.com/jfpmonteiro/sok/blob/master/tests/simple/certificate.crt"
click node_simple_key "https://github.com/jfpmonteiro/sok/blob/master/tests/simple/privateKey.key"
click node_http_makefile "https://github.com/jfpmonteiro/sok/tree/master/tests/http/Makefile"
click node_http_server "https://github.com/jfpmonteiro/sok/blob/master/tests/http/server.c"
click node_rfi_client "https://github.com/jfpmonteiro/sok/blob/master/tests/rfi/client.c"
click node_rfi_server "https://github.com/jfpmonteiro/sok/blob/master/tests/rfi/server.c"
click node_rfi_h "https://github.com/jfpmonteiro/sok/blob/master/tests/rfi/rfi.h"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_makefile_root,node_doc_conf toneBlue
class node_sok_h,node_sok_c toneAmber
class node_simple_makefile,node_simple_client,node_simple_server,node_simple_cert,node_simple_key toneMint
class node_http_makefile,node_http_server toneRose
class node_rfi_client,node_rfi_server,node_rfi_h toneIndigo
```

## Components

### Build & docs

Top-level build entry points and documentation configuration.

- [Makefile](https://github.com/jfpmonteiro/sok/tree/master/Makefile): build entry · Primary repository build entry point. · `Makefile`
- [doc.conf](https://github.com/jfpmonteiro/sok/blob/master/doc.conf): docs config · Documentation/configuration layer separate from runtime code. · `doc.conf`

### Core library

Reusable socket abstraction exposed by the public header and implemented in C.

- [sok.h](https://github.com/jfpmonteiro/sok/blob/master/sok.h): public API · Public interface boundary for the socket library. · `sok.h`
- [sok.c](https://github.com/jfpmonteiro/sok/blob/master/sok.c): library impl · Implementation behind the public socket interface. · `sok.c`

### Simple test

Self-contained client/server scenario with TLS-style runtime assets.

- [Makefile](https://github.com/jfpmonteiro/sok/tree/master/tests/simple/Makefile): test build · Build file for the simple scenario. · `tests/simple/Makefile`
- [Client](https://github.com/jfpmonteiro/sok/blob/master/tests/simple/client.c): test client · Client process for the simple scenario. · `tests/simple/client.c`
- [Server](https://github.com/jfpmonteiro/sok/blob/master/tests/simple/server.c): test server · Server process for the simple scenario. · `tests/simple/server.c`
- [Cert](https://github.com/jfpmonteiro/sok/blob/master/tests/simple/certificate.crt): runtime asset · Certificate material used by the simple server. · `tests/simple/certificate.crt`
- [Key](https://github.com/jfpmonteiro/sok/blob/master/tests/simple/privateKey.key): runtime asset · Private key material used by the simple server. · `tests/simple/privateKey.key`

### HTTP test

Protocol-specific server example built on the core socket layer.

- [Makefile](https://github.com/jfpmonteiro/sok/tree/master/tests/http/Makefile): test build · Build file for the HTTP scenario. · `tests/http/Makefile`
- [HTTP Server](https://github.com/jfpmonteiro/sok/blob/master/tests/http/server.c): protocol server · HTTP-oriented server example on top of the core socket layer. · `tests/http/server.c`

### RFI test

Local client/server harness with its own shared test header.

- [Client](https://github.com/jfpmonteiro/sok/blob/master/tests/rfi/client.c): test client · Client process for the RFI scenario. · `tests/rfi/client.c`
- [Server](https://github.com/jfpmonteiro/sok/blob/master/tests/rfi/server.c): test server · Server process for the RFI scenario. · `tests/rfi/server.c`
- [rfi.h](https://github.com/jfpmonteiro/sok/blob/master/tests/rfi/rfi.h): local contract · Scenario-specific shared header for the RFI harness. · `tests/rfi/rfi.h`

## Connections

- Makefile → sok.c: builds · Builds the core library implementation.
- Makefile → sok.h: installs · Exposes the public interface as part of the build.
- Makefile → Makefile: delegates · Top-level build can delegate into scenario-specific targets.
- Makefile → Makefile: delegates · Top-level build can delegate into scenario-specific targets.
- Makefile → Client: builds · Compiles the simple client executable.
- Makefile → Server: builds · Compiles the simple server executable.
- Client → sok.h: uses · Client consumes the public socket API.
- Server → sok.h: uses · Server consumes the public socket API.
- Server → Cert: loads · Server uses certificate material at runtime.
- Server → Key: loads · Server uses private key material at runtime.
- Makefile → HTTP Server: builds · Compiles the HTTP server executable.
- HTTP Server → sok.h: uses · HTTP server builds on the public socket API.
- Client → sok.h: uses · Client consumes the public socket API.
- Server → sok.h: uses · Server consumes the public socket API.
- Client → rfi.h: shares · Client uses the test-local contract header.
- Server → rfi.h: shares · Server uses the test-local contract header.
- sok.c → sok.h: implements · Implementation realizes the public interface.