Architecture Overview

Architecture Overview

Prev: Architecture | Up: Architecture | Next: Execution Flow

This page answers three practical questions:

1. What main subsystems exist?
2. Where do they live in the repository?
3. How do they depend on each other?

Main Runtime Layers

CLI / main
  -> config loading and CLI overrides
  -> registry bootstrap and plugin discovery
  -> request resolution and proxy expansion
  -> planning and dependency graph
  -> validation / audit / SBOM preparation
  -> execution through plugins
  -> output rendering / remote transport

Major Components

CLI and entrypoint

• src/main/cpp/main.cpp
• src/main/cpp/cli/cli.cpp

Responsibilities:

• parse commands,
• load defaults and config.lua,
• apply CLI overrides,
• select display mode,
• route to normal orchestration, remote server mode, or remote client mode.

Configuration

• src/main/include/core/config/configuration.h
• src/main/cpp/core/config/configuration.cpp

Responsibilities:

• define the full config model,
• load Lua config,
• derive default XDG paths,
• merge CLI overrides,
• expose helpers such as repository lists and proxy settings.

Registry and plugin database

• src/main/include/core/registry/registry.h
• src/main/cpp/core/registry/registry.cpp
• src/main/include/core/registry/registry_database.h
• src/main/cpp/core/registry/registry_database.cpp
• src/main/cpp/core/registry/registry_json_parser.cpp

Responsibilities:

• keep track of known plugins,
• resolve aliases,
• refresh plugin records from registry sources,
• materialize Lua plugin scripts or bundles into the plugin directory,
• validate trust metadata and script hashes.

Plugins

• Lua runtime bridge: src/main/cpp/plugins/lua_bridge.cpp
• plugin interface: src/main/include/plugins/iplugin.h
• built-in native plugin: src/main/cpp/plugins/rq_plugin.cpp
• local Lua examples: plugins/*

Responsibilities:

• package-manager-specific logic,
• local file handling,
• search/list/info/update behavior,
• optional package resolution,
• optional proxy resolution,
• security metadata.

Today only native built-in plugin is rqp. Registry-discovered and workspace plugins are Lua-based and run through LuaBridge.

Planner and request resolution

• src/main/cpp/core/planning/planner.cpp
• src/main/cpp/core/planning/planner_core.cpp
• src/main/cpp/core/planning/request_resolution.cpp

Responsibilities:

• expand aliases and proxies,
• ensure plugins are available,
• include plugin dependencies when required,
• build the package dependency graph.

Validator and security services

• src/main/cpp/core/security/validator.cpp
• src/main/cpp/core/security/vulnerability_sync_service.cpp
• src/main/cpp/core/export/audit_exporter.cpp
• src/main/cpp/core/export/sbom_exporter.cpp

Responsibilities:

• audit graphs for vulnerabilities,
• sync OSV data,
• enforce security policies,
• export audit and SBOM outputs.

Executor

• src/main/cpp/core/execution/executor.cpp

Responsibilities:

• execute planned actions,
• build plugin call contexts,
• dispatch graph nodes to plugins,
• track history and installed-state ownership,
• refresh system state where needed.

Orchestrator

• src/main/cpp/core/execution/orchestrator.cpp

Responsibilities:

• glue everything together,
• choose special fast paths for list/search/info/outdated/snapshot/audit/sbom,
• preprocess URLs and local archive targets,
• run planner -> validator -> executor pipeline for mutating flows.

Remote runtime

• src/main/cpp/core/remote/serve_remote.cpp
• src/main/cpp/core/remote/remote_client.cpp
• src/main/cpp/core/remote/remote_profiles.cpp

Responsibilities:

• run rqp commands over TCP,
• support text and JSON client modes,
• handle auth, readonly mode, upload installs, and admin operations.

Repository Layout Cheat Sheet

Path	Purpose
src/main/cpp/main.cpp	app startup and runtime mode selection
src/main/cpp/cli/cli.cpp	command parsing and help text
src/main/cpp/core/config/configuration.cpp	config loading, defaults, overrides
src/main/cpp/core/registry/*.cpp	registry database, refresh, trust, parsing
src/main/cpp/core/planning/*.cpp	graph planning and dependency logic
src/main/cpp/core/planning/request_resolution.cpp	proxy resolution and alias-aware request rewriting
src/main/cpp/core/execution/executor.cpp	action dispatch and runtime execution
src/main/cpp/core/execution/orchestrator.cpp	top-level workflow coordination
src/main/cpp/plugins/lua_bridge.cpp	Lua plugin runtime bridge
src/main/cpp/plugins/rq_plugin.cpp	built-in native rqp package manager
plugins/	local Lua plugin sources
tests/	behavioral and regression coverage

Related Pages

• Execution Flow
• Data, State, and Trust

Prev: Architecture | Up: Architecture | Next: Execution Flow