Legacy Archival

Confiance : high

legacy-archivalcode-maintenancetechnical-debtsystem-migrationknowledge-preservationcodebase-simplificationhistorical-contextsuccessor-optimization

Software maintenance practice of moving outdated or superseded code into archive directories rather than deleting it, preserving institutional knowledge while reducing cognitive load on current developers.

Core Philosophy

Legacy archival balances knowledge preservation with cognitive simplification, ensuring historical context remains accessible while preventing it from interfering with current development workflows.

Implementation Strategy

Archive Structure

src/
├── current_modules/          # Active development code
├── _archive/                 # Archived legacy code
│   ├── rag_v1/              # Historical version 1
│   ├── rag_v2/              # Historical version 2  
│   ├── rag_v3/              # Historical version 3
│   └── migration_notes.md   # Context for archival decisions

Archival Criteria

Superseded functionality replaced by newer implementations
Complex dependencies that hinder maintainability
Experimental code that didn't reach production
Multiple versions where only one is actively maintained

Preservation Guidelines

Complete modules archived together to maintain functionality context
Documentation included explaining archival rationale and timing
Import paths updated to prevent accidental usage
Git history preserved maintaining full development context

Benefits

Cognitive Load Reduction

Developers focus on current, relevant code without navigating historical complexity or deprecated patterns.

Knowledge Preservation

Historical implementations remain accessible for reference, debugging legacy issues, or understanding architectural evolution.

Clean Development Environment

Current codebase presents coherent, intentional structure rather than accumulated technical debt.

Onboarding Acceleration

New developers encounter streamlined, purposeful code structure rather than archaeological layers of historical decisions.

Implementation Phases

Phase 1: Dependency Analysis

Map all imports and references to identify what code depends on legacy modules before archival.

Phase 2: Migration Planning

Create replacement implementations or update dependent code to eliminate legacy dependencies.

Phase 3: Archival Execution

Move legacy code to _archive/ directories
Update import paths in remaining code
Add documentation explaining archival decisions
Verify no broken references remain

Phase 4: Validation

Test complete system functionality to ensure archival didn't break current operations.

Anti-Patterns

Premature Archival

Moving code to archive before ensuring all dependencies are properly migrated or replaced.

Deletion Instead of Archival

Permanently removing code that contains valuable context or could be needed for debugging legacy issues.

Incomplete Documentation

Archiving without explaining why code was archived or what replaced it, losing institutional knowledge.

Import Path Confusion

Failing to update all references, leading to broken imports or accidental usage of archived code.

Integration with Handover Process

Legacy archival serves as critical component of handover-process and production-handover:

Successor Optimization

Archived legacy code doesn't confuse new developers trying to understand current system architecture.

Historical Context

Previous implementations remain available for understanding architectural decisions and evolution.

Clean Starting Point

New developers begin with intentional, current codebase rather than accumulated historical complexity.

Case Study: Assistant-RH Migration

The assistant-rh project demonstrates comprehensive legacy archival:

Multiple Version Consolidation:

src/rag/, src/rag_v2/, src/rag_v3/ → src/_archive/
Single src/rag_v3_clean/ becomes current implementation
53% total code reduction through consolidation and archival

Dependency Migration:

All current pages and UI updated to use rag_v3_clean only
Legacy imports completely eliminated from production code
Archived code remains accessible for historical reference

Documentation Strategy:

Migration notes explaining archival decisions
Technical report covering evolution from v1 → v3_clean
Clear boundaries between current and historical implementations

The approach enabled radical simplification while preserving institutional knowledge, optimizing for successor engineer success.