Architecture Execution Flow

Execution Flow

Prev: Architecture Overview | Up: Architecture | Next: Data, State, and Trust

This page explains what happens when a ReqPack command runs.

High-level Flow

For a normal mutating command such as install, remove, update, or ensure, the flow is:

1. load config defaults and config file
2. apply CLI overrides
3. bootstrap registry database
4. scan plugin directories
5. preprocess local URLs and archives
6. resolve aliases and proxies
7. build execution graph
8. validate graph against security policy
9. execute graph through plugins
10. update history and installed state

Step-by-step

1. CLI parse

main.cpp and cli.cpp parse command-line arguments into Request objects.

Each request contains fields such as:

• action,
• system,
• packages,
• flags,
• output format/path,
• local path state.

2. Config resolution

ReqPack builds a default config, then loads config.lua, then applies overrides.

This step also resolves:

• XDG paths,
• plugin directories,
• registry locations,
• jobs mode,
• security thresholds,
• archive password resolution.

3. Registry bootstrap and plugin scanning

Before work starts, ReqPack ensures the registry DB is ready and scans:

• configured plugin directory,
• local workspace plugins/ directory when present and different.

That is why developing Lua plugins inside the repo is straightforward. Built-in rqp plugin is already registered in process and does not come from those directories.

4. Local target preprocessing

If an install request targets a local file, directory, or URL:

• archives may be extracted to temp directories first,
• system can be inferred from plugin.fileExtensions,
• remote URLs are downloaded before plugin selection happens.

This is all handled in orchestrator.cpp before planning.

5. Request resolution

RequestResolutionService resolves:

• aliases through registry and planner aliases,
• proxy plugins through resolveProxyRequest().

Important safety rules:

• max proxy depth is limited,
• cycles are rejected,
• proxies cannot resolve to themselves,
• proxies cannot return both packages and localPath.

6. Planning

Planner turns resolved requests into a directed graph of Package nodes.

It also:

• filters already-satisfied install requests through getMissingPackages(),
• optionally downloads missing plugins,
• optionally injects plugin requirements,
• topologically sorts the graph if configured.

7. Validation and audit preparation

There are three security-relevant paths:

• audit: build graph, run validator, export findings
• sbom: build graph, export inventory
• mutating actions: validate graph first, then execute only if validation passes

Validation can block execution for reasons such as:

• vulnerability findings,
• unsupported ecosystem mapping,
• unresolved versions,
• OSV sync errors under strict policy.

8. Execution

Executor groups work by system and dispatches to plugins.

For each plugin call it builds a PluginCallContext containing:

• plugin identity and paths,
• flags,
• runtime host,
• proxy config,
• repositories,
• host info snapshot,
• current item ID for display correlation.

9. Event, output, and progress handling

Plugins emit:

• log messages,
• transaction steps,
• status and progress,
• semantic events such as installed or searched,
• artifacts.

ReqPack routes those into:

• display rendering,
• structured logs,
• remote response output,
• native package manifests in the rqp case.

10. History and installed state

After execution, ReqPack can append history events and maintain installed-state tracking.

That state is later used by:

• snapshot,
• ownership tracking,
• some restore-style workflows.

Special-case Flows

list, search, info, outdated

These skip the heavy graph execution path. Orchestrator calls executor query methods directly and renders table or field/value output.

snapshot

This bypasses plugins and exports a reqpack.lua manifest from tracked installed-state history.

update --all and wrapper refresh

ReqPack has dedicated fast paths for:

• system-wide package updates,
• plugin wrapper refresh,
• ReqPack self-update.

These are intentionally separated from standard graph execution.

Remote Flow

Remote requests eventually use the same parser and orchestrator pipeline. The remote runtime adds:

• auth,
• readonly checks,
• protocol framing,
• optional upload handling,
• admin command dispatch.

Related Pages

• Architecture Overview
• Data, State, and Trust
• Remote Mode

Prev: Architecture Overview | Up: Architecture | Next: Data, State, and Trust