backend-structure-organizer
Organizes a flat backend directory structure into a clean, modular architecture with proper Python packages and updated import paths. Transforms a flat backend structure into a modular, organized architecture following Python best practices.
When & Why to Use This Skill
The Backend Structure Organizer is a specialized Claude skill designed to refactor flat Python backend directories into clean, modular architectures. It automates the reorganization of files into logical packages—such as services, models, and utilities—while simultaneously updating complex import paths and creating necessary package initializers. This tool ensures codebases follow Python best practices, significantly enhancing maintainability, scalability, and developer workflow efficiency.
Use Cases
- Refactoring legacy Python projects where all backend files are cluttered in a single root directory into a professional modular structure.
- Automating the tedious process of updating absolute and relative import statements across dozens of files during a directory reorganization.
- Standardizing messy prototype code into a production-ready architecture with dedicated layers for API, services, models, and database logic.
- Ensuring consistent Python package structures across multiple microservices by automatically generating __init__.py files and logical directory hierarchies.
- Updating project documentation and configuration files to reflect new architectural changes after a structural migration.
| name | backend-structure-organizer |
|---|---|
| description | Organizes a flat backend directory structure into a clean, modular architecture with proper Python packages and updated import paths. Transforms a flat backend structure into a modular, organized architecture following Python best practices. |
| license | Complete terms in LICENSE.txt |
Backend Structure Organizer
Organizes a flat backend directory structure into a clean, modular architecture with proper Python packages and updated import paths.
When to Use This Skill
This skill should be used when:
- Backend files are organized in a flat structure and need to be organized into logical modules
- Python backend code requires refactoring to follow package best practices
- Import statements need to be updated to reflect a new directory structure
- Documentation needs to be updated to reflect a new backend organization
Prerequisites
- Backend directory exists with Python files in flat structure
- Project uses Python with import statements that may need updating
- Git repository is initialized (for tracking changes)
Process Overview
Phase 1: Analysis and Setup
- Scan backend directory to identify all Python files
- Identify current structure and file locations
- Generate report of files to be moved and updated
- Create new organized directory structure:
agents/- AI/ML agents and processingauth/- Authentication moduleschatkit/- Chatkit integration componentsdata/- Data handling and storage utilitiesdatabase/- Database operations and managementmodels/- Database models and schema definitionsservices/- Business logic and service layerutils/- Utility functions and helpersscripts/- Utility scriptstests/- Test files
Phase 2: File Movement
- Move files to appropriate directories based on their purpose:
- Agent-related files →
agents/ - Authentication files →
auth/ - Data processing files →
data/ - Database files →
database/ - Model files →
models/ - Service files →
services/ - Utility files →
utils/ - Scripts →
scripts/ - Tests →
tests/
- Agent-related files →
Phase 3: Import Updates
- Update import statements in all affected Python files to reflect new locations
- Handle both absolute and relative import patterns
- Verify all imports resolve correctly after updates
Phase 4: Package Setup
- Create
__init__.pyfiles in each new directory - Ensure proper Python package structure
- Verify import resolution throughout codebase
Phase 5: Documentation Update
- Update README.md to include structure documentation
- Update requirements.txt if needed
- Update any configuration files referencing old paths
Common Import Pattern Updates
Main Application File (main.py) updates:
from database import→from database.database importfrom models import→from models.models importfrom agent import→from agents.agent importfrom vector_store import→from data.vector_store importfrom rate_limiting import→from utils.rate_limiting importfrom session_service import→from services.session_service import
Chatkit Components updates:
from models import→from models.models importfrom session_service import→from services.session_service importfrom agent import→from agents.agent importfrom vector_store import→from data.vector_store importfrom embeddings import→from data.embeddings import
Data Processing Files updates:
from database import→from database.database importfrom models import→from models.models importfrom vector_store import→from data.vector_store importfrom embeddings import→from data.embeddings import
Success Criteria
- All files organized into logical directories
- All import statements updated and resolving correctly
__init__.pyfiles created in each directory- Application functionality preserved
- Structure documented in README.md
Validation Steps
- Verify all imports resolve without errors
- Run application to ensure functionality preserved
- Check that new directory structure is logical and maintainable
- Confirm documentation reflects new structure
Rollback Plan
If issues occur:
- Restore from git backup before changes
- Revert file movements
- Revert import statement changes
- Remove newly created directories