Dear Antonio,
thank you once again very warmly for the tip and for your persistence in encouraging us to finally start with Antigravity, or more generally with agentic software development. In the end, the installation was truly not that difficult at all. Here is my first result: I had the microservice examined thoroughly, especially with regard to the use of the Harbourino style during development and in the evaluation.
Now, of course, I first need to familiarize myself with how to use the program and see how well it fits in with my other workflows, but I think I’ll manage.
Best regards,
Otto
The structure you have outlined reveals a fascinating architectural concept: the project quite obviously uses Harbourino as a code assembler, preprocessor, or snippet manager.
With Harbourino, the source code is not maintained as one huge, confusing monolithic .prg file, but instead split into atomic, logical building blocks (snippets). At compile time, Harbourino pulls these building blocks together (marked by placeholders or comments such as //-- HARBOURINO HB_MAIN --//) and generates the actual compilable Harbour code.
From this perspective, the architecture can be analyzed excellently. It is broadly divided into two worlds:
Harbour level (business logic & locking)
C level (BEGINDUMP) (low-level web server & sockets)
Here is the analysis of the project based on the Harbourino building blocks you mentioned:
Harbour level (business logic & state)
-> HB_MAIN
The main entry point of the compiled application (FUNCTION Main()). Hierarchically, this is the framework from which constants are loaded, the audit directory is initialized, and finally the HTTP server written in C is started.
The locking & sweep mechanism
Since traditional DBF databases are used, conflict management is extremely important, especially when access happens via web/API (statelessness). The following snippets handle concurrent access to bookings ("record locks" with a time limit):
-> ACQUIRE_GUARD_SWEEP_SETZEN: Sets a guard. When a user/client reserves a resource, a lease timer is set.
-> GUARD_LOCKS_DBF: Handles the central table (LOCKS.DBF), which records who is currently editing which room/which booking.
-> RELEASE_IDEMPOTENT: Cleanly releases a lock again (idempotent means that even if it is called multiple times, nothing crashes).
-> SWEEP_STATUS / -> LOCKSTATUS: A garbage collection (sweep) for locks. If a client crashes (for example, the browser is closed), locks do not remain stuck forever after the lease time expires, but are recognized and deleted by the "sweeper."
-> F_DB_API: API layer for database operations. Presumably core routines such as opening DBFs, searching, and pagination, which are used by the various endpoints.
-> CONVERTUMLAUTE: Converts umlauts between systems (presumably ANSI / Code Page 850 / DEWIN to UTF-8 for clean JSON in the web frontend).
C level (#pragma BEGINDUMP ... #pragma ENDDUMP)
This is where Harbour shows its greatest strength: native embedding of C code. Since Harbour itself does not have a built-in high-performance multithreading HTTP server for modern web APIs, one was implemented here directly and efficiently on top of the Windows Socket API (Winsock) in pure C. Harbourino logically assembles the C functions:
Helper functions & utilities:
-> INCLUDEFILES_C: Loads C header files (<winsock2.h>, <stdio.h>, etc.).
-> HELPERS_4_HTML / -> HF_LOGGING: Generates HTML output for error pages and provides C logging functionality.
-> SHELL_EXECUTE: A C wrapper for the Windows API ShellExecute in order to call external programs (such as checkweb.exe).
Security & routing:
-> CRYPTACQUIRECONTEXT: Calls Windows crypto APIs (often used for random numbers, nonces, or SSL).
-> GETPVPROFSTRING / -> HELPER: Reads, for example, INI files or contains string utilities for C.
-> GET_HEADER_VALUE_CI: Case-insensitive reading of HTTP headers (for example Authorization: or Content-Type:).
-> G_EXPECTED_TOKEN / -> IS_TOKEN_OK / -> ROUTE_NEEDS_AUTH: This is the authentication middleware. Before an API call reaches the hotel API, it is checked whether the route is protected and whether the supplied bearer token is valid.
HTTP & JSON response architecture:
-> SEND_ALL: Ensures that large TCP packets are sent completely to the socket (prevents truncated JSON output).
-> ADD_CORS_HEADERS: Adds Access-Control-Allow-Origin: * so that browser applications can access the backend across different domains (Cross-Origin Resource Sharing).
-> BUILDANDSENDJSONRESPONSE / -> F_BUILDJSONRESPONSE: Takes the JSON string generated in Harbour, wraps it in a valid HTTP 1.1 header (200 OK, Content-Length), and sends it to the client through the socket.
The heartbeat: HB_FUNC( STARTHTTPSERVER )
This is the main loop of the C server, called from the Harbour level. Harbourino builds this function step by step like Lego:
-> WSASTARTUP: Initializes the Windows Socket API.
-> SOCKET_CREATE / -> PORT_BIND / -> LISTENSOCKET: Creates the TCPv4 socket, binds it to a port (for example 80 or 8080), and puts it into listening mode.
The main loop (while (1)) (synchronous blocking):
-> ACCEPT: Waits until a browser/client connects.
-> READ_REQUEST / -> REQUESTLINE: Reads the raw HTTP traffic and parses, for example, POST /api/customers HTTP/1.1.
-> ROUTER: (The core component) Takes the extracted HTTP URL and forwards it in C via hb_itemDoC() to the Harbour functions (for example to HANDLE_READRECORD_CUSTOMERS).
-> CLIENTSOCKET_RESPONSE: Takes the return value from Harbour routing and sends it.
-> SHUTDOWN_CLIENTSOCKET / -> SO_LINGER / -> CLOSESOCKET: Ends the transaction. SO_LINGER ensures that any TCP packets still in flight leave the system cleanly before the socket is forcibly closed.
-> CLOSEMAINSOCKET / -> WINSOCKET_CLEAN: In the event of a server shutdown, memory is released again.
Conclusion on the Harbourino approach
The code uses Harbourino extremely intelligently as an architectural tool: the C part of the HTTP server (STARTHTTPSERVER) would normally be horrible spaghetti code in C. Harbourino breaks the C code down into digestible, reusable blocks (socket init, auth, router, teardown). At the same time, on the Harbour side it provides a clean interface concept (controller functions) so that the business logic (locking, DBF read/write operations, umlauts) can be programmed completely separately from the TCP/IP low-level details.