OpenSPP · emjay0921 · Mar 12, 2026 · Mar 12, 2026 · Mar 12, 2026 · Mar 12, 2026
diff --git a/spp_aggregation/README.rst b/spp_aggregation/README.rst
@@ -22,84 +22,87 @@ OpenSPP Aggregation Engine
 
 |badge1| |badge2| |badge3|
 
-Unified aggregation engine for computing statistics, breakdowns, and
-fairness metrics over scoped registrant populations. Supports multiple
-scope types (CEL expressions, areas, spatial queries, explicit IDs) with
-access control, caching, and privacy enforcement.
+Unified aggregation service that all consumers (simulation API, GIS API,
+dashboards) use to compute population statistics with demographic
+breakdowns and privacy enforcement. Resolves a scope (CEL expression,
+area, polygon, explicit IDs) to registrant IDs, computes requested
+statistics, applies k-anonymity suppression, and caches results.
 
 Key Capabilities
 ~~~~~~~~~~~~~~~~
 
-- Define reusable aggregation scopes: CEL expression, area, area tag,
-  spatial polygon/buffer, or explicit registrant IDs
-- Resolve scopes to registrant sets with union and intersection
-  operations
-- Compute statistics (count, Gini) with extensible statistic registry
-  supporting CEL variables
-- Role-based access control with per-user scope type restrictions,
-  dimension limits, and area constraints
-- Result caching with configurable TTL per scope type and automatic
-  cleanup
-- Privacy enforcement via k-anonymity suppression on computed results
-- Convenience methods for area-based, expression-based, fairness, and
-  distribution queries
+- Single entry point (``spp.aggregation.service.compute_aggregation``)
+  for all analytics queries
+- Scope resolution: CEL expressions, admin areas, area tags, spatial
+  polygons/buffers, explicit IDs
+- Multi-dimensional breakdown (up to 3 dimensions) using demographic
+  dimensions
+- Result caching with configurable TTL and manual invalidation
+- Per-user access rules controlling scope types, dimensions, and
+  k-anonymity thresholds
 
 Key Models
 ~~~~~~~~~~
 
-+----------------------------+----------+----------------------------+
-| Model                      | Type     | Description                |
-+============================+==========+============================+
-| ``spp.aggregation.scope``  | Concrete | Configurable aggregation   |
-|                            |          | scope definitions          |
-+----------------------------+----------+----------------------------+
-| ``spp                      | Concrete | Per-user/group access      |
-| .aggregation.access.rule`` |          | control rules              |
-+----------------------------+----------+----------------------------+
-| ``spp                      | Concrete | Persistent cache entries   |
-| .aggregation.cache.entry`` |          | with TTL                   |
-+----------------------------+----------+----------------------------+
-| ``spp.ag                   | Abstract | Strategy-based scope       |
-| gregation.scope.resolver`` |          | resolution service         |
-+----------------------------+----------+----------------------------+
-| ``spp.aggregation.cache``  | Abstract | Cache service with TTL and |
-|                            |          | cleanup                    |
-+----------------------------+----------+----------------------------+
-| ``spp.aggreg               | Abstract | Statistic computation      |
-| ation.statistic.registry`` |          | registry (builtins + CEL)  |
-+----------------------------+----------+----------------------------+
-| `                          | Abstract | Main aggregation entry     |
-| `spp.aggregation.service`` |          | point                      |
-+----------------------------+----------+----------------------------+
++----------------------------------------+----------------------------------+
+| Model                                  | Description                      |
++========================================+==================================+
+| ``spp.aggregation.scope``              | Defines what to aggregate (CEL,  |
+|                                        | area, polygon, explicit IDs)     |
++----------------------------------------+----------------------------------+
+| ``spp.aggregation.access.rule``        | Per-user/group access level,     |
+|                                        | scope restrictions, k-threshold  |
++----------------------------------------+----------------------------------+
+| ``spp.aggregation.cache.entry``        | Cached aggregation results       |
++----------------------------------------+----------------------------------+
+| ``spp.aggregation.service``            | Abstract service: main           |
+|                                        | aggregation entry point          |
++----------------------------------------+----------------------------------+
+| ``spp.aggregation.scope.resolver``     | Abstract service: resolves       |
+|                                        | scopes to registrant IDs         |
++----------------------------------------+----------------------------------+
+| ``spp.aggregation.statistic.registry`` | Abstract service: dispatches     |
+|                                        | statistic computation            |
++----------------------------------------+----------------------------------+
 
 Configuration
 ~~~~~~~~~~~~~
 
