Small moving parts, explicit boundaries.

01 / FLOW

A browser action becomes durable work.

The hand-written HTTP/1.1 server accepts a request and passes it to the application router. Page handlers read SQLite to render the repository list, detail pages, and job history. Actions that change mirrors or refresh metadata insert a job first; worker threads claim and execute those jobs later.

Clone, fetch, health check, GitHub metadata refresh, and account import are queued jobs. File trees, blobs, commits, and archives are local reads from the mirror; these run during the browsing request rather than entering the network-work queue.

GitCube runs child commands with posix_spawnp and argument arrays, never by concatenating a shell command. The process wrapper captures output, enforces timeouts, and handles termination during shutdown.

02 / STORAGE

One data directory holds the collection.

The SQLite database tracks repositories, jobs, refs, releases, and schema migrations. Bare mirrors live in paths based on repository IDs; temporary clone staging and exports are kept separately.

data/
├── gitcube.sqlite3
├── gitcube.lock
├── repositories/
│   └── by-id/42.git/
├── tmp/
├── cache/
└── logs/

The database uses WAL mode and a thread-safe connection pool. Schema changes are applied as ordered migrations, including when a database is created for the first time. Startup verifies essential columns so a mismatch fails clearly rather than surfacing later during a request.

03 / RELIABILITY

Incomplete work stays incomplete.

A clone starts under data/tmp and moves into its final mirror path only after git clone --mirror succeeds. An interrupted clone cannot appear as a ready mirror. A hard crash can leave staging files, which GitCube removes on the next start.

The queue records work before a worker starts it. On graceful shutdown, GitCube stops accepting new requests and claims, gives active commands a short window to finish, then returns interrupted jobs to the queue. Per-repository locking prevents two workers from changing the same mirror at once.

GitHub rate-limit responses delay affected metadata work until a suitable retry time. Transient failures use bounded backoff rather than leaving a job running forever.

04 / SECURITY

A local tool with a clear trust boundary.

GitCube binds to loopback by default. It has no user login or built-in TLS, so the intended use is a single-user browser on the same machine. Binding to a non-loopback address requires explicit flags and still calls for authentication and HTTPS in front of GitCube.

• Restricted inputs. Repository URLs must use public HTTP(S), without embedded credentials. Ref names and repository-relative paths are validated before Git receives them.
• Protected actions. POST handlers require a per-process CSRF token; the HTTP server also checks allowed Host names and rejects browser requests explicitly marked cross-site.
• No shell interpolation. Git, curl, and zip receive controlled arguments and environment, so URL or path text cannot become shell syntax.
• Safe file display. Potentially executable raw formats such as HTML, SVG, and XML are served as plain text inside the GitCube origin.

The HTTP server bounds clients and request time, and the GitHub JSON parser caps nesting depth. These limits are meant to keep a public repository or remote response from consuming unlimited resources.

05 / SCOPE

What this version does not try to do.