Space-Gib

Space-Gib is the multitenant synchronization peer and hosting environment for the IbGib ecosystem. It features a Node.js Express/serve-gib backend and a dynamic SPA client frontend.

Local Development Workflow

The local development environment uses a dual-target esbuild watch process and Docker for hosting the Node.js server behind a Traefik reverse proxy.

To run the full development loop, open three separate terminal windows:

Terminal 1: Watch (Client & Server)

Run the watch process to continuously type-check and bundle both client and server source files.

npm run watch:space-gib

Terminal 2: Run (Docker)

Start the Docker environment (Traefik + Node container).

npm run docker:space-gib

Once started, the application is available at https://space-gib.localhost

Terminal 3: Restart (As needed)

Because the Node.js process runs inside Docker, hot-reloading the server code requires restarting the container.

• Client changes: Auto-reload when you refresh the browser.
• Server changes: Run this command to load your newly compiled server code.

npm run restart:space-gib

Directory Structure

• src/client/: The browser SPA frontend. See Client README.
• src/server/: The Node.js server. See Server README.
• src/common/: Shared logic, types, and constants used by both client and server.

  [!IMPORTANT] STRICT RULE: src/common MUST NEVER import from src/client or src/server. This ensures the shared layer remains portable and prevents circular dependencies.

• dist/: The output directory where esbuild writes the bundled client (dist/client/) and server (dist/server/) code.

Debugging the Server

You can attach the VS Code debugger directly to the Node.js process running inside Docker.

1. The server runs with the --inspect=0.0.0.0:9229 flag.
2. docker-compose.yml maps port 9229 to your host machine.
3. Use the VS Code launch configuration Docker: Attach to Space-Gib to attach breakpoints.