-- Aggregation scopes: **Settings > Aggregation > Aggregation Scopes**
-- Access rules: **Settings > Aggregation > Access Rules**
-- Cache cleanup runs daily via scheduled action
+After installing:
+
+1. Navigate to **Settings > Aggregation > Configuration > Scopes** to
+   define reusable scopes
+2. Configure **Access Rules** to set per-user/group privacy levels and
+   scope restrictions
+3. Verify the **Cache Cleanup** scheduled action is active under
+   **Settings > Technical > Scheduled Actions**
+
+UI Location
+~~~~~~~~~~~
+
+- **Menu**: Settings > Aggregation > Configuration > Scopes
+- **Menu**: Settings > Aggregation > Configuration > Demographic
+  Dimensions
+- **Menu**: Settings > Aggregation > Configuration > Access Rules
 
 Security
 ~~~~~~~~
 
-+----------------------------------+----------------------------------+
-| Group                            | Access                           |
-+==================================+==================================+
-| ``spp_aggr                       | Read-only access to scopes and   |
-| egation.group_aggregation_read`` | cache                            |
-+----------------------------------+----------------------------------+
-| ``spp_aggre                      | Read/write scopes and access     |
-| gation.group_aggregation_write`` | rules                            |
-+----------------------------------+----------------------------------+
-| ``spp_aggreg                     | Implied by write group           |
-| ation.group_aggregation_viewer`` |                                  |
-+----------------------------------+----------------------------------+
-| ``spp_aggrega                    | Implied by viewer group          |
-| tion.group_aggregation_officer`` |                                  |
-+----------------------------------+----------------------------------+
-| ``spp_aggrega                    | Full access, implied by admin    |
-| tion.group_aggregation_manager`` |                                  |
-+----------------------------------+----------------------------------+
+============================= =============================
+Group                         Access
+============================= =============================
+``group_aggregation_read``    Read scopes and cache entries
+``group_aggregation_write``   Full CRUD on scopes and cache
+``group_aggregation_manager`` Full CRUD on access rules
+============================= =============================
+
+Extension Points
+~~~~~~~~~~~~~~~~
+
+- Add new scope types by extending ``spp.aggregation.scope`` and
+  ``spp.aggregation.scope.resolver``
+- Register custom statistics via ``spp.aggregation.statistic.registry``
+- Override ``_compute_single_statistic()`` for custom computation logic
 
 Dependencies
 ~~~~~~~~~~~~

