# Makefile Tutorial: Generating PASBDC Reports

This project uses a `makefile` to automate the generation of Section 1 (Network Wide) and Section 3 (Center Specific) reports. The pipeline can process data either from manually exported CSV files or directly from Neoserra via the Export Module (API).

## Table of Contents
1. [Prerequisites](#prerequisites)
2. [Data Source Modes](#data-source-modes)
3. [Running Reports](#running-reports)
4. [Targeting Specific Fiscal Years](#targeting-specific-fiscal-years)
5. [Manual Setup for Scorecard Reports (Intervals & Satisfaction)](#manual-setup-for-scorecard-reports)
6. [Output Structure](#output-structure)

---

## Prerequisites

- **Python 3.12+**: Ensure Python is installed.
- **Virtual Environment**: The makefile expects a virtual environment at `.venv/`.
  ```bash
  python -m venv .venv
  source .venv/bin/activate  # Linux/macOS
  # or
  .venv\Scripts\activate     # Windows
  pip install -r requirements.txt
  ```

---

## Data Source Modes

The makefile supports two ways to ingest data from Neoserra.

### 1. Manual CSV Mode (Default)
This mode uses CSV files stored locally in the `csv_files/` directory.

- **Requirement**: `USE_EXPORT_MODULE=false` (default).
- **File Naming**: CSVs must follow a specific naming convention: `[type]_raw_[FYXX].csv`.
  Example for FY25:
  - `csv_files/trainings_raw_FY25.csv`
  - `csv_files/client_list_raw_FY25.csv`
  - `csv_files/nbs_milestones_raw_FY25.csv`
  - `csv_files/funding_milestones_raw_FY25.csv`
  - *Plus specialized interval CSVs:* `days_client_signup_to_start_FY25.csv`, etc.

### 2. Export Module Mode (API)
This mode fetches data directly from Neoserra using pre-configured Export Module URLs.

- **Requirement**: `USE_EXPORT_MODULE=true`.
- **Usage**:
  ```bash
  make all USE_EXPORT_MODULE=true
  ```
- **Note**: **Counselling Interval Analysis** and **Satisfaction Survey** reports are skipped in this mode. Neoserra does not currently support exporting scorecard/survey data via the Export Module API; these reports require manual CSV exports.

---

## Running Reports

### Generate All Reports (Current FY)
To generate all Section 1 and Section 3 reports for the current fiscal year:
```bash
make all
```

### Clean Previous Runs
To delete the generated reports for the resolved fiscal year:
```bash
make clean
```

---

## Targeting Specific Fiscal Years

The makefile automatically calculates the `CURRENT` and `PREVIOUS` fiscal years based on the system date (FY starts Oct 1st). You can override this in two ways:

### 1. Using Helper Targets
```bash
make current    # Force current FY
make previous   # Force previous FY
make fy24       # Specific year
make fy23       # Specific year
```

### 2. Overriding the Variable
```bash
make all FISCAL_YEAR=FY25
```

---

## Manual Setup for Scorecard Reports

Because Neoserra does not support exporting Scorecard data (Satisfaction and Intervals) via the API, these must always be run using CSV files. **Critically, you must ensure `USE_EXPORT_MODULE=false` is set (which is the default).**

### 1. Export Data from Neoserra
Manual exports must be performed in Neoserra for the following categories:
- Satisfaction Survey
- Counselling Intervals (Signup to Start, Start to Counselling, etc.)

### 2. Place CSVs in `csv_files/`
Ensure the files are named correctly according to the `RESOLVED_FY`. If you are running for **FY26**, your files must be:
- `csv_files/satisfaction_survey_raw_FY26.csv`
- `csv_files/days_client_signup_to_start_FY26.csv`
- `csv_files/days_client_signup_to_counselling_FY26.csv`
- `csv_files/days_client_start_to_counselling_FY26.csv`
- `csv_files/days_initial_to_followup_FY26.csv`
- `csv_files/days_training_to_counselling_FY26.csv`

### 3. Running the Reports
To generate these reports for a new fiscal year (e.g., FY26), ensure the CSVs are in place and run:
```bash
# Explicitly disable export module to ensure these targets are not skipped
make all FISCAL_YEAR=FY26 USE_EXPORT_MODULE=false
```

### 4. Overriding Specific Paths (Optional)
If you need to use a non-standard file location:
```bash
make all SATISFACTION_SURVEY_CSV=special_exports/survey_data.csv USE_EXPORT_MODULE=false
```

---

## Output Structure

Reports are generated in the `reports/` directory, sub-folder by fiscal year:
```text
reports/
└── FY25/
    ├── section_1_trainings_analysis_FY25.docx
    ├── section_1_milestone_analysis_FY25.docx
    ├── section_3_trainings_topics_analysis_FY25.docx
    ├── section_3_trainings_analysis_word/ (Folder containing individual center docs)
    └── ... (folders containing generated graphs)
```