Archive Directory Filtering Implementation

Session 3.1: Configure docs-angular to ignore Archive directories in all scanning operations

Date: January 8, 2026
Status: ✅ Complete
Confidence: 98%
MCP Decision ID: dev_1767879511624_ki7u9zy

🎯 Objective

Improve the NX docs-angular app by ensuring all directories/folders named "Archive", "archive", "Archived", or "archived" are completely ignored by the documentation scanning system.

📊 Impact

Quantitative Results

Qualitative Improvements

• ✅ Cleaner navigation (no archived content in sidebar)
• ✅ Faster scan performance (25% fewer files)
• ✅ Reduced manifest size (smaller JSON files)
• ✅ Better search results (only active documentation)
• ✅ Consistent with existing patterns (.hidden, node_modules)

🔧 Technical Implementation

Modified Files

1. scan-docs-structure.js

Location: Lines 97-105
Change: Added archive directory filtering in main scan loop

if (entry.isDirectory()) {
  // Skip hidden directories, node_modules, and archive folders
  const lowerName = entry.name.toLowerCase();
  if (entry.name.startsWith('.') || 
      entry.name === 'node_modules' || 
      lowerName === 'archive' || 
      lowerName === 'archived') {
    continue;
  }
  // ... continue with directory processing
}

2. scan-folders-config.js

Location: Lines 208-215
Change: Added archive filtering in child recursion

// Recurse children (directories only)
for (const entry of entries) {
  if (!entry.isDirectory()) continue;
  if (entry.name.startsWith('.')) continue;
  // Skip archive folders
  const lowerName = entry.name.toLowerCase();
  if (lowerName === 'archive' || lowerName === 'archived') continue;
  // ... process child directory
}

3. scan-docs-visibility.js

Location: Lines 62-68
Change: Added archive filtering in project folder scan

for (const entry of entries) {
  if (!entry.isDirectory()) continue;
  // Skip archive folders
  const lowerName = entry.name.toLowerCase();
  if (lowerName === 'archive' || lowerName === 'archived') continue;
  // ... process project folder
}

🧠 Design Rationale

Why Ignore at Scan Level?

Chosen Approach: Ignore archive directories during file system scanning

Alternatives Considered:

1. Include but filter in UI ❌

   • Cons: Increases manifest size, slower scans, UI complexity

2. Make configurable ❌

   • Cons: Over-engineering, maintenance overhead

3. Process with special tags ❌

   • Cons: Performance impact, unnecessary complexity

4. Ignore at scan level ✅

   • Pros: Simple, fast, consistent with existing patterns
   • Follows same pattern as .hidden and node_modules

Case-Insensitive Matching

Implementation: entry.name.toLowerCase()

Rationale:

• Documentation uses various casing: archive/, Archive/, archived/
• User explicitly requested all variations
• Negligible performance overhead
• Future-proof against naming inconsistencies

✅ Testing & Verification

Test Execution

# Test 1: Structure Scanner
node apps/docs-angular/scripts/scan-docs-structure.js
✅ Files: 2278 → 1694 (-584)
✅ Directories: 375 → 313 (-62)

# Test 2: Folders Config Scanner
node apps/docs-angular/scripts/scan-folders-config.js
✅ Updated without archive folders

# Test 3: Visibility Scanner
node apps/docs-angular/scripts/scan-docs-visibility.js
✅ Config updated without archived projects

Verification Points

• All three scan scripts updated
• Case-insensitive matching works
• Significant reduction in scanned items
• No breaking changes to manifest structure
• Auto-generated files updated correctly
• Documentation scans successfully
• MCP decision logged

📚 Context & Documentation Research

Archive Usage in Codebase

Found multiple archive directories in active use:

docs/english/GoGrab-Space/libs/libs-foundational/storage-system/
├── archive/
│   └── 2025/
│       ├── implementation-history/
│       ├── firebase-implementation/
│       └── completed-consolidation/

Archive Purpose

From existing documentation:

• Contains completed feature documentation
• Provides historical context for future reference
• Organized by year (e.g., archive/2025/)
• Not meant for active navigation or search
• Includes README files explaining why content was archived

🎓 Key Learnings

1. Pattern Consistency: Following existing patterns (.hidden, node_modules) made implementation intuitive
2. All Scanners Matter: Must update all three scan scripts for complete coverage
3. Case Sensitivity: Real-world usage varies; case-insensitive is essential
4. Significant Impact: 584 files is substantial (25.6% reduction)
5. Documentation First: Researching existing docs revealed clear archive patterns
6. MCP Value: Logging decisions helps future agents understand context

📋 Implementation Checklist

• Research documentation system architecture
• Analyze existing archive directory usage
• Update scan-docs-structure.js
• Update scan-folders-config.js
• Update scan-docs-visibility.js
• Implement case-insensitive matching
• Test all three scan scripts
• Verify file count reduction
• Check manifest generation
• Log decision to MCP system
• Create session documentation
• Update session tracking

🔗 Related Resources

Documentation Files

• Docs Angular Overview
• Add Documentation Guide
• Configurable Docs System

Code Files

• apps/docs-angular/scripts/scan-docs-structure.js
• apps/docs-angular/scripts/scan-folders-config.js
• apps/docs-angular/scripts/scan-docs-visibility.js

Generated Files

• apps/docs-angular/src/assets/docs-manifest.json
• apps/docs-angular/src/assets/docs-folders-config.json
• apps/docs-angular/src/assets/docs-config.json

🚀 Future Considerations

Potential Enhancements

• Document archive directory conventions in style guide
• Monitor for additional naming patterns
• Consider archive year rotation policies

No Action Required

✅ Implementation is complete, tested, and production-ready

Session: 3.1
Workspace: editor2
Platform: cursor
Agent: cursor-architecture-agent
Confidence: 98%
MCP Decision: dev_1767879511624_ki7u9zy