# jguer/yay architecture

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

- Interactive diagram: https://gitdiagram.com/jguer/yay
- Repository: https://github.com/jguer/yay

## Overview

yay is a Go AUR helper for searching, querying, upgrading, and installing Arch packages from both repositories and the AUR. The main CLI initializes configuration and runtime services, then dispatches package operations; the sync operation prepares build directories, checks source metadata and PGP keys, and installs packages. Dependency solving, PKGBUILD retrieval, upgrade checks, completions, voting, and Lua customization are additional product branches. Some dispatch and build implementation files were not excerpted, so those relationships are shown only where README documentation or sampled references support them.

Main entry points: [`main.go`](https://github.com/jguer/yay/blob/next/main.go) (CLI entry), [`pkg/sync/sync.go`](https://github.com/jguer/yay/blob/next/pkg/sync/sync.go) (Sync operation), [`pkg/db/ialpm/alpm.go`](https://github.com/jguer/yay/blob/next/pkg/db/ialpm/alpm.go) (Package database), [`pkg/upgrade/service.go`](https://github.com/jguer/yay/blob/next/pkg/upgrade/service.go) (Upgrade service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI and Runtime"]
  node_entry["CLI entry<br/>[main.go]"]
  node_config["Configuration<br/>[config.go]"]
  node_arguments["Argument parsing<br/>[parser.go]"]
  node_runtime["Runtime services<br/>[runtime.go]"]
  node_command["Command dispatch<br/>[cmd.go]"]
end

subgraph group_packages["Package Discovery"]
  node_query["Package search<br/>[query_builder.go]"]
  node_db[("Package database<br/>[alpm.go]")]
  node_dependency["Dependency solver<br/>[dep_graph.go]"]
  node_download["PKGBUILD retrieval<br/>[unified.go]"]
  node_upgrade["Upgrade service<br/>[service.go]"]
  node_aur["AUR service"]
end

subgraph group_build["Build and Install"]
  node_sync["Sync operation<br/>[sync.go]"]
  node_workdir["Build preparation<br/>[preparer.go]"]
  node_srcinfo["Source metadata<br/>[service.go]"]
  node_installer["Package installer"]
  node_diff["PKGBUILD review<br/>[diff_menu.go]"]
end

subgraph group_system["System Operations"]
  node_vcs[("Development tracking<br/>[vcs.go]")]
  node_completion["AUR completions<br/>[completion.go]"]
  node_vote["Package voting<br/>[vote.go]"]
  node_querycmd["Package queries<br/>[query.go]"]
  node_cleanup["Package cleanup<br/>[clean.go]"]
  node_lua["Lua customization"]
end

node_user(("CLI user"))

node_user -->|"invokes"| node_entry
node_entry -->|"loads"| node_config
node_entry -->|"parses options"| node_arguments
node_entry -->|"creates"| node_runtime
node_entry -->|"opens database"| node_db
node_entry -.->|"dispatches"| node_command
node_runtime -->|"creates"| node_query
node_runtime -->|"creates"| node_vcs
node_query -->|"searches"| node_aur
node_query -->|"queries packages"| node_db
node_dependency -->|"resolves against"| node_db
node_dependency -.->|"retrieves package data"| node_aur
node_download -->|"fetches package data"| node_aur
node_download -->|"selects package source"| node_db
node_upgrade -->|"checks updates"| node_aur
node_upgrade -.->|"uses dependency graph"| node_dependency
node_sync -->|"prepares builds"| node_workdir
node_sync -->|"checks source metadata"| node_srcinfo
node_sync -->|"installs packages"| node_installer
node_sync -->|"updates completions"| node_completion
node_sync -->|"runs post-install hooks"| node_lua
node_workdir -.->|"retrieves build sources"| node_download
node_srcinfo -->|"updates development records"| node_vcs
node_diff -->|"requests review"| node_user
node_upgrade -.->|"checks repository updates"| node_db
node_command -.->|"routes queries"| node_querycmd
node_user -->|"requests package query"| node_querycmd
node_user -->|"votes packages"| node_vote
node_user -->|"cleans dependencies"| node_cleanup
node_user -->|"requests completions"| node_completion
node_user -->|"requests upgrades"| node_upgrade
node_user -->|"requests package install"| node_sync

click node_entry "https://github.com/jguer/yay/blob/next/main.go"
click node_config "https://github.com/jguer/yay/blob/next/pkg/settings/config.go"
click node_arguments "https://github.com/jguer/yay/blob/next/pkg/settings/parser/parser.go"
click node_runtime "https://github.com/jguer/yay/blob/next/pkg/runtime/runtime.go"
click node_command "https://github.com/jguer/yay/blob/next/cmd.go"
click node_query "https://github.com/jguer/yay/blob/next/pkg/query/query_builder.go"
click node_db "https://github.com/jguer/yay/blob/next/pkg/db/ialpm/alpm.go"
click node_dependency "https://github.com/jguer/yay/blob/next/pkg/dep/dep_graph.go"
click node_download "https://github.com/jguer/yay/blob/next/pkg/download/unified.go"
click node_upgrade "https://github.com/jguer/yay/blob/next/pkg/upgrade/service.go"
click node_sync "https://github.com/jguer/yay/blob/next/pkg/sync/sync.go"
click node_workdir "https://github.com/jguer/yay/blob/next/pkg/sync/workdir/preparer.go"
click node_srcinfo "https://github.com/jguer/yay/blob/next/pkg/sync/srcinfo/service.go"
click node_installer "https://github.com/jguer/yay/tree/next/pkg/sync/build"
click node_diff "https://github.com/jguer/yay/blob/next/pkg/menus/diff_menu.go"
click node_vcs "https://github.com/jguer/yay/blob/next/pkg/vcs/vcs.go"
click node_completion "https://github.com/jguer/yay/blob/next/pkg/completion/completion.go"
click node_vote "https://github.com/jguer/yay/blob/next/vote.go"
click node_querycmd "https://github.com/jguer/yay/blob/next/query.go"
click node_cleanup "https://github.com/jguer/yay/blob/next/clean.go"
click node_lua "https://github.com/jguer/yay/tree/next/pkg/settings/lua"

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_entry,node_config,node_arguments,node_runtime,node_command,node_user toneBlue
class node_query,node_db,node_dependency,node_download,node_upgrade,node_aur toneAmber
class node_sync,node_workdir,node_srcinfo,node_installer,node_diff toneMint
class node_vcs,node_completion,node_vote,node_querycmd,node_cleanup,node_lua toneRose
```

## Components

### CLI and Runtime

- [CLI entry](https://github.com/jguer/yay/blob/next/main.go): `main.go`
- [Configuration](https://github.com/jguer/yay/blob/next/pkg/settings/config.go): `pkg/settings/config.go`
- [Argument parsing](https://github.com/jguer/yay/blob/next/pkg/settings/parser/parser.go): `pkg/settings/parser/parser.go`
- [Runtime services](https://github.com/jguer/yay/blob/next/pkg/runtime/runtime.go): `pkg/runtime/runtime.go`
- [Command dispatch](https://github.com/jguer/yay/blob/next/cmd.go): `cmd.go`

### Package Discovery

- [Package search](https://github.com/jguer/yay/blob/next/pkg/query/query_builder.go): `pkg/query/query_builder.go`
- [Package database](https://github.com/jguer/yay/blob/next/pkg/db/ialpm/alpm.go): `pkg/db/ialpm/alpm.go`
- [Dependency solver](https://github.com/jguer/yay/blob/next/pkg/dep/dep_graph.go): `pkg/dep/dep_graph.go`
- [PKGBUILD retrieval](https://github.com/jguer/yay/blob/next/pkg/download/unified.go): `pkg/download/unified.go`
- [Upgrade service](https://github.com/jguer/yay/blob/next/pkg/upgrade/service.go): `pkg/upgrade/service.go`
- **AUR service**

### Build and Install

- [Sync operation](https://github.com/jguer/yay/blob/next/pkg/sync/sync.go): `pkg/sync/sync.go`
- [Build preparation](https://github.com/jguer/yay/blob/next/pkg/sync/workdir/preparer.go): `pkg/sync/workdir/preparer.go`
- [Source metadata](https://github.com/jguer/yay/blob/next/pkg/sync/srcinfo/service.go): `pkg/sync/srcinfo/service.go`
- [Package installer](https://github.com/jguer/yay/tree/next/pkg/sync/build): `pkg/sync/build`
- [PKGBUILD review](https://github.com/jguer/yay/blob/next/pkg/menus/diff_menu.go): `pkg/menus/diff_menu.go`

### System Operations

- [Development tracking](https://github.com/jguer/yay/blob/next/pkg/vcs/vcs.go): `pkg/vcs/vcs.go`
- [AUR completions](https://github.com/jguer/yay/blob/next/pkg/completion/completion.go): `pkg/completion/completion.go`
- [Package voting](https://github.com/jguer/yay/blob/next/vote.go): `vote.go`
- [Package queries](https://github.com/jguer/yay/blob/next/query.go): `query.go`
- [Package cleanup](https://github.com/jguer/yay/blob/next/clean.go): `clean.go`
- [Lua customization](https://github.com/jguer/yay/tree/next/pkg/settings/lua): `pkg/settings/lua`

### Other components

- **CLI user**

## Connections

- CLI user → CLI entry: invokes (evidence: `main.go`)
- CLI entry → Configuration: loads (evidence: `main.go`)
- CLI entry → Argument parsing: parses options (evidence: `main.go`)
- CLI entry → Runtime services: creates (evidence: `main.go`)
- CLI entry → Package database: opens database (evidence: `main.go`)
- CLI entry → Command dispatch: dispatches
- Runtime services → Package search: creates (evidence: `pkg/runtime/runtime.go`)
- Runtime services → Development tracking: creates (evidence: `pkg/runtime/runtime.go`)
- Package search → AUR service: searches (evidence: `pkg/query/query_builder.go`)
- Package search → Package database: queries packages (evidence: `pkg/query/query_builder.go`)
- Dependency solver → Package database: resolves against (evidence: `pkg/dep/dep_graph.go`)
- Dependency solver → AUR service: retrieves package data
- PKGBUILD retrieval → AUR service: fetches package data (evidence: `pkg/download/unified.go`)
- PKGBUILD retrieval → Package database: selects package source (evidence: `pkg/download/unified.go`)
- Upgrade service → AUR service: checks updates (evidence: `pkg/upgrade/service.go`)
- Upgrade service → Dependency solver: uses dependency graph
- Sync operation → Build preparation: prepares builds (evidence: `pkg/sync/sync.go`)
- Sync operation → Source metadata: checks source metadata (evidence: `pkg/sync/sync.go`)
- Sync operation → Package installer: installs packages (evidence: `pkg/sync/sync.go`)
- Sync operation → AUR completions: updates completions (evidence: `pkg/sync/sync.go`)
- Sync operation → Lua customization: runs post-install hooks (evidence: `pkg/sync/sync.go`)
- Build preparation → PKGBUILD retrieval: retrieves build sources
- Source metadata → Development tracking: updates development records (evidence: `pkg/sync/srcinfo/service.go`)
- PKGBUILD review → CLI user: requests review (evidence: `pkg/menus/diff_menu.go`)
- Upgrade service → Package database: checks repository updates
- Command dispatch → Package queries: routes queries
- CLI user → Package queries: requests package query (evidence: `README.md`)
- CLI user → Package voting: votes packages (evidence: `README.md`)
- CLI user → Package cleanup: cleans dependencies (evidence: `README.md`)
- CLI user → AUR completions: requests completions (evidence: `README.md`)
- CLI user → Upgrade service: requests upgrades (evidence: `README.md`)
- CLI user → Sync operation: requests package install (evidence: `README.md`)
