Codebase Architect

This skill provides comprehensive project structure analysis and reorganization capabilities for codebases of any size and language.

Core Capabilities

• Dependency Analysis: Map import chains and cross-file relationships
• Structure Assessment: Evaluate current organization against best practices
• Dead Code Detection: Identify unused files, exports, and orphaned code
• Refactoring Planning: Generate safe migration strategies
• Pattern Recognition: Detect and apply architectural patterns

Quick Start

For immediate analysis of a project:

# Basic project analysis
python scripts/analyze_structure.py --root . --output analysis_report.json

# Generate dependency graph
python scripts/dependency_mapper.py --root src --format visual

# Detect dead code
python scripts/dead_code_detector.py --root . --exclude node_modules,dist

Analysis Workflow

Phase 1: Discovery

Start with comprehensive project analysis:

# Scan project for framework and language detection
python scripts/project_scanner.py --root . --output project_scan.json

# Analyze project structure in detail
python scripts/analyze_structure.py --root . --output analysis_report.json

This identifies:

• Framework/library conventions (React, Vue, Django, Rails, etc.)
• Build configuration files
• Test structure
• Documentation organization

Phase 2: Dependency Mapping

Map all file relationships:

python scripts/dependency_mapper.py --root . --output deps.json --detect-circular

For specific language analysis:

• JavaScript/TypeScript: Analyzes imports, requires, dynamic imports
• Python: Tracks imports, relative imports, init patterns
• Java/C#: Namespace and package dependencies
• Go: Module and package imports

Phase 3: Problem Identification

Analyze dependencies and identify issues:

# Unified issue detection (runs all checks)
python scripts/issue_detector.py --root . --output issues.json --severity all

# Or run individual checks:
python scripts/dependency_mapper.py --root . --output deps.json --detect-circular
python scripts/dead_code_detector.py --root . --exclude node_modules,dist

Common issues detected:

• Circular dependencies
• Deep nesting (>4 levels)
• Inconsistent naming patterns
• Misplaced files (utilities in components, etc.)
• God files (too many responsibilities)
• Orphaned code (no imports/exports)

Phase 4: Restructuring

Generate reorganization plan:

python scripts/restructure_planner.py --root . --pattern <pattern> --output migration_plan.json

Available patterns:

• feature-based: Group by features/domains
• mvc: Model-View-Controller separation
• clean: Clean Architecture layers
• modular: Self-contained modules
• ddd: Domain-Driven Design

Architectural Patterns

Feature-Based Structure

Best for: Frontend applications, microservices

src/
├── features/
│   ├── auth/
│   │   ├── components/
│   │   ├── hooks/
│   │   ├── services/
│   │   ├── types/
│   │   └── index.ts
│   └── dashboard/
│       ├── components/
│       ├── hooks/
│       ├── services/
│       └── index.ts
├── shared/
│   ├── components/
│   ├── utils/
│   └── types/
└── core/
    ├── api/
    ├── config/
    └── constants/

Clean Architecture

Best for: Enterprise applications, complex domains

src/
├── domain/           # Business logic
│   ├── entities/
│   ├── repositories/
│   └── use-cases/
├── application/      # Application services
│   ├── services/
│   └── dto/
├── infrastructure/   # External concerns
│   ├── database/
│   ├── api/
│   └── config/
└── presentation/     # UI layer
    ├── controllers/
    └── views/

Modular Monolith

Best for: Large applications, gradual microservices migration

src/
├── modules/
│   ├── user/
│   │   ├── api/
│   │   ├── domain/
│   │   ├── infrastructure/
│   │   └── module.ts
│   └── billing/
│       ├── api/
│       ├── domain/
│       └── module.ts
├── shared-kernel/
└── composition-root/

Advanced Features

Custom Rules Configuration

Create .codebase-architect.json in project root (see assets/example-config.json for full template):

{
  "rules": {
    "maxNestingDepth": 4,
    "enforceBarrelExports": true,
    "namingConvention": "kebab-case",
    "forbiddenDependencies": [
      {"from": "domain/*", "to": "infrastructure/*"}
    ]
  }
}

Migration Safety

Execute migrations safely with automated backups and rollback:

# Dry run to preview changes
python scripts/migrate.py --root . --plan migration_plan.json --dry-run

# Execute with automatic backup
python scripts/migrate.py --root . --plan migration_plan.json --backup

# Execute with rollback on error
python scripts/migrate.py --root . --plan migration_plan.json --rollback-on-error

Safety features:

• Automatic backups before any file operations
• Git integration with pre/post-operation commits
• Dry-run mode to preview all changes
• Rollback capability if errors occur
• Import path updates automatically handled

See Safety System section for complete safety features.

