Architecture Overview

Relevant source files

The following files were used as context for generating this wiki page:

• apps/api/app.py
• core/stage_runner.py
• services/graph/graph.py
• cli/aldecI.py
• tools/docgen/api_cli_map.py
• artifacts/upstream_doc_index.json

Aldeci is a contextual risk and evidence platform designed to process security artifacts through a configurable pipeline. The system exposes its functionality through two primary interfaces: a command-line interface (CLI) and a FastAPI-based web service. Both interfaces act as entry points to a common core processing engine that executes a series of defined stages, transforming raw inputs like SBOMs and SARIF files into contextualized risk assessments, compliance evidence, and automation manifests.

The architecture is modular, with distinct services for handling specific concerns such as provenance, risk scoring, and graph analytics. Configuration is managed through an overlay system, allowing the platform's behavior to be adapted for different environments (e.g., demo vs. enterprise) without code changes. This design ensures parity between local CLI execution and remote API-driven workflows, making it suitable for both CI/CD automation and interactive analysis.

Sources: artifacts/upstream_doc_index.json

Core Components

The Aldeci platform is built around a few key components that manage user interaction, data processing, and state.

Entrypoints: CLI and API

Users interact with Aldeci through either the CLI or the FastAPI application. Both are thin wrappers that delegate processing to the core StageRunner.

• FastAPI Application: The main web service entry point, defined in apps/api/app.py. The create_app function initializes the FastAPI instance and wires up the various API routers for services like provenance, risk, graph, and evidence.
• Command-Line Interface (CLI): A Typer-based application, with its command structure defined in cli/aldecI.py. It provides commands that map directly to the system's capabilities, offering parity with the API for local and air-gapped environments.

Sources: apps/api/app.py:20-23, cli/aldecI.py, tools/docgen/api_cli_map.py:27-29

The following diagram illustrates the high-level component interaction.

Staged Pipeline Execution

The central architectural pattern in Aldeci is the staged pipeline, orchestrated by the StageRunner class. This component is responsible for executing discrete processing stages in a defined order, where the output of one stage can serve as the input for subsequent stages.

Sources: core/stage_runner.py:65-67

The StageRunner Class

The StageRunner coordinates the canonical input/output handling for each stage. Its primary method, run_stage, takes a stage name and input path, resolves the application and run identity, and invokes the corresponding _process_<stage> method to perform the actual work.

Key responsibilities include:

• Resolving application and run IDs.
• Saving input files to a structured run directory.
• Executing the specific processing logic for the given stage.
• Writing canonical output files.
• Handling artifact signing and verification.
• Generating a final StageSummary object.

Sources: core/stage_runner.py:102-168

Pipeline Stages

The pipeline consists of several predefined stages, each with a specific input artifact and a corresponding output.

Stage	Input Filename	Output Filename	Description
requirements	requirements-input.csv	requirements.json	Parses requirements and applies SSVC anchoring.
design	design-input.json	design.manifest.json	Processes design context, allocates IDs, and calculates a design risk score.
build	sbom.json	build.report.json	Normalizes an SBOM and flags risky components based on predefined rules.
test	scanner.sarif	test.report.json	Ingests SARIF reports, summarizes finding severities, and calculates drift and coverage.
deploy	tfplan.json	deploy.manifest.json	Analyzes infrastructure-as-code plans for posture issues like public S3 buckets.
operate	ops-telemetry.json	operate.snapshot.json	Blends telemetry with KEV/EPSS feeds to compute operational risk pressure.
decision	decision-input.json	decision.json	Synthesizes all prior stage outputs into a final verdict and bundles evidence.

Sources: core/stage_runner.py:70-87

The following flowchart shows the data flow through the StageRunner.

API and CLI Interaction Model

Aldeci provides a unified interaction model where both the CLI and API map to a common set of underlying capabilities defined in an execution registry. This ensures consistent behavior regardless of the entry point. The tools/docgen/api_cli_map.py script and the EXECUTION_REGISTRY it contains serve as the source of truth for this mapping.

Sources: tools/docgen/api_cli_map.py:24-25

Capability Mapping

The EXECUTION_REGISTRY maps high-level capabilities to their respective CLI commands, API endpoints, and backend services.

Capability	CLI Command	API Route	Backend Service(s)
stage.run	aldecI stage run	POST /v1/stage/run	core.stage_runner
ingest.sbom	aldecI ingest sbom	POST /v1/ingest/sbom	lib4sbom.normalizer
risk.score	aldecI risk score	POST /v1/risk/score	risk.scoring
provenance.attest	aldecI provenance attest	POST /v1/provenance/attest	services.provenance.attestation
graph.lineage	aldecI graph lineage	GET /v1/graph/lineage	services.graph.graph
evidence.bundle	aldecI evidence bundle	GET /v1/evidence/bundle/{run_id}	evidence.packager

Sources: tools/docgen/api_cli_map.py:24-25, 128-154

Interaction Flow

The sequence diagram below illustrates a typical interaction flow, starting from a CLI command, which can either be handled by a local backend or be proxied through the SDK to the remote FastAPI server.

Sources: tools/docgen/api_cli_map.py:31-48, 230-280

Services

Aldeci's architecture includes several backend services that encapsulate specific business logic. These are invoked by the core pipeline or exposed directly via API endpoints.

Provenance Graph Service

The provenance graph service is responsible for linking various entities within the software supply chain. Although the implementation in services/graph/graph.py is minimal in the provided source, documentation indicates its role is to build a queryable knowledge graph (backed by SQLite and NetworkX) that connects commits, CI jobs, artifacts, SBOM components, and CVEs. This enables queries for lineage, KEV exposure, and downgrade anomalies.

Sources: services/graph/graph.py, artifacts/upstream_doc_index.json