# guepard-corp/gfs architecture

> Architecture diagram of the GitHub repository guepard-corp/gfs, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/guepard-corp/gfs
- Repository: https://github.com/guepard-corp/gfs

## Overview

GFS provides Git-like version control for database state: users initialize repositories, query and change databases, commit snapshots, then inspect history or switch branches and revisions. The CLI is the main user-facing workflow; an MCP server exposes operations to AI agents. Domain use cases sit above repository, provider, compute, and storage abstractions. Separate product branches include the web console, PostgreSQL proxy, and experimental lazy-clone extension. The README documents capabilities beyond the sampled implementations; dashed links mark workflow relationships that the excerpts do not establish.

Main entry points: [`crates/applications/cli/src/commands/cmd_query.rs`](https://github.com/guepard-corp/gfs/blob/main/crates/applications/cli/src/commands/cmd_query.rs) (GFS CLI), [`crates/domain/src/usecases/repository`](https://github.com/guepard-corp/gfs/tree/main/crates/domain/src/usecases/repository) (Repository operations), [`crates/domain/src/adapters/gfs_repository.rs`](https://github.com/guepard-corp/gfs/blob/main/crates/domain/src/adapters/gfs_repository.rs) (Repository adapter), [`crates/domain/src/ports`](https://github.com/guepard-corp/gfs/tree/main/crates/domain/src/ports) (Domain ports)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["User interfaces"]
  node_cli["GFS CLI<br/>[cmd_query.rs]"]
  node_mcp["MCP server<br/>[tools.rs]"]
  node_console["Web console<br/>[main.rs]"]
  node_consoleui["Console UI<br/>[App.tsx]"]
end

subgraph group_domain["Version control"]
  node_usecases["Repository operations"]
  node_repo["Repository adapter<br/>[gfs_repository.rs]"]
  node_layout["Repository layout<br/>[repo_layout.rs]"]
  node_commit["Commit model<br/>[commit.rs]"]
  node_config["Repository config<br/>[config.rs]"]
  node_ports["Domain ports"]
end

subgraph group_runtime["Database runtime"]
  node_provider["Database providers"]
  node_compute["Compute runtime<br/>[lib.rs]"]
  node_storage["Database storage<br/>[lib.rs]"]
end

subgraph group_proxy["Proxy and cloning"]
  node_proxyapp["Postgres proxy<br/>[proxy.rs]"]
  node_discovery["Clone discovery<br/>[discovery.rs]"]
  node_gfs["Lazy clone extension<br/>[route.rs]"]
  node_catalog[("Clone catalog<br/>[catalog.rs]")]
  node_hydrate["Row hydration<br/>[hydrate.rs]"]
  node_worker["Copy worker<br/>[worker.rs]"]
end

subgraph group_adapters["Infrastructure adapters"]
end

node_developer(("Developer or agent"))

node_developer -->|"runs commands"| node_cli
node_developer -->|"uses tools"| node_mcp
node_developer -.->|"views databases"| node_consoleui
node_cli -->|"executes query"| node_usecases
node_usecases -->|"uses abstractions"| node_ports
node_usecases -.->|"manages repository"| node_repo
node_repo -->|"delegates layout"| node_layout
node_repo -->|"records commits"| node_commit
node_repo -->|"reads config"| node_config
node_ports -->|"defines provider port"| node_provider
node_ports -->|"defines compute port"| node_compute
node_cli -->|"selects provider"| node_provider
node_cli -->|"runs query"| node_compute
node_consoleui -.->|"requests API"| node_console
node_console -.->|"reads clone data"| node_discovery
node_proxyapp -.->|"runs proxy"| node_discovery
node_gfs -->|"tracks clone state"| node_catalog
node_gfs -->|"hydrates rows"| node_hydrate
node_worker -->|"performs queued copy"| node_hydrate
node_worker -->|"updates predicate state"| node_catalog
node_usecases -.->|"uses storage"| node_storage

click node_cli "https://github.com/guepard-corp/gfs/blob/main/crates/applications/cli/src/commands/cmd_query.rs"
click node_mcp "https://github.com/guepard-corp/gfs/blob/main/crates/applications/mcp/src/tools.rs"
click node_console "https://github.com/guepard-corp/gfs/blob/main/crates/applications/console/src/main.rs"
click node_consoleui "https://github.com/guepard-corp/gfs/blob/main/crates/applications/console/web/src/App.tsx"
click node_usecases "https://github.com/guepard-corp/gfs/tree/main/crates/domain/src/usecases/repository"
click node_repo "https://github.com/guepard-corp/gfs/blob/main/crates/domain/src/adapters/gfs_repository.rs"
click node_layout "https://github.com/guepard-corp/gfs/blob/main/crates/domain/src/repo_utils/repo_layout.rs"
click node_commit "https://github.com/guepard-corp/gfs/blob/main/crates/domain/src/model/commit.rs"
click node_config "https://github.com/guepard-corp/gfs/blob/main/crates/domain/src/model/config.rs"
click node_ports "https://github.com/guepard-corp/gfs/tree/main/crates/domain/src/ports"
click node_provider "https://github.com/guepard-corp/gfs/tree/main/crates/adapters/db-providers/src"
click node_compute "https://github.com/guepard-corp/gfs/blob/main/crates/adapters/compute-docker/src/lib.rs"
click node_storage "https://github.com/guepard-corp/gfs/blob/main/crates/adapters/storage-file/src/lib.rs"
click node_proxyapp "https://github.com/guepard-corp/gfs/blob/main/crates/applications/proxy/src/proxy.rs"
click node_discovery "https://github.com/guepard-corp/gfs/blob/main/crates/applications/proxy/src/discovery.rs"
click node_gfs "https://github.com/guepard-corp/gfs/blob/main/crates/extensions/gfs/src/route.rs"
click node_catalog "https://github.com/guepard-corp/gfs/blob/main/crates/extensions/gfs/src/catalog.rs"
click node_hydrate "https://github.com/guepard-corp/gfs/blob/main/crates/extensions/gfs/src/hydrate.rs"
click node_worker "https://github.com/guepard-corp/gfs/blob/main/crates/extensions/gfs/src/worker.rs"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_mcp,node_console,node_consoleui toneBlue
class node_usecases,node_repo,node_layout,node_commit,node_config,node_ports toneAmber
class node_provider,node_compute,node_storage toneMint
class node_proxyapp,node_discovery,node_gfs,node_catalog,node_hydrate,node_worker toneRose
class node_developer toneIndigo
```

## Components

### User interfaces

- [GFS CLI](https://github.com/guepard-corp/gfs/blob/main/crates/applications/cli/src/commands/cmd_query.rs): `crates/applications/cli/src/commands/cmd_query.rs`
- [MCP server](https://github.com/guepard-corp/gfs/blob/main/crates/applications/mcp/src/tools.rs): `crates/applications/mcp/src/tools.rs`
- [Web console](https://github.com/guepard-corp/gfs/blob/main/crates/applications/console/src/main.rs): `crates/applications/console/src/main.rs`
- [Console UI](https://github.com/guepard-corp/gfs/blob/main/crates/applications/console/web/src/App.tsx): `crates/applications/console/web/src/App.tsx`

### Version control

- [Repository operations](https://github.com/guepard-corp/gfs/tree/main/crates/domain/src/usecases/repository): `crates/domain/src/usecases/repository`
- [Repository adapter](https://github.com/guepard-corp/gfs/blob/main/crates/domain/src/adapters/gfs_repository.rs): `crates/domain/src/adapters/gfs_repository.rs`
- [Repository layout](https://github.com/guepard-corp/gfs/blob/main/crates/domain/src/repo_utils/repo_layout.rs): `crates/domain/src/repo_utils/repo_layout.rs`
- [Commit model](https://github.com/guepard-corp/gfs/blob/main/crates/domain/src/model/commit.rs): `crates/domain/src/model/commit.rs`
- [Repository config](https://github.com/guepard-corp/gfs/blob/main/crates/domain/src/model/config.rs): `crates/domain/src/model/config.rs`
- [Domain ports](https://github.com/guepard-corp/gfs/tree/main/crates/domain/src/ports): `crates/domain/src/ports`

### Database runtime

- [Database providers](https://github.com/guepard-corp/gfs/tree/main/crates/adapters/db-providers/src): `crates/adapters/db-providers/src`
- [Compute runtime](https://github.com/guepard-corp/gfs/blob/main/crates/adapters/compute-docker/src/lib.rs): `crates/adapters/compute-docker/src/lib.rs`
- [Database storage](https://github.com/guepard-corp/gfs/blob/main/crates/adapters/storage-file/src/lib.rs): `crates/adapters/storage-file/src/lib.rs`

### Proxy and cloning

- [Postgres proxy](https://github.com/guepard-corp/gfs/blob/main/crates/applications/proxy/src/proxy.rs): `crates/applications/proxy/src/proxy.rs`
- [Clone discovery](https://github.com/guepard-corp/gfs/blob/main/crates/applications/proxy/src/discovery.rs): `crates/applications/proxy/src/discovery.rs`
- [Lazy clone extension](https://github.com/guepard-corp/gfs/blob/main/crates/extensions/gfs/src/route.rs): `crates/extensions/gfs/src/route.rs`
- [Clone catalog](https://github.com/guepard-corp/gfs/blob/main/crates/extensions/gfs/src/catalog.rs): `crates/extensions/gfs/src/catalog.rs`
- [Row hydration](https://github.com/guepard-corp/gfs/blob/main/crates/extensions/gfs/src/hydrate.rs): `crates/extensions/gfs/src/hydrate.rs`
- [Copy worker](https://github.com/guepard-corp/gfs/blob/main/crates/extensions/gfs/src/worker.rs): `crates/extensions/gfs/src/worker.rs`

### Other components

- **Developer or agent**

## Connections

- Developer or agent → GFS CLI: runs commands
- Developer or agent → MCP server: uses tools
- Developer or agent → Console UI: views databases
- GFS CLI → Repository operations: executes query (evidence: `crates/applications/cli/src/commands/cmd_query.rs`)
- Repository operations → Domain ports: uses abstractions (evidence: `crates/domain/src/usecases/repository/execute_query_usecase.rs`)
- Repository operations → Repository adapter: manages repository
- Repository adapter → Repository layout: delegates layout (evidence: `crates/domain/src/adapters/gfs_repository.rs`)
- Repository adapter → Commit model: records commits (evidence: `crates/domain/src/adapters/gfs_repository.rs`)
- Repository adapter → Repository config: reads config (evidence: `crates/domain/src/adapters/gfs_repository.rs`)
- Domain ports → Database providers: defines provider port (evidence: `crates/domain/src/ports/database_provider.rs`)
- Domain ports → Compute runtime: defines compute port (evidence: `crates/domain/src/ports/compute.rs`)
- GFS CLI → Database providers: selects provider (evidence: `crates/applications/cli/src/commands/cmd_query.rs`)
- GFS CLI → Compute runtime: runs query (evidence: `crates/applications/cli/src/commands/cmd_query.rs`)
- Console UI → Web console: requests API
- Web console → Clone discovery: reads clone data
- Postgres proxy → Clone discovery: runs proxy
- Lazy clone extension → Clone catalog: tracks clone state
- Lazy clone extension → Row hydration: hydrates rows (evidence: `crates/extensions/gfs/src/hydrate.rs`)
- Copy worker → Row hydration: performs queued copy (evidence: `crates/extensions/gfs/src/worker.rs`)
- Copy worker → Clone catalog: updates predicate state (evidence: `crates/extensions/gfs/src/worker.rs`)
- Repository operations → Database storage: uses storage