Language-Specific Features

For detailed language-specific analysis:

• JavaScript/TypeScript: See references/javascript-patterns.md
• Python: See references/python-patterns.md
• Java/Kotlin: See references/jvm-patterns.md
• Go: See references/go-patterns.md
• C#/.NET: See references/dotnet-patterns.md

Reporting

Generate comprehensive reports in HTML or Markdown:

# HTML report with visualizations
python scripts/report_generator.py \
  --format html \
  --output report \
  --structure analysis.json \
  --dependencies deps.json \
  --dead-code dead_code.json \
  --issues issues.json

# Markdown for documentation
python scripts/report_generator.py --format markdown --output ARCHITECTURE.md

# Both formats
python scripts/report_generator.py --format both --output report

Reports include:

• Structure metrics and file distribution
• Dependency graphs and coupling scores
• Dead code analysis with savings estimates
• Issue summaries by severity

Best Practices

Before Reorganizing

1. Backup everything: Use version control or create archive
2. Run tests: Ensure all tests pass before changes
3. Document current state: Generate architecture documentation
4. Communicate changes: Inform team members

During Reorganization

1. Incremental changes: Move one module at a time
2. Update imports immediately: Use automated tools
3. Run tests frequently: Catch breaks early
4. Maintain compatibility: Keep old paths with deprecation warnings

After Reorganization

1. Update documentation: README, architecture docs, onboarding
2. Update CI/CD: Build paths, test configurations
3. Team training: Share new structure and conventions
4. Monitor for issues: Watch for import errors, build failures

Safety System

⚡ NEW: Comprehensive safety features to protect against accidental deletions and enable recovery.

Safety Manager

Central safety system providing:

• Timestamped backups: Automatic .tar.gz archives before operations
• Trash system: Soft-delete to .codebase-safety/trash/ instead of permanent deletion
• Change tracking: Full audit log of all operations
• Git integration: Automatic commits before/after operations
• Rollback capability: Restore from backups or trash

# Create manual backup
python scripts/safety_manager.py --root . backup --description "Before major refactor"

# List all backups
python scripts/safety_manager.py --root . list-backups

# Restore from backup
python scripts/safety_manager.py --root . restore backup_20250102_143022.tar.gz

# Move file to trash instead of deleting
python scripts/safety_manager.py --root . trash path/to/file.ts --reason "Deprecated"

# List trash contents
python scripts/safety_manager.py --root . list-trash

# Restore from trash
python scripts/safety_manager.py --root . restore-trash 20250102_143500

# Clean up old trash (30+ days)
python scripts/safety_manager.py --root . cleanup-trash --days 30

# Create pre-operation git commit
python scripts/safety_manager.py --root . git-commit "migration to feature-based"

Safety Directory Structure

.codebase-safety/
├── backups/                    # Timestamped tar.gz archives
│   ├── backup_20250102_140000.tar.gz
│   └── backup_20250102_150000.tar.gz
├── trash/                      # Soft-deleted files
│   ├── 20250102_143000/
│   │   ├── old_file.ts
│   │   └── old_file.ts.meta.json
│   └── 20250102_144000/
├── operation_log.json          # Complete audit log
├── file_manifest.json          # File state snapshots
└── last_migration.json         # Last migration details for rollback

Best Practices

1. Always use safety features: Never skip backups for destructive operations
2. Review dry-run output: Always run --dry-run before executing migrations
3. Keep git clean: Commit all changes before major refactoring
4. Regular cleanup: Run cleanup-trash monthly to free disk space
5. Test rollback: Verify backup/restore works before production use

Scripts Reference

All scripts in scripts/ directory (9 total, 3,577 lines of code):

Analysis Scripts:

• analyze_structure.py: Main structure analysis engine (378 lines)
• dependency_mapper.py: Maps import chains and dependencies (454 lines)
• dead_code_detector.py: Detects unused files and exports (540 lines)
• issue_detector.py: Unified issue detection aggregator (311 lines)
• project_scanner.py: Framework and language detection (177 lines)

Operation Scripts:

• restructure_planner.py: Generates migration plans (634 lines)
• migrate.py: Executes safe file reorganization (339 lines)
• safety_manager.py: Backup, trash, and recovery system (470 lines)

Reporting Scripts:

• report_generator.py: Creates HTML/Markdown reports (274 lines)

Run any script with --help for detailed options.

Troubleshooting

Common Issues

Large codebases (>10k files): Use --sample flag for initial analysis Binary files causing errors: Add to --exclude patterns Permission errors: Check file permissions or run with appropriate access Memory issues: Use --stream mode for large projects

For additional patterns and detailed examples, see references/patterns-catalog.md