diff --git a/spp_api_v2_simulation/README.rst b/spp_api_v2_simulation/README.rst
@@ -0,0 +1,153 @@
+======================
+OpenSPP Simulation API
+======================
+
+..
+   !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+   !! This file is generated by oca-gen-addon-readme !!
+   !! changes will be overwritten.                   !!
+   !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+   !! source digest: sha256:341a99619ee4fc6dc0669b84803de47b0cf14405275a60681952e5cf1eb6025f
+   !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+.. |badge1| image:: https://img.shields.io/badge/maturity-Production%2FStable-green.png
+    :target: https://odoo-community.org/page/development-status
+    :alt: Production/Stable
+.. |badge2| image:: https://img.shields.io/badge/license-LGPL--3-blue.png
+    :target: http://www.gnu.org/licenses/lgpl-3.0-standalone.html
+    :alt: License: LGPL-3
+.. |badge3| image:: https://img.shields.io/badge/github-OpenSPP%2FOpenSPP2-lightgray.png?logo=github
+    :target: https://github.com/OpenSPP/OpenSPP2/tree/19.0/spp_api_v2_simulation
+    :alt: OpenSPP/OpenSPP2
+
+|badge1| |badge2| |badge3|
+
+FastAPI-based REST endpoints for simulation scenario management,
+execution, comparison, and population aggregation. Provides external
+systems (dashboards, mobile apps, third-party tools) programmatic access
+to the simulation and analytics engine.
+
+Key Capabilities
+~~~~~~~~~~~~~~~~
+
+- CRUD operations on simulation scenarios with entitlement rules
+- Execute simulations and retrieve run results (distribution, fairness,
+  geographic data)
+- Compare multiple simulation runs side-by-side with overlap analysis
+- Compute population aggregation with demographic breakdowns via the
+  aggregation engine
+- List available demographic dimensions and scenario templates
+- Convert simulation scenarios to real programs
+
+API Endpoints
+~~~~~~~~~~~~~
+
++--------+-----------------------------+-----------------------------+
+| Method | Path                        | Description                 |
++========+=============================+=============================+
+| GET    | ``/simulation/scenarios``   | List scenarios              |
++--------+-----------------------------+-----------------------------+
+| POST   | ``/simulation/scenarios``   | Create scenario             |
++--------+-----------------------------+-----------------------------+
+| GET    | ``/                         | Get scenario details        |
+|        | simulation/scenarios/{id}`` |                             |
++--------+-----------------------------+-----------------------------+
+| PUT    | ``/                         | Update draft scenario       |
+|        | simulation/scenarios/{id}`` |                             |
++--------+-----------------------------+-----------------------------+
+| DELETE | ``/                         | Archive scenario            |
+|        | simulation/scenarios/{id}`` |                             |
++--------+-----------------------------+-----------------------------+
+| POST   | ``/simula                   | Mark scenario ready         |
+|        | tion/scenarios/{id}/ready`` |                             |
++--------+-----------------------------+-----------------------------+
+| POST   | ``/simu                     | Execute simulation          |
+|        | lation/scenarios/{id}/run`` |                             |
++--------+-----------------------------+-----------------------------+
+| POST   | ``/simulation/scenario      | Convert to program          |
+|        | s/{id}/convert-to-program`` |                             |
++--------+-----------------------------+-----------------------------+
+| GET    | ``/simulation/runs``        | List runs                   |
++--------+-----------------------------+-----------------------------+
+| GET    | ``/simulation/runs/{id}``   | Get run with optional       |
+|        |                             | details                     |
++--------+-----------------------------+-----------------------------+
+| POST   | ``/simulation/comparisons`` | Create run comparison       |
++--------+-----------------------------+-----------------------------+
+| GET    | ``/si                       | Get comparison              |
+|        | mulation/comparisons/{id}`` |                             |
++--------+-----------------------------+-----------------------------+
+| GET    | ``/simulation/templates``   | List scenario templates     |
++--------+-----------------------------+-----------------------------+
+| POST   | ``/aggregation/compute``    | Compute population          |
+|        |                             | aggregation                 |
++--------+-----------------------------+-----------------------------+
+| GET    | ``/aggregation/dimensions`` | List demographic dimensions |
++--------+-----------------------------+-----------------------------+
+
+OAuth Scopes
+~~~~~~~~~~~~
+
+====================== ====================================
+Scope                  Operations
+====================== ====================================
+``simulation:read``    List/get scenarios, runs, templates
+``simulation:write``   Create/update/archive scenarios
+``simulation:execute`` Run simulations
+``simulation:convert`` Convert scenario to program
+``aggregation:read``   Compute aggregation, list dimensions
+====================== ====================================
+
+UI Location
+~~~~~~~~~~~
+
+No standalone menu; API-only module.
+
+Dependencies
+~~~~~~~~~~~~
+
+``spp_api_v2``, ``spp_simulation``, ``spp_aggregation``
+
+**Table of contents**
+
+.. contents::
+   :local:
+
+Bug Tracker
+===========
+
+Bugs are tracked on `GitHub Issues <https://github.com/OpenSPP/OpenSPP2/issues>`_.
+In case of trouble, please check there if your issue has already been reported.
+If you spotted it first, help us to smash it by providing a detailed and welcomed
+`feedback <https://github.com/OpenSPP/OpenSPP2/issues/new?body=module:%20spp_api_v2_simulation%0Aversion:%2019.0%0A%0A**Steps%20to%20reproduce**%0A-%20...%0A%0A**Current%20behavior**%0A%0A**Expected%20behavior**>`_.
+
+Do not contact contributors directly about support or help with technical issues.
+
+Credits
+=======
+
+Authors
+-------
+
+* OpenSPP.org
+
+Maintainers
+-----------
+
+.. |maintainer-jeremi| image:: https://github.com/jeremi.png?size=40px
+    :target: https://github.com/jeremi
+    :alt: jeremi
+.. |maintainer-gonzalesedwin1123| image:: https://github.com/gonzalesedwin1123.png?size=40px
+    :target: https://github.com/gonzalesedwin1123
+    :alt: gonzalesedwin1123
+.. |maintainer-reichie020212| image:: https://github.com/reichie020212.png?size=40px
+    :target: https://github.com/reichie020212
+    :alt: reichie020212
+
+Current maintainers:
+
+|maintainer-jeremi| |maintainer-gonzalesedwin1123| |maintainer-reichie020212| 
+
+This module is part of the `OpenSPP/OpenSPP2 <https://github.com/OpenSPP/OpenSPP2/tree/19.0/spp_api_v2_simulation>`_ project on GitHub.
+
+You are welcome to contribute.
diff --git a/spp_graduation/views/graduation_menus.xml b/spp_graduation/views/graduation_menus.xml
@@ -5,6 +5,7 @@
         id="menu_graduation_root"
         name="Graduation"
         sequence="60"
