sales-data-analysis/TEMPLATE_OVERVIEW.md

Sales Analysis Template - Overview

Start here for a high-level understanding of the template.

For detailed setup, see QUICK_START.md. For complete documentation, see README.md.

🎯 Purpose

This template provides a production-ready, reusable framework for analyzing sales invoice detail data from any company. It's designed to be:

• Flexible: Works with different column names, date formats, and data structures
• Automated: Interactive setup wizard configures everything
• AI-Optimized: Fully optimized for Cursor AI - just ask and the AI generates complete analyses
• Best-in-Class: Based on proven patterns from 24+ production analyses

📦 What's Included

Core Framework

• config.py - Centralized configuration (customize for your company)
• data_loader.py - Intelligent data loading with fallback logic
• analysis_utils.py - Common utilities (formatters, LTM, helpers)
• validate_revenue.py - Revenue validation utility

Templates & Tools

• analysis_template.py - Template for creating new analyses
• run_all_analyses.py - Batch runner for all scripts
• setup_wizard.py - Interactive setup wizard

Documentation

• README.md - Comprehensive documentation
• QUICK_START.md - Quick reference guide
• .cursor/rules/ - Cursor IDE rules for automation

Configuration

• requirements.txt - Python dependencies
• .gitignore - Git ignore patterns

🚀 Quick Start

1. Run setup wizard:

   python setup_wizard.py
   

2. Test data loading:

   python -c "from data_loader import load_sales_data; from config import get_data_path; df = load_sales_data(get_data_path()); print(f'✓ Loaded {len(df):,} rows')"
   

3. Create your first analysis:

   cp analysis_template.py my_analysis.py
   # Edit my_analysis.py
   python my_analysis.py
   

🎨 Key Features

1. Flexible Data Loading

• Handles different column names via configuration
• Fallback logic for date parsing (100% coverage)
• Automatic validation

2. LTM Support

• Automatic Last Twelve Months calculation
• Apples-to-apples comparison with full years
• Configurable periods

3. Standardized Formatting

• Automatic millions formatter for revenue
• Consistent chart styling
• Professional output

4. Exclusion Filters

• Easy configuration for excluding segments
• Useful for test accounts, business units, etc.

5. AI Automation

• Comprehensive Cursor rules
• Automated agent assistance
• Best practices enforcement

📊 Analysis Types Supported

This template supports all standard sales analyses:

• Revenue: Annual trends, monthly analysis, by segment
• Customer: Segmentation, concentration, churn, CLV
• Product: Performance, lifecycle, BCG matrix
• Financial: Price elasticity, margins
• Advanced: Seasonality, forecasting, predictions

🔧 Customization Points

All customization happens in config.py:

1. Company Info: Name, analysis date
2. Data File: Location, filename
3. Column Mappings: Revenue, date, customer, product, etc.
4. Date Range: Years, LTM configuration
5. Filters: Exclusion rules
6. Chart Settings: Sizes, styles, DPI

📚 Documentation Structure

• README.md - Complete guide (start here)
• QUICK_START.md - Quick start (includes Cursor tips)
• EXAMPLES.md - Example scripts guide
• TEMPLATE_SUMMARY.md - Comprehensive template overview
• .cursor/rules/ - Detailed patterns for AI agents (auto-loaded by Cursor)
• config.py - Heavily commented configuration

🎓 Learning Path

1. Read: QUICK_START.md (5 minutes)
2. Run: setup_wizard.py (2 minutes)
3. Test: Data loading (1 minute)
4. Create: First analysis using analysis_template.py (15 minutes)
5. Explore: .cursor/rules/ for patterns (as needed)

💡 Best Practices

1. Always use utilities - Don't reinvent the wheel
2. Use config values - Never hardcode column names
3. Validate data - After loading and after analysis
4. Follow patterns - See .cursor/rules/analysis_patterns.md
5. Test incrementally - Test data loading before full analysis

🔍 What Makes This "Best-in-Class"

1. Proven Patterns: Based on 24+ production analyses
2. Flexibility: Works with any data structure
3. Automation: Setup wizard + AI-friendly rules
4. Documentation: Comprehensive guides and examples
5. Error Handling: Validation and troubleshooting built-in
6. Consistency: Standardized formatting and patterns

📈 Next Steps

1. Run setup_wizard.py to configure for your company
2. Review config.py to understand all options
3. Create your first analysis using analysis_template.py
4. Explore .cursor/rules/ for detailed patterns
5. Build your analysis suite

---

Template Version: 1.0
Last Updated: January 2026
Status: Production Ready