FASP-QAT · RohitAltius · Mar 25, 2026 · Mar 24, 2026 · Mar 25, 2026 · Mar 25, 2026
diff --git a/docs/user/00-introduction.md b/docs/user/00-introduction.md
diff --git a/docs/user/01-introduction.md b/docs/user/01-introduction.md
@@ -0,0 +1,14 @@
+---
+id: introduction
+title: "Introduction"
+sidebar_label: "Introduction"
+sidebar_position: 1
+---
+
+# Introduction
+
+Welcome to the User Documentation for the Quantification Analytics Tool (QAT). This guide is designed for both end-users and technical administrators, providing comprehensive information on system functionality, workflows, and best practices.
+
+The Quantification Analytics Tool (QAT) is a modernized solution for country-led forecasting and supply planning. QAT leverages advanced technologies to enhance the functionality of legacy tools like PipeLine and Quantimed.
+
+For a high-level overview of the document structure, please refer to the [Table of Contents](03-table-of-contents.md).
diff --git a/docs/user/01-overview.md b/docs/user/01-overview.md
diff --git a/docs/user/02-getting-started.md b/docs/user/02-getting-started.md
diff --git a/docs/user/02-version-history.md b/docs/user/02-version-history.md
@@ -0,0 +1,20 @@
+---
+id: version-history
+title: "Version History"
+sidebar_label: "Version History"
+sidebar_position: 2
+---
+
+# Version History
+
+| Version | Date | Author/Editor | Notes & Major Changes |
+| :--- | :--- | :--- | :--- |
+| 0 | Jan 27, 2021 | Altius & FHI 360 | Initial draft. |
+| 1 | Mar 15, 2021 | GHSC-PSM FASP | Restructured document; moved realm and application administrator functions to Annex; applied formatting changes and clarity edits. |
+| 2 | Apr 26, 2021 | GHSC-PSM FASP | **Software Enhancements:**<br/>- Section 2.E: Included password expiry rules.<br/>- Section 5.A: Updated screenshots and terminology for actual vs. projected inventory.<br/>- Section 6.A: Enhanced QAT Problem List with summary tables, updated logic, and problem categories. |
+| 3 | June 10, 2021 | GHSC-PSM FASP | **General Updates:**<br/>- Improved section numbering and footer formatting.<br/>- Added reminders for master data synchronization and offline/online modes.<br/>**Software Enhancements:**<br/>- Section 4.B.3: Updated batch information pop-ups.<br/>- Section 4.B.4: Added ERP Linking instructions and screenshots.<br/>- Section 4.A.3: Integrated alternate reporting units.<br/>- Section 5.C.1 & 5.C.2: Updated suggested shipment logic and added recalculation features.<br/>- Section 5.D: Added final inventory batch pop-ups.<br/>- Section 5.E: Introduced the batch ledger. |
+| 4 | Oct 15, 2021 | GHSC-PSM FASP | **Software Enhancements:**<br/>- Section 4.A.1: Updated multi-select functionality for technical areas.<br/>- Annex 1 Section H: Added "organization & country" descriptor to user requirements.<br/>- Annex 1 Section G: Added Organization Type instructions for realm-level master data. |
+| 5 | Feb 13, 2023 | GHSC-PSM FASP | **Core Updates:**<br/>- Integrated the Forecasting Module throughout the manual.<br/>**Software Enhancements:**<br/>- Section 2.E: Added online/offline functionality.<br/>- Section 2.H.3: Included network error troubleshooting.<br/>- Section 2.I: Updated Jira HelpDesk ticket management.<br/>- Section 3.D & 6.A.1: Added manual problem descriptions.<br/>- Section 3.E: Explained unencrypted/encrypted JSON exports.<br/>- Section 4.A.2, 5.A, 6.A.3, 6.C.2, & 6.C.3: Explained minimum quantity parameters.<br/>- Section 4.B.3: Added strategic calculator and emergency shipment details.<br/>- Section 4.B.4: Updated ERP Linking functionality.<br/>- Section 4.C.3: Launched QAT Forecast Import.<br/>- Section 5.F: Added "Replan Supply Plan" scenario.<br/>- Section 6.E.1 & 6.E.2: Added Procurement Agent-specific dropdowns.<br/>- Section 6.E.3: Added editing capability to Shipment Details Report.<br/>- Annex 2: Added Business Rules for the Forecasting Module. |
+| 6 | Feb 16, 2023 | GHSC-PSM FASP | Updated PMI branding and logo. |
+| 7 | Nov 09, 2023 | GHSC-PSM | **Terminology & Core Changes:**<br/>- Standardized "Upload/Download" language throughout. <br/>- Section 3.B: Clarified redownload notifications.<br/>- Section 3.C: Optimized merging forecasts during upload.<br/>- Section 3.D: Renamed 'Rejected' status to 'Needs Revision'.<br/>- Section 4.A.1, 4.A.4 & Annex 3/4: Added Road transport and enhanced Program Admin permissions.<br/>- Section 4.A.6: Multi-program tagging for budgets.<br/>- Section 4.B.1 & 4.B.2: Multi-select PU support for data entry.<br/>- Section 5.A, 5.C, & 5.G: Streamlined shipment handling and improved visualization.<br/>- Section 6.D, 6.F, & 8.B: New reports (Forecast Error, Inventory Turns) and tree forecast enhancements. |
+| 8 | Dec 31, 2024 | GHSC-PSM | **Major Platform Enhancements:**<br/>- Section 2.L: Introduced the enhanced Supply Planning Dashboard.<br/>- Section 3.B: Subset data downloads for optimized file size.<br/>- Section 4.A.3: Added PA-specific freight and lead time defaults.<br/>- Section 8.A.3: Bulk extrapolation and optimized ARIMA/TES parameters.<br/>- Section 8.B.1: Enhanced tree reordering, branch templates, and aesthetic updates.<br/>- Annex 1/2: Updated business rules for inventory tagging, auto-adjustments, and realm-level tools. |
diff --git a/docs/user/03-managing-programs-and-versions.md b/docs/user/03-managing-programs-and-versions.md
diff --git a/docs/user/03-table-of-contents.md b/docs/user/03-table-of-contents.md
@@ -0,0 +1,64 @@
+---
+id: table-of-contents
+title: "Table of Contents"
+sidebar_label: "Table of Contents"
+sidebar_position: 3
+---
+
+# Table of Contents
+
+Below is the full breakdown of the QAT user documentation. Click on any section to navigate to the detailed guide.
+
+- [Acronyms](18-acronyms.md)
+- [Section 1: Overview](04-overview.md#overview)
+- [Section 2: Getting Started](05-getting-started.md#getting-started)
+- [Section 3: Managing Programs and Versions](06-managing-programs-and-versions.md#managing-programs-and-versions)
+- [Section 4: Supply Planning Module - Program Data](07-supply-planning-module-program-data.md#supply-planning-module-program-data)
+- [Section 5: Supply Planning Module - Supply Planning](08-supply-planning-module-supply-planning.md#supply-planning-module-supply-planning)
+- [Section 6: Supply Planning Module - Reports](09-supply-planning-module-reports.md#supply-planning-module-reports)
+- [Section 7: Forecasting Module - Program Data](10-forecasting-module-program-data.md#forecasting-module-program-data)
+- [Section 8: Forecasting Module - Forecasting](11-forecasting-module-forecasting.md#forecasting-module-forecasting)
+- [Section 9: Forecasting Module - Reports and Outputs](12-forecasting-module-reports-and-outputs.md#forecasting-module-reports-and-outputs)
+- [Annex 1: Application & Realm Administrator Manual](13-annex-1-application-realm-administrator-manual.md#annex-1-application-realm-administrator-manual)
+- [Annex 2: Business Rules](14-annex-2-business-rules.md#annex-2-business-rules)
+- [Annex 3: User Role Matrix](15-annex-3-user-role-matrix.md#annex-3-user-role-matrix)
+- [Annex 4: Business Functions](16-annex-4-business-functions.md#annex-4-business-functions)
+- [Annex 5: PipeLine Program Import](17-annex-5-pipeline-program-import.md#annex-5-pipeline-program-import)
+
+---
+
+## Acronyms
+
+| Acronym | Definition |
+| :--- | :--- |
+| **AMC** | Average Monthly Consumption |
+| **ARIMA** | Auto Regressive Integrated Moving Average |
+| **ARTMIS** | Automated Requisition Tracking Management Information System |
+| **ARU** | Alternate Reporting Unit |
+| **ERP** | Enterprise Resource Planning |
+| **EU** | Equivalency Unit |
+| **FASP** | Forecasting and Supply Planning |
+| **FEFO** | First Expiry, First Out |
+| **FP/RH** | Family Planning and Reproductive Health |
+| **GFPVAN** | Global Family Planning Visibility and Analytics Network |
+| **GHSC-PSM** | Global Health Supply Chain – Procurement and Supply Management |
+| **GLN** | Global Location Number |
+| **GTIN** | Global Trade Item Number |
+| **MSE** | Mean Squared Error |
+| **MAPE** | Mean Absolute Percentage Error |
+| **MNCH** | Maternal, Newborn and Child Health |
+| **MOH** | Ministry of Health |
+| **MOQ** | Minimum Order Quantity |
+| **MOS** | Months of Stock |
+| **PEPFAR** | President's Emergency Plan for AIDS Relief |
+| **PMI** | U.S. President's Malaria Initiative |
+| **PWA** | Progressive Web Application |
+| **QAT** | Quantification Analytics Tool |
+| **RMSE** | Root Mean Squared Error |
+| **RO** | Requisition Order |
+| **SKU** | Stock Keeping Unit |
+| **SOH** | Stock on Hand |
+| **STG** | Standard Treatment Guidelines |
+| **TES** | Triple Exponential Smoothing (Holt-Winters) |
+| **USAID** | United States Agency for International Development |
+| **WAPE** | Weighted Absolute Percentage Error |
diff --git a/docs/user/04-overview.md b/docs/user/04-overview.md
@@ -0,0 +1,102 @@
+---
+id: overview
+title: "Overview"
+sidebar_label: "Overview"
+sidebar_position: 4
+---
+
+# Overview
+
+# Overview
+
+## Introduction
+
+The Global Health Supply Chain – Procurement and Supply Management (GHSC-PSM) program is an official United States Agency for International Development (USAID) project. Implemented by Chemonics International and its consortium members, GHSC-PSM ensures the uninterrupted supply of health commodities to support U.S. Government-funded public health initiatives worldwide.
+
+The Forecasting and Supply Planning (FASP) tool modernization initiative was supported by the U.S. President’s Emergency Plan for AIDS Relief (PEPFAR), the U.S. President’s Malaria Initiative (PMI), USAID’s Family Planning and Reproductive Health (FP/RH) program, and USAID’s Maternal and Child Health (MCH) program.
+
+### Background and Objectives
+Previous USAID-funded projects, such as Supply Chain Management Systems (SCMS) and DELIVER, successfully implemented a suite of FASP tools. However, these tools were often siloed, had inconsistent user interfaces, and required manual data exchange.
+
+The primary objective of this initiative was to build a next-generation FASP platform that is:
+- **Scalable and Modular**: Built on a modern, operating-system-agnostic architecture.
+- **Web-Based with Offline Capabilities**: Ensuring accessibility even in low-connectivity environments.
+- **Interoperable**: Designed for seamless data sharing across stakeholders and public health systems.
+- **User-Centric**: Focused on usability and automation to drive end-to-end data visibility and evidence-based decision-making.
+
+## Forecasting vs. Supply Planning
+
+- **Forecasting**: An estimate or prediction of the quantities of products to be consumed by clients or consumers over a future period.
+- **Supply Planning**: The component of supply chain management focused on fulfilling demand plan requirements. The goal is to balance supply and demand to meet the financial and service delivery objectives of the health program.
+
+## What is QAT and What Can It Do for You?
+
+The Quantification Analytics Tool (QAT) is a modernized solution for country-led forecasting and supply planning. QAT leverages advanced technologies to enhance the functionality of legacy tools like PipeLine and Quantimed by providing:
+- **Flexible Forecasting**: Customizable tree structures and advanced extrapolation methodologies (ARIMA, Holt-Winters, etc.).
+- **Scenario Planning**: Robust tools to model and compare different supply chain scenarios.
+- **Offline Functionality**: Reliable data entry and management without a constant network connection.
+- **Standardization**: Master data management to drive consistency across all programs.
+
+### Core Functions
+- **Forecasting**: Multi-method forecasts, visual output comparison, and stakeholder consensus tools.
+- **Monitoring**: Real-time tracking of stock balances, minimum/maximum stock parameters, and automated problem identification (e.g., pending shortfalls).
+- **Procurement Planning**: Shortfall calculations, lead-time-based action tracking, and estimated shipment/freight cost modeling.
+
+## Who Should Use QAT?
+
+QAT empowers local program managers to take charge of their own forecasting and procurement planning. While program managers are the primary users, the system provides vital insights for policymakers, country directors, procurers, and donors.
+
+| User Group | Purpose |
+| :--- | :--- |
+| **Supply Planners / Program Managers** | Manage procurements across multiple funding sources and procurement agents. QAT provides visibility into long-term stock status and decreases the risk of stock imbalances. |
+| **Forecast / Demand Planners** | Estimate demand using flexible templates and built-in validations. Compare methodologies and select final commodity forecasts using integrated visualizations. |
+| **Policy Makers / Directors** | Visually compare forecasts and analyze the implications of budgetary constraints or new program targets. |
+| **Procurers and Donors** | Gain clear visibility into current supply status and future procurement requirements. |
+
+*Table 1: Recommended QAT users and purpose*
+
+## Important QAT Concepts and Terms
+
+### Cross-cutting Terms
+
+| Term | Definition |
+| :--- | :--- |
+| **Forecasting Unit** | The base unit used for a specified forecasting period (e.g., one tablet, one milliliter). |
+| **Master Data (Sync)** | A standardized set of data (e.g., product lists, funder names) shared across the system. Users can request updates via a ticketing mechanism. QAT syncs master data during login or manual triggers. Note that full forecast or supply plan datasets must be downloaded for local use. |
+| **Planning Unit** | The product planned for in QAT, described up to the primary packaging level (e.g., a bottle of 30 tablets). |
+| **Programs** | Similar to a "supply plan database" in legacy tools. Each program consists of one country, specific technical areas, a region (e.g., national level), and an organization (e.g., MOH). |
+| **Realm** | A high-level subdivision in QAT (e.g., Global Health) governed by its own master data. |
+| **Region** | Sub-national levels used to structure program data. To define a region, both consumption and inventory data must be entered at that level for national aggregation. |
+| **Technical Area** | Synonymous with commodity groups (e.g., ARV, Malaria, Family Planning) used to categorize programs. |
+| **Tickets** | The mechanism for reporting bugs or requesting master data updates. Tickets are resolved by system administrators. |
+| **User Roles** | Dedicated assignments that define data access and functional permissions within the application. |
+
+### Supply Planning Terms
+
+| Term | Definition |
+| :--- | :--- |
+| **Alternate Reporting Unit (ARU)** | The product and unit in which a country's data (consumption or stock) is reported. This may differ from the planning unit. QAT allows users to define an ARU and a conversion factor (multiplier) to the planning unit. For example, if the planning unit is a bottle of 30 tablets and inventory is reported in boxes of 20 bottles, the multiplier is 20. See Section 4.A3 (Alternate Reporting Unit) for details. |
+| **Average Monthly Consumption (AMC)** | A dynamic value calculated month-to-month based on average product usage over a specific period. By default, QAT calculates AMC using the past three months, the current month, and the next two months. Missing monthly data is treated as "null" rather than zero. Administrators can adjust the calculation window up to 12 months into the past and future.<br/>![AMC Formula](/img/media/image6.png) |
+| **Data Source** | The origin of data entered into QAT. Data sources must be applied to all transactional records (Consumption, Inventory, Adjustments, and Shipments). Selection depends on the specific Data Source Type of the record. |
+| **Enterprise Resource Planning (ERP)** | QAT is designed to interface with various procurement management systems (ERPs). Currently, an interface with ARTMIS enables the direct import of USAID product and shipment data which reduces manual planning efforts by auto-updating delivery dates and statuses. |
+| **Funding Source** | Any financial institution or entity providing facilities or funding for the program. Every shipment must be assigned a funding source. |
+| **Lead Times** | Mapped to supply planning statuses, lead times are input per product, procurement agent, or program. Calculations include:<br/>- **Planned to Submitted**: Time from identifying a need to entry in the procurement system.<br/>- **Submitted to Approved**: Time from entry to procurement approval.<br/>- **Approved to Shipped**: Time from approval to supplier dispatch.<br/>- **Shipped to Arrived (Sea/Air)**: Transit time to the port of entry.<br/>- **Arrived to Received**: Time for customs clearance and delivery to the final destination. |
+| **Min & Max Stock Levels** | **Minimum stock level** (in months) is determined per planning unit at the program level. <br/>![Min Stock Formula](/img/media/image7.png)<br/>**Maximum stock level** is dynamically calculated as the minimum stock level plus the reorder interval.<br/>![Max Stock Formula](/img/media/image8.png) |
+| **Minimum Order Quantity (MOQ)** | The minimum number of units a product must be ordered in. |
+| **Months of Stock (MOS)** | A measure of inventory levels relative to consumption, conceptually similar to PipeLine but using the updated QAT AMC methodology.<br/>![MOS Formula](/img/media/image9.png) |
+| **Plan by MOS** | Best suited for high-consumption products with minimal expiries where shipments primarily replace consumed stock. Planning focuses on maintaining month-based stock parameters. See Section 4.A2 for configuration. |
+| **Plan by Quantity** | Best suited for low-consumption products with high expiry rates (e.g., emergency medicines). Planning focuses on maintaining a fixed quantity of stock (e.g., 2 units per facility) rather than months of stock. See Section 4.A2 for configuration. |
+| **Reorder Interval** | The user-defined number of months between shipments (default is 1 month). This value is used to calculate maximum stock levels for both MOS and Quantity-based planning. |
+| **Shipment Statuses** | Tracking a shipment through its lifecycle via nine statuses: Suggested (automated warning), Planned (confirmed for projection), Submitted (ordered), Approved, Shipped, Arrived (at port), Received (at destination), Cancelled, and On-Hold. |
+| **Unmet Demand** | Quantities that would have been consumed if stock were available. QAT tracks unmet demand separately when:<br/>a) Forecasted consumption exceeds available stock.<br/>b) Actual consumption includes stock-out periods.<br/>c) A negative adjustment exceeds the projected ending balance. |
+| **Volumetrics** | Feature allowing users to define product volumes to estimate the total physical size and logistics requirements of orders. |
+
+### Forecasting Terms
+
+| Term | Definition |
+| :--- | :--- |
+| **Consumption-based Forecast** | A prediction of future demand based on historical actual consumption data using linear and non-linear extrapolation methodologies. |
+| **Tree Forecast** | Flexible forecasting structures used to convert diverse data types (demographics, morbidity, services) into commodity requirements by modeling service pathways. |
+| **Tree Template** | Pre-defined forecasting trees that can be downloaded and customized to a specific user's context. |
+| **Usage Template** | Pre-defined rates of use for specific products that can be applied consistently across different trees and programs. |
+| **Continuous and Discrete Usage** | When defining usage rates, users can choose between **Continuous** (ongoing) or **Discrete** (specific period or single-use) applications. |