# 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 and
worker deployments later. Agent interaction UI is provided by the sibling
`../agent-shell` Flutter package, and the agent backend/runtime is owned by the
sibling `../iop` project.

## Layers

### Control Plane

- Owns external REST API/webhook surfaces and internal proto-socket surfaces.
- Accepts user, automation, and provider callback requests.
- Applies auth, policy, and approval gates.
- Creates operations and delivers normalized events.
- 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.
- Coordinates with the IOP backend/runtime for agent execution results.
- Records operation outcomes and emits events.
- Handles retry and backoff policy.

### Agent Shell Package And IOP Backend

- `../agent-shell` is a product-agnostic Flutter UI/domain package.
- Flutter hosts attach it as an `agent_shell: path: ../agent-shell` package
  dependency rather than treating Gito as the agent UI package.
- `../iop` owns the backend/runtime that executes agents, shell commands, and
  model/runtime orchestration.
- Gito does not execute arbitrary workspace commands directly.
- Gito records IOP backend results as operation state, Git revision, and event
  records.

### 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 Forgejo/Gitea PR, GitHub PR, and GitLab MR into provider-neutral
  `ChangeRequest` operations.
- Treat webhooks as wakeup signals. Final state must be verified through Git
  revision or provider read APIs.
- MVP priority is Forgejo push intake: provider webhooks enter through REST
  callbacks, then Gito records normalized branch events. External consumers
  receive them through signed HTTP webhook delivery, not proto-socket.

## Transport

- REST is the external integration surface for provider callbacks, public APIs,
  HTTP webhook delivery, health/readiness, smoke/curl, and simple bootstrap
  endpoints.
- proto-socket is internal-only control/runtime transport. It is not an external
  integration contract and is not offered as a fallback consumer transport.
- 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.
