76 lines
2.8 KiB
Markdown
76 lines
2.8 KiB
Markdown
# 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 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.
|
|
- 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 emits normalized branch events for internal proto-socket
|
|
consumers such as NomadCode.
|
|
|
|
## 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.
|