---
title: Architecture
description: The system architecture, storage layers, protocol engines, and trust boundaries of exist.io.
---

exist.io is designed as a single, self-contained Go binary with clear separation of responsibilities between forge metadata, Git object storage, and protocol transport.

## System overview

```mermaid
flowchart TD
    subgraph Clients["Client Ecosystem"]
        GitClient["Git CLI & Workflows<br/>(git clone, push, fetch)"]
        GitSSH["Git over SSH (:2222)<br/>(OpenSSH / Ed25519)"]
        GitLFS["Git LFS Client<br/>(Batch API & CAS)"]
        Agent["AI Coding Agents<br/>(MCP JSON-RPC Protocol)"]
        WebUI["Space UI Living Dashboard<br/>(React 19 / Vite / Motion)"]
        IdP["Corporate IdP (Entra / Okta)<br/>(OIDC, SAML, SCIM 2.0)"]
        IaC["Terraform & Helm<br/>(Infrastructure as Code)"]
    end

    subgraph Service["existd Service Daemon"]
        Gateway["HTTP Server & Auth Guard<br/>(Bearer Token, Session Cookies, Basic Auth)"]
        SSHServer["Pure-Go SSH Daemon<br/>(Port 2222, Zero CGO, Host Keys)"]
        SmartHTTP["Git Smart-HTTP Engine<br/>(Upload-Pack / Receive-Pack)"]
        LFSEngine["Git LFS v1 Batch CAS Engine<br/>(SHA-256 Verification & File Locks)"]
        SigEngine["Commit Signature Engine<br/>(OpenSSH SIGSPEC & GPG RFC 4880)"]
        MCPServer["MCP JSON-RPC Server<br/>(34 AI Agent Tools at /mcp)"]
        RESTRouter["REST API Router<br/>(119 Forge Operations at /v1/origin)"]
        Federation["Federation & SCIM Engine<br/>(/scim/v2/Users, OIDC & SAML SSO)"]
        PolicyEngine["3-Way Merge & Ruleset Engine<br/>(Approvals, Checks, CIDR, SSH CA)"]
    end

    subgraph Storage["Hermetic Local Storage"]
        MetaDB[("SQLite Database (WAL Mode)<br/>Metadata, Grants, PRs, Rules, SSO")]
        GitRepo[("Bare Git Repositories (go-git v6)<br/>Packfiles, Commits, Trees, Refs")]
        LFSCAS[("LFS Content-Addressable Storage<br/>(SHA-256 Sharded Binary Objects)")]
    end

    GitClient --> Gateway
    GitSSH --> SSHServer
    GitLFS --> Gateway
    Agent --> Gateway
    WebUI --> Gateway
    IdP --> Federation
    IaC --> RESTRouter

    Gateway --> SmartHTTP
    Gateway --> LFSEngine
    Gateway --> MCPServer
    Gateway --> RESTRouter
    Gateway --> Federation

    SSHServer --> SigEngine
    SmartHTTP --> SigEngine
    SigEngine --> GitRepo
    LFSEngine --> LFSCAS

    RESTRouter --> PolicyEngine
    MCPServer --> PolicyEngine

    SmartHTTP --> GitRepo
    SSHServer --> GitRepo
    RESTRouter --> GitRepo
    RESTRouter --> MetaDB
    MCPServer --> GitRepo
    MCPServer --> MetaDB
    Federation --> MetaDB
```

## Storage model

exist.io separates data storage into three specialized layers:

### 1. Forge metadata (SQLite WAL)

All non-Git entities are managed by a SQLite database running in Write-Ahead Logging (WAL) mode with foreign key constraints enforced:

- **Identity & Credentials:** Users, password hashes (bcrypt), active web sessions, API tokens (stored as SHA-256 hashes), user SSH public keys, and Personal Access Tokens.
- **Grants & Authorization:** Namespace and repository role assignments (`admin`, `write`, `read`).
- **Pull Requests & Social:** PR metadata, review threads, line-level comments, reactions, and labels.
- **Checks & Rulesets:** Check suites, check runs, branch/tag protection rulesets, and bypass actor lists.
- **Enterprise Controls:** Inbound IP allowlists (CIDR blocks), SSH Certificate Authorities, and SSO / SCIM configurations.

The database runs via `modernc.org/sqlite`, a pure Go implementation requiring zero cgo compilers.

### 2. Git object storage (`go-git`)

Repository source code is stored as bare Git repositories managed by `github.com/go-git/go-git/v6` under the operator's configured data directory (`./data/repos/{owner}/{repo}.git`):

- Standard Git packfiles, trees, commits, blobs, and references.
- Repositories are standard Git directories that can be backed up or transferred with standard tools.

### 3. Git LFS Content-Addressable Storage (CAS)

Large binary assets are stored in a Content-Addressable Storage directory (`./data/lfs/objects/{oid[0:2]}/{oid[2:4]}/{oid}`) verified with cryptographic SHA-256 hashes.

---

## Protocol engines

### Embedded Pure-Go SSH Server

Runs on port `2222` (configurable via `EXIST_SSH_ADDR`):
- Pure Go SSH implementation with zero host OpenSSH daemon requirements.
- Authenticates Git clients against user public keys in the SQLite database and organization-wide SSH Certificate Authorities.
- Supports streaming `git-upload-pack` and `git-receive-pack` with pre-receive security push protection hooks.

### Git Large File Storage (LFS) v1 Engine

Mounted under repository endpoints:
- Implements the Git LFS v1 Batch HTTP protocol (`/info/lfs/objects/batch`).
- Streaming binary object upload with real-time SHA-256 checksum verification.
- Streaming object downloads with HTTP `Range` headers.
- RFC-compliant binary file locking protocol (`/info/lfs/locks`) preventing merge collisions on unmergeable assets.

### Cryptographic Commit Signature Engine

- Parses **OpenSSH SIGSPEC** binary signatures and **GPG (OpenPGP RFC 4880)** ASCII armor.
- Evaluates committer public key fingerprints against enrolled developer keys.
- Surfaces cryptographic verification audit data in the Web UI and REST API.

### Enterprise Federation & SCIM 2.0 Engine

- Implements **RFC 7643 / RFC 7644 SCIM 2.0** at `/scim/v2/Users` for automated user provisioning and offboarding.
- Single Sign-On (SSO) support for both **OpenID Connect (OIDC)** and **SAML 2.0**.
- Automatic workspace provisioning upon first login and session cookie lifecycle management.

### Model Context Protocol (MCP) server

Mounted at `/mcp` (read-write) and `/mcp/readonly`:
- Implements JSON-RPC 2.0 per the Model Context Protocol specification.
- Exposes **34 specialized tools** enabling AI coding agents to navigate codebases, inspect diffs, open pull requests, post review comments, and report status check results.

### Merge and ruleset policy engine

- Native 3-way merge and squash merge logic.
- Evaluates branch and tag rulesets before push and merge operations.
- Enforces required review approvals, unresolved review thread blockers, and passing status checks.
- Honors bypass actor configurations for designated administrators.