# 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:**
   ```bash
   python setup_wizard.py
   ```

2. **Test data loading:**
   ```bash
   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:**
   ```bash
   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