+        web_icon="spp_graduation,static/description/openspp-graduation-menu-icons.png"
         groups="group_spp_graduation_user"
     />
 

diff --git a/spp_metrics_core/README.rst b/spp_metrics_core/README.rst
@@ -22,38 +22,63 @@ OpenSPP Metrics Core
 
 |badge1| |badge2| |badge3|
 
-Unified metric foundation providing abstract base models for statistics,
-simulations, and reporting across OpenSPP modules.
+Shared foundation for all metric types in OpenSPP (statistics,
+simulation metrics, and custom domain metrics). Provides an abstract
+base model with identity, presentation, and categorization fields, plus
+a hierarchical category system. Concrete metric modules inherit from the
+base and add their own computation fields.
 
 Key Capabilities
 ~~~~~~~~~~~~~~~~
 
-- Abstract base model for defining reusable metrics with label, unit,
-  and decimal precision
-- Hierarchical metric categories with unique code constraints
-- Category tree with parent-child recursion prevention
-- Default metric categories for population, coverage, targeting, and
-  distribution
+- Abstract base model (``spp.metric.base``) with shared identity,
+  presentation, and metadata fields
+- Hierarchical metric category system with unique codes
+- Default categories: Demographics, Vulnerability, Programs, Geographic,
+  Economic, Fairness
 
 Key Models
 ~~~~~~~~~~
 
-+-------------------------+----------+----------------------------+
-| Model                   | Type     | Description                |
-+=========================+==========+============================+
-| ``spp.metric.base``     | Abstract | Base fields and logic      |
-|                         |          | inherited by concrete      |
-|                         |          | metrics                    |
-+-------------------------+----------+----------------------------+
-| ``spp.metric.category`` | Concrete | Hierarchical grouping of   |
-|                         |          | metrics by domain          |
-+-------------------------+----------+----------------------------+
++-------------------------+--------------------------------------------+
+| Model                   | Description                                |
++=========================+============================================+
+| ``spp.metric.base``     | Abstract model inherited by all concrete   |
+|                         | metric types                               |
++-------------------------+--------------------------------------------+
+| ``spp.metric.category`` | Hierarchical categorization for organizing |
+|                         | metrics                                    |
++-------------------------+--------------------------------------------+
 
 Configuration
 ~~~~~~~~~~~~~
 
-No configuration required. Default categories are created via data files
-on install.
+After installing, default metric categories are created automatically.
+Add custom categories via **Settings > Technical > Metric Categories**
+or in XML data files.
+
+UI Location
+~~~~~~~~~~~
+
+No standalone menu; library module consumed by ``spp_statistic``,
+``spp_simulation``, and other metric modules.
+
+Security
+~~~~~~~~
+
+===================== =======================
+Group                 Access
+===================== =======================
+``base.group_user``   Read categories
+``base.group_system`` Full CRUD on categories
+===================== =======================
+
+Extension Points
+~~~~~~~~~~~~~~~~
+
+- Inherit ``spp.metric.base`` to create domain-specific metric models
+- Add custom categories via XML data records referencing
+  ``spp.metric.category``
 
 Dependencies
 ~~~~~~~~~~~~