Use Case: Large Directory Transfer

Scenario

Transfer a large directory with mixed file sizes (e.g., software development environment with source code, dependencies, build artifacts) across an air-gap.

Use Case: Large Directory Transfer UC-TRANSFER-002

status: approved

tags: transfer, workflow, directory, tar

release: v1.0

specifies: FR-TRANSFER-001, FR-TRANSFER-004, FR-TRANSFER-009, FR-TRANSFER-011, FR-TRANSFER-012, FR-TRANSFER-015, FR-TRANSFER-034

Transfer large directory with mixed file sizes (40GB, 50,000 files) across air-gap preserving structure and permissions.

Pack: Archive directory to tar format, split into chunks sized for USB capacity (32GB + 8GB), preserve directory structure and file permissions.

Transfer: Transport USB drives across air-gap with optional chain of custody verification.

Unpack: Verify chunk checksums, extract in order preserving structure, verify final directory integrity and file count.

Acceptance Criteria: All files present, directory structure preserved, file permissions maintained, all checksums verified, process takes < 30 minutes.

Prerequisites

Source machine: Development machine with internet
Destination machine: air-gapped production system
Transfer media: Two 32GB USB drives
Directory: ~/project/ (40GB, 50,000 files)

Workflow Steps

Phase 1: Pack on Source Machine

Preview operation

airgap-transfer pack ~/project/ /media/usb-drive --dry-run
Shows: 2 chunks needed (32GB + 8GB)

Execute pack

airgap-transfer pack ~/project/ /media/usb-drive --verbose
Preserves directory structure in tar format

Writes chunk_000.tar (32GB) to USB #1

Progress: “15,000 files packed (30%)”

Swap to USB #2

Tool prompts for USB swap

Writes chunk_001.tar (8GB) to USB #2

Manifest written to both USBs

Phase 2: Physical Transfer

Transport USB drives across air-gap
Verify physical chain of custody if required

Phase 3: Unpack on Destination Machine

Verify chunks

airgap-transfer list /media/usb-1
airgap-transfer list /media/usb-2
Confirms both chunks present with valid checksums

Unpack to destination

airgap-transfer unpack /media/usb-drives ~/restored-project/
Verifies all chunk checksums

Extracts in order, preserving structure

Progress: “35,000 files extracted (70%)”

Final verification of directory structure

Verify integrity

cd ~/restored-project
find . -type f | wc -l  # Should match source count

Acceptance Criteria

✅ All 50,000 files present
✅ Directory structure preserved
✅ File permissions maintained
✅ All checksums verified
✅ Process takes < 30 minutes

Optimization Notes

Factor	Impact	Mitigation
Many small files	Slower tar creation	Use compression in post-MVP
Mixed file sizes	Uneven chunk utilization	Acceptable for MVP
Symlinks	May break if absolute paths	Document limitation, fix post-MVP

Error Scenarios

Error	Cause	Recovery
“Permission denied”	Insufficient permissions	Run with appropriate user
“Disk full on unpack”	Insufficient destination space	Free space, resume
“Partial directory”	Interrupted pack	Resume from manifest

Linked Requirements

ID	Title	Status	Release	Verified By
FR-TRANSFER-001	Split Files into Chunks	approved	v1.0	TC-PCK-001; TC-PCK-002
FR-TRANSFER-004	Create Manifest File	approved	v1.0	TC-PCK-005
FR-TRANSFER-009	Reconstruct Files from Chunks	approved	v1.0	TC-UNP-001
FR-TRANSFER-011	Place Files in Destination	approved	v1.0	TC-UNP-003
FR-TRANSFER-012	Validate Chunk Completeness	approved	v1.0	TC-UNP-004
FR-TRANSFER-015	Show Unpack Progress	approved	v1.0	TC-UNP-007
FR-TRANSFER-034	Verbose Flag	approved	v1.0	TC-TRANSFER-CLI-007

Traceability

Tests

Integration Tests

No needs passed the filters

Unit Tests of Linked Requirements

ID	Title	Status
TC-PCK-001	Pack Single File into Chunks	approved
TC-PCK-002	Pack Directory into Chunks	approved
TC-PCK-005	Create Manifest File	approved
TC-TRANSFER-CLI-007	Verbose Flag	approved
TC-UNP-001	Reconstruct Files from Chunks	approved
TC-UNP-003	Place Files in Destination	approved
TC-UNP-004	Validate Chunk Completeness	approved
TC-UNP-007	Unpack Progress Display	approved