gito/docs/architecture.md

Architecture

Gito starts as a modular monolith with separable process roles. The codebase can run as one service at first, but its boundaries should allow separate server, worker, and shell deployments later.

Layers

Control Plane

• Owns proto-socket and REST surfaces.
• Accepts user, automation, and provider callback requests.
• Applies auth, policy, and approval gates.
• Creates operations and exposes event streams.
• Does not execute Git commands directly.

Core Domain

• Owns repository registry, workspace leases, operations, revision cursors, idempotency keys, audit records, and normalized events.
• Knows provider-neutral concepts such as Repo, WorkspaceLease, GitOperation, RevisionEvent, and ChangeRequest.
• Does not know GitHub, GitLab, Gitea, Plane, Jira, or IOP HTTP details.

Worker

• Picks pending operations.
• Coordinates workspace leases.
• Calls agent-shell for filesystem and command execution.
• Records operation outcomes and emits events.
• Handles retry and backoff policy.

Agent Shell

• Runs on a machine that owns local workspace access.
• Executes Git CLI and IOP CLI commands.
• Streams logs, handles cancellation, and enforces dirty-workspace guards.
• Connects outbound to the control plane where possible.

Git Engine

• Platformless Git operation layer.
• Supports clone, fetch, pull, checkout, status, diff, commit, push, branch, tag, and revision scans.
• Must be testable against local bare repositories without GitHub, GitLab, or Gitea.

Provider Adapters

• Own platform APIs and DTOs.
• Map GitHub PR, GitLab MR, and Gitea PR into provider-neutral ChangeRequest operations.
• Treat webhooks as wakeup signals. Final state must be verified through Git revision or provider read APIs.

Transport

• proto-socket is the default internal runtime transport.
• REST is reserved for health/readiness, provider callbacks, smoke/curl, and simple bootstrap endpoints.
• gRPC is intentionally out of scope for the initial architecture.

Event Policy

All external side effects should produce durable operation and event records in PostgreSQL. Redis may be added later for fanout or stream acceleration, but it is not the source of truth.