# mclucy/lucy architecture

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

- Interactive diagram: https://gitdiagram.com/mclucy/lucy
- Repository: https://github.com/mclucy/lucy

## Overview

Lucy is a Minecraft server package manager. Its principal workflow is to initialize a project, add package requests, resolve package dependencies, persist a lockfile, and install the locked artifacts into a server workspace. It also supports deterministic reinstall, workspace/runtime inspection, dependency-tree and orphan views, crash bisection, and multi-source search. The tree and README establish these product areas; sampled source confirms project state I/O, provider routing/execution, cache behavior, and search rendering, but not every command’s internal wiring.

Main entry points: [`main.go`](https://github.com/mclucy/lucy/blob/main/main.go) (Lucy CLI), [`state/service.go`](https://github.com/mclucy/lucy/blob/main/state/service.go) (Project state service), [`install/install.go`](https://github.com/mclucy/lucy/blob/main/install/install.go) (Install engine), [`internal/cli/add/add.go`](https://github.com/mclucy/lucy/blob/main/internal/cli/add/add.go) (Add packages)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_commands["CLI workflows"]
  node_cli["Lucy CLI<br/>[main.go]"]
  node_init["Initialize project<br/>[init_flow.go]"]
  node_add["Add packages<br/>[add.go]"]
  node_remove["Remove packages<br/>[cmd_remove.go]"]
  node_search["Search packages<br/>[search.go]"]
  node_inspect["Inspect workspace<br/>[status.go]"]
  node_tree["Dependency views<br/>[cmd_tree.go]"]
  node_leaves["Unused packages<br/>[cmd_leaves.go]"]
  node_bisect["Crash bisection<br/>[bisect.go]"]
end

subgraph group_resolution["Package discovery"]
  node_solver["Dependency resolver<br/>[solver.go]"]
  node_routing["Provider routing<br/>[routing.go]"]
  node_providers["Package providers"]
  node_github["GitHub source<br/>[gh.go]"]
end

subgraph group_installation["Install and runtime"]
  node_workspace["Server workspace<br/>[workspace.go]"]
  node_installcli["Install command<br/>[install.go]"]
  node_installer["Install engine<br/>[install.go]"]
  node_bootstrap["Server bootstrap<br/>[bootstrap.go]"]
  node_artifact["Artifact metadata<br/>[artifact.go]"]
  node_cache[("Artifact cache<br/>[cache.go]")]
  node_detector["Runtime detection<br/>[detector.go]"]
end

subgraph group_project["Project state"]
  node_state["Project state service<br/>[service.go]"]
  node_manifest["Manifest and lock<br/>[manifest.go]"]
end

node_operator(("Server operator"))
node_registries(("Package registries"))

node_operator -->|"runs commands"| node_cli
node_cli -->|"dispatches"| node_init
node_cli -->|"dispatches"| node_add
node_cli -->|"dispatches"| node_remove
node_cli -->|"dispatches"| node_search
node_cli -->|"dispatches"| node_inspect
node_cli -->|"dispatches"| node_tree
node_cli -->|"dispatches"| node_leaves
node_cli -->|"dispatches"| node_bisect
node_init -->|"scaffolds state"| node_state
node_add -->|"resolves requests"| node_solver
node_solver -->|"selects providers"| node_routing
node_routing -->|"routes requests"| node_providers
node_providers -->|"queries metadata"| node_registries
node_search -->|"selects providers"| node_routing
node_search -->|"searches packages"| node_providers
node_add -->|"updates project state"| node_state
node_remove -->|"updates project state"| node_state
node_state -->|"reads and writes"| node_manifest
node_add -->|"installs packages"| node_installcli
node_installcli -->|"starts sync"| node_installer
node_installer -->|"reads lockfile"| node_state
node_installer -->|"syncs files"| node_workspace
node_installer -->|"handles artifacts"| node_artifact
node_installer -->|"uses cache"| node_cache
node_installer -->|"installs server core"| node_bootstrap
node_inspect -->|"probes runtime"| node_workspace
node_workspace -->|"detects platform"| node_detector
node_tree -->|"reads dependencies"| node_state
node_leaves -->|"reads dependencies"| node_state
node_bisect -->|"examines installation"| node_workspace
node_providers -.->|"uses source"| node_github

click node_cli "https://github.com/mclucy/lucy/blob/main/main.go"
click node_init "https://github.com/mclucy/lucy/blob/main/internal/cli/init/init_flow.go"
click node_add "https://github.com/mclucy/lucy/blob/main/internal/cli/add/add.go"
click node_remove "https://github.com/mclucy/lucy/blob/main/cmd/cmd_remove.go"
click node_search "https://github.com/mclucy/lucy/blob/main/internal/cli/search/search.go"
click node_inspect "https://github.com/mclucy/lucy/blob/main/internal/cli/status/status.go"
click node_tree "https://github.com/mclucy/lucy/blob/main/cmd/cmd_tree.go"
click node_leaves "https://github.com/mclucy/lucy/blob/main/cmd/cmd_leaves.go"
click node_bisect "https://github.com/mclucy/lucy/blob/main/internal/cli/bisect/bisect.go"
click node_solver "https://github.com/mclucy/lucy/blob/main/resolve/solver.go"
click node_routing "https://github.com/mclucy/lucy/blob/main/upstream/routing/routing.go"
click node_providers "https://github.com/mclucy/lucy/tree/main/upstream/providers"
click node_state "https://github.com/mclucy/lucy/blob/main/state/service.go"
click node_manifest "https://github.com/mclucy/lucy/blob/main/state/manifest.go"
click node_workspace "https://github.com/mclucy/lucy/blob/main/workspace/workspace.go"
click node_installcli "https://github.com/mclucy/lucy/blob/main/internal/cli/install/install.go"
click node_installer "https://github.com/mclucy/lucy/blob/main/install/install.go"
click node_bootstrap "https://github.com/mclucy/lucy/blob/main/bootstrap/bootstrap.go"
click node_artifact "https://github.com/mclucy/lucy/blob/main/artifact/artifact.go"
click node_cache "https://github.com/mclucy/lucy/blob/main/cache/cache.go"
click node_detector "https://github.com/mclucy/lucy/blob/main/workspace/internal/detector/detector.go"
click node_github "https://github.com/mclucy/lucy/blob/main/github/gh.go"

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_init,node_add,node_remove,node_search,node_inspect,node_tree,node_leaves,node_bisect toneBlue
class node_solver,node_routing,node_providers,node_github toneAmber
class node_workspace,node_installcli,node_installer,node_bootstrap,node_artifact,node_cache,node_detector,node_operator toneMint
class node_state,node_manifest toneRose
class node_registries toneIndigo
```

## Components

### CLI workflows

- [Lucy CLI](https://github.com/mclucy/lucy/blob/main/main.go): `main.go`
- [Initialize project](https://github.com/mclucy/lucy/blob/main/internal/cli/init/init_flow.go): `internal/cli/init/init_flow.go`
- [Add packages](https://github.com/mclucy/lucy/blob/main/internal/cli/add/add.go): `internal/cli/add/add.go`
- [Remove packages](https://github.com/mclucy/lucy/blob/main/cmd/cmd_remove.go): `cmd/cmd_remove.go`
- [Search packages](https://github.com/mclucy/lucy/blob/main/internal/cli/search/search.go): `internal/cli/search/search.go`
- [Inspect workspace](https://github.com/mclucy/lucy/blob/main/internal/cli/status/status.go): `internal/cli/status/status.go`
- [Dependency views](https://github.com/mclucy/lucy/blob/main/cmd/cmd_tree.go): `cmd/cmd_tree.go`
- [Unused packages](https://github.com/mclucy/lucy/blob/main/cmd/cmd_leaves.go): `cmd/cmd_leaves.go`
- [Crash bisection](https://github.com/mclucy/lucy/blob/main/internal/cli/bisect/bisect.go): `internal/cli/bisect/bisect.go`

### Package discovery

- [Dependency resolver](https://github.com/mclucy/lucy/blob/main/resolve/solver.go): `resolve/solver.go`
- [Provider routing](https://github.com/mclucy/lucy/blob/main/upstream/routing/routing.go): `upstream/routing/routing.go`
- [Package providers](https://github.com/mclucy/lucy/tree/main/upstream/providers): `upstream/providers`
- [GitHub source](https://github.com/mclucy/lucy/blob/main/github/gh.go): `github/gh.go`

### Install and runtime

- [Server workspace](https://github.com/mclucy/lucy/blob/main/workspace/workspace.go): `workspace/workspace.go`
- [Install command](https://github.com/mclucy/lucy/blob/main/internal/cli/install/install.go): `internal/cli/install/install.go`
- [Install engine](https://github.com/mclucy/lucy/blob/main/install/install.go): `install/install.go`
- [Server bootstrap](https://github.com/mclucy/lucy/blob/main/bootstrap/bootstrap.go): `bootstrap/bootstrap.go`
- [Artifact metadata](https://github.com/mclucy/lucy/blob/main/artifact/artifact.go): `artifact/artifact.go`
- [Artifact cache](https://github.com/mclucy/lucy/blob/main/cache/cache.go): `cache/cache.go`
- [Runtime detection](https://github.com/mclucy/lucy/blob/main/workspace/internal/detector/detector.go): `workspace/internal/detector/detector.go`

### Project state

- [Project state service](https://github.com/mclucy/lucy/blob/main/state/service.go): `state/service.go`
- [Manifest and lock](https://github.com/mclucy/lucy/blob/main/state/manifest.go): `state/manifest.go`

### Other components

- **Server operator**
- **Package registries**

## Connections

- Server operator → Lucy CLI: runs commands
- Lucy CLI → Initialize project: dispatches
- Lucy CLI → Add packages: dispatches
- Lucy CLI → Remove packages: dispatches
- Lucy CLI → Search packages: dispatches
- Lucy CLI → Inspect workspace: dispatches
- Lucy CLI → Dependency views: dispatches
- Lucy CLI → Unused packages: dispatches
- Lucy CLI → Crash bisection: dispatches
- Initialize project → Project state service: scaffolds state
- Add packages → Dependency resolver: resolves requests
- Dependency resolver → Provider routing: selects providers
- Provider routing → Package providers: routes requests
- Package providers → Package registries: queries metadata
- Search packages → Provider routing: selects providers
- Search packages → Package providers: searches packages
- Add packages → Project state service: updates project state
- Remove packages → Project state service: updates project state
- Project state service → Manifest and lock: reads and writes
- Add packages → Install command: installs packages
- Install command → Install engine: starts sync
- Install engine → Project state service: reads lockfile
- Install engine → Server workspace: syncs files
- Install engine → Artifact metadata: handles artifacts
- Install engine → Artifact cache: uses cache
- Install engine → Server bootstrap: installs server core
- Inspect workspace → Server workspace: probes runtime
- Server workspace → Runtime detection: detects platform
- Dependency views → Project state service: reads dependencies
- Unused packages → Project state service: reads dependencies
- Crash bisection → Server workspace: examines installation
- Package providers → GitHub source: uses source