# What Is the Staging Directory in Archify’s Delivery Process?

> Discover the staging directory in Archify's delivery process. Learn how this private folder isolates artifacts, enables atomic commits, and ensures crash-resilient deliveries for tt-a1i/archify.

- Repository: [tt-a1i/archify](https://github.com/tt-a1i/archify)
- Tags: deep-dive
- Published: 2026-09-05

---

**Archify’s delivery pipeline creates a private, same-directory staging folder to isolate candidate artifacts, enable atomic commits, and ensure crash-resilient deliveries.**

The **staging directory** is a core mechanism in the `tt-a1i/archify` CLI that guarantees safe, deterministic output generation. Each time you run a `deliver` command, the tool creates a temporary workspace—named `*.archify-delivery-*`—to hold candidate files before committing them to the final destination. This design ensures that your existing artifacts remain untouched until every validation gate passes, as documented in the project’s architectural roadmap at [`ROADMAP.md`](https://github.com/tt-a1i/archify/blob/main/ROADMAP.md) (line 22).

## Core Functions of the Staging Directory

### Isolation and Safety

The staging directory provides a **sandboxed workspace** where all intermediate files live during the delivery pipeline. If any step—render, validate, composition, or receipt verification—fails, Archify simply discards the temporary folder. Your existing output file remains intact, preventing partial or corrupted updates.

### Atomic Commit Guarantees

Only after **all deterministic gates pass** does Archify perform an atomic move from the staging area to the final destination. This ensures that the output is either completely new or completely unchanged, eliminating the risk of users encountering half-written files during a crash.

### Concurrency and Deterministic Naming

Because Archify creates the staging folder using `fs.mkdtempSync` with a unique temporary suffix (`*.archify-delivery-*`), concurrent deliveries cannot clash. Each process writes to its own isolated path, ensuring that parallel runs never alias or corrupt intermediate files.

## Implementation in the Archify Source Code

According to the `archify/bin/archify.mjs` implementation, the staging directory lifecycle follows three distinct phases.

### Creation with mkdtempSync

At line 850, the CLI initializes the staging path:

```javascript
stagingDirectory = fs.mkdtempSync(path.join(outputDirectory, '.archify-delivery-'));

```

This generates a **private, same-directory folder** with a cryptographically random suffix, placing it adjacent to the target output for efficient atomic moves.

### Storing Candidate Artifacts

Between lines 870–872, the pipeline assembles candidate files inside the staging area:

```javascript
const candidatePath = path.join(stagingDirectory, path.basename(outputPath));

```

This holds the rendered HTML, generated receipt, specification snapshots, and any auxiliary files while validation runs.

### Cleanup and Error Handling

At line 1118, after a successful delivery, Archify attempts recursive removal:

```javascript
console.error(`Warning: could not remove delivery staging directory "${stagingDirectory}": ${error.message}`);

```

If `fs.rmSync` fails to remove the staging directory, the CLI emits a **non-fatal warning** rather than crashing. This preserves diagnostic access to the temporary files without corrupting the delivered artifact.

## Delivery Workflow Example

As defined in [`archify/references/delivery-contract.md`](https://github.com/tt-a1i/archify/blob/main/archify/references/delivery-contract.md), the following command triggers the staging workflow:

```bash
node bin/archify.mjs deliver architecture examples/web-app.architecture.json \
    /tmp/web-app.html --quality showcase --json

```

Inside the CLI, the workflow follows this deterministic sequence:

```javascript
// Phase 1: Initialize isolated workspace
const stagingDirectory = fs.mkdtempSync(
  path.join(outputDirectory, '.archify-delivery-')
);

// Phase 2: Generate and validate candidates
const candidatePath = path.join(stagingDirectory, path.basename(outputPath));
// ... render HTML, validate schema, compute receipt ...

// Phase 3: Atomic commit or graceful discard
if (allChecksPass) {
  fs.renameSync(candidatePath, outputPath);   // Atomic move
} else {
  fs.rmSync(stagingDirectory, {recursive:true, force:true});
  // Existing output remains untouched
}

// Phase 4: Cleanup
fs.rmSync(stagingDirectory, {recursive:true, force:true});

```

When validation fails, the staging directory is removed without touching the destination file, maintaining **side-effect-free** operation.

## Summary

- **Isolation**: The staging directory acts as a sandbox for candidate artifacts, ensuring failed deliveries never corrupt existing outputs.
- **Atomicity**: Verified candidates move to the final destination only after all checks pass, guaranteeing all-or-nothing updates.
- **Concurrency**: Unique temporary naming via `fs.mkdtempSync` prevents clashes between simultaneous delivery processes.
- **Resilience**: Non-fatal cleanup warnings preserve diagnostic capabilities without breaking the delivery contract.

## Frequently Asked Questions

### Where is the staging directory created?

The staging directory is created in the **same directory as the target output file** using `fs.mkdtempSync` with the prefix `.archify-delivery-`. This co-location enables atomic `rename` operations and keeps temporary files close to their final destination for optimal I/O performance.

### What happens if a delivery fails?

If any validation step fails—such as schema validation or receipt mismatch—the CLI discards the staging directory via `fs.rmSync` without moving files to the output path. Your existing artifact remains completely untouched, and the process exits with an error code.

### Is the staging directory removed automatically?

Yes. Upon successful delivery, Archify attempts to recursively remove the staging directory using `fs.rmSync` with `force: true`. If removal fails (e.g., due to permission issues), the CLI emits a warning message but considers the delivery successful, allowing you to inspect the leftover files without blocking your pipeline.

### Can multiple deliveries run simultaneously?

Yes. Because each staging directory receives a unique cryptographically random suffix from `fs.mkdtempSync`, concurrent `deliver` commands cannot interfere with one another. Each process writes to its own isolated `*.archify-delivery-*` folder, making the pipeline safe for parallel execution.