OpenSPP v2 — Public Release

OpenSPP v2 is a complete social protection platform built on Odoo 19, covering the full programme lifecycle from registration and eligibility through payments, grievances, and compliance. It is designed for national and subnational deployments where data quality, privacy, and interoperability with government systems are non-negotiable requirements. The 90+ module architecture allows governments and implementing organisations to install only what they need, from a standalone farmer registry to a full SP-MIS with disaster response and case management.

Platform Components

Registry

The Registry is the authoritative source of record for individuals and groups — households, families, cooperatives — providing a unified data model with configurable identity documents, verification workflows, and relationship mapping. It is designed to handle the messy realities of population data at scale: overlapping group memberships, multiple ID types with varying verification confidence, and the need to expose data to officers without exposing it to everyone.

Unified res.partner model with is_registrant / is_group flags — no separate tables for individuals vs. groups
Privacy-by-default search interface loads zero records until a 3-character query is entered
Four-tier RBAC (viewer, officer, manager, config admin) with hierarchical group nesting (e.g., cooperative → farm → individual)
ID documents support regex validation per type, namespace URIs for standards compliance, and seven verification methods (DCI API, physical document, biometric, etc.)
CEL-powered registry search compiles expressions to SQL for filtered queries at scale
Group metric invalidation automatically triggers recomputation of household-level indicators when membership changes

Area Management

Area Management provides the geographic backbone of the platform — a configurable administrative boundary hierarchy that drives access control, reporting, and spatial queries across every other module. Rather than hard-coding country-specific boundary structures, it supports up to ten levels with bulk import from standard humanitarian datasets.

Max 10-level hierarchy with parent_path indexing for efficient subtree queries
Bulk Excel import parses COD-style column patterns (adminNName_{lang}, ADMN_PCODE) in 1,000-row job-queue batches
HDX Common Operational Datasets integration downloads admin boundaries with official P-codes
center_area_ids on res.users computed from role lines — drives automatic domain filtering on spp.area and res.partner
Area tags (spp.area.tag) with unique codes enable CEL-based and report-based filtering
PostGIS extension (via spp_gis) adds find_by_coordinates() and find_all_containing() spatial lookups

Security

OpenSPP's security model is built around the principle that access rules should be composable, auditable, and enforceable at the database level — not just the UI. The three-tier architecture separates technical groups, functional privileges, and optional user roles so that permissions can be granted and revoked cleanly without side effects.

24 ir.module.category entries organise permissions by domain (registry, programs, payments, GIS, audit, etc.)
group_spp_admin inherits all domain manager groups; linked to base.group_system via post-init hook
group_access_restrict_self limits field agents to their own user record
Multi-company rule_partner_company record rule gates res.partner access by company_id
Odoo 19 privilege system (res.groups.privilege) provides clean per-domain UI for permission assignment
Auditor bypass group grants unrestricted registry browse for compliance staff

Vocabulary

Vocabulary management provides a shared semantic layer so that data from different countries, systems, and standards can be compared and combined without transformation errors. Each code list is anchored to a globally unique namespace URI, and concept groups abstract over local vs. international schemes so that business logic written once works across all deployments.

Namespace URIs per vocabulary (e.g., urn:iso:std:iso:5218, urn:fao:icc:1.1) for unambiguous cross-system exchange
Deployment profiles activate context-relevant codes without modifying underlying vocabularies; local extensions via is_local=True
Concept groups enable vocabulary-aware CEL functions like is_female() and is_head()
Vocabulary mappings transform between code systems (e.g., national disability codes ↔ DCI standard)
System vocabularies are write-protected; only active, deprecated, and sequence fields are editable
REST API exposes vocabularies for external system synchronisation via spp_api_v2_vocabulary

Farmer Registry

The Farmer Registry extends the social registry with an FAO-aligned agriculture data model, enabling governments to manage agricultural households and individual farmers within the same platform used for broader social protection. Farm classification, species tracking, and land parcel management are all natively integrated with the CEL targeting engine.

Farm details use _inherits delegation: type, tenure, holder type (FAO WCA 2020), acreage breakdown, experience years
Agricultural activities track crop/livestock/aquaculture with species from urn:fao:icc:1.1, urn:fao:livestock:2020, urn:fao:asfis:2024 — extensible via AGROVOC import wizard
Season state machine (draft → active → closed) with overlap prevention and role-based access
CEL variables include farm_size_hectares, is_smallholder (configurable threshold, default 5 ha), crop_count, total_livestock_heads, is_female_farmer
Dedicated CR types for farm details, activities, land parcels, and assets with approval workflows
Starter bundle (spp_starter_farmer_registry) installs social registry + GIS + programs + API in one click

Disability Registry

The Disability Registry implements internationally standardised disability assessment tooling — the Washington Group Short Set and the UNICEF Child Functioning Module — directly within the platform, with automated scheduling, DCI interoperability, and assistive device tracking. Assessment type selection is automatic based on the individual's age at time of assessment.

WG-SS 4-point scale per domain; "a lot" or "cannot do" in any domain = has_disability
Review categories: MIE (12 months), MIP (36 months), MINE (72 months) — next review date auto-computed
Assistive device tracking with ISO 9999-aligned types and status lifecycle (needed → requested → provided)
Six CEL functions: has_disability(), is_severe_disability(), household_has_pwd(), household_pwd_count(), disability_severity(), needs_reassessment()
DCI data object mapping (DO.DR.01–05) with vocabularies under urn:dci:cd:dr:01 through urn:dci:cd:dr:04
spp_dci_client_dr queries external Disability Registries with local caching, sync status, and Ed25519/RSA-256 callback verification

SP-MIS (Social Protection Management Information System)

SP-MIS is the full-stack deployment bundle for managing social protection programmes end-to-end. It is the recommended starting point for national deployments, combining the registry, eligibility engine, entitlements, payments, and event data collection into a single cohesive system — while retaining the modular architecture that allows components to be replaced or extended.

Installs registry, area, security, vocabulary, consent, change requests, CEL, Studio, API, and DCI client modules in one step
Eight pluggable manager types per programme: eligibility, deduplication, notification, programme, cycle, entitlement, payment, compliance
CEL-based eligibility engine compiles targeting rules to SQL — configurable via Studio without code changes
Async job queue for batch operations exceeding 200 records; cycle locking prevents concurrent processing races
Demo module ships with 6 programmes, 12 personas, all 11 CR types in various states, and pre-activated Logic Packs
Design targets: <100 ms single record, <500 ms search, 10k enrolments in <10 minutes

DRIMS (Disaster Response Inventory Management System)

DRIMS manages the full lifecycle of emergency relief supplies — from donation intake through dispatch and proof-of-delivery — linked to hazard incidents and geographic areas. It is designed for humanitarian operations where stock visibility, donor accountability, and OCHA reporting are required alongside the social protection functions of the platform.

Donation tracking with inspection, lot/batch/expiry management, and multi-donor coordination
Multi-tier request approval with SLA monitoring; dispatch generates waybills with proof-of-delivery tracking
OCHA cluster integration (food security, health, WASH, shelter, etc.) with personnel directory and 4W reporting
Stock health indicators (critical/warning/good) with configurable thresholds; automatic low-stock and expiry alerts
KPI hybrid architecture: cheap counts as computed fields, expensive aggregates via spp.data.value with 15-minute async refresh
Sri Lanka demo data included (spp_drims_sl, spp_drims_sl_demo)

Grievance Redress Mechanism (GRM)

The GRM provides a structured, auditable channel for beneficiaries and other stakeholders to raise complaints and track their resolution. It supports multi-channel intake, SLA monitoring, and escalation to case management — and is integrated with the registry and programme modules so that benefit-related grievances are handled in context.

Auto-ticket creation from email aliases; portal at /my/tickets for beneficiary self-service
Stage-based workflow with per-stage access control, approval requirements, and decision enforcement
SLA auto-computed from category/subcategory defaults; CEL-based escalation rules via spp_grm_cel
Structured decisions: upheld, partially upheld, rejected, withdrawn, redirected, referred to case management
Sensitivity levels (standard, sensitive, highly sensitive) control visibility and handling
Integrates with registry (registrant-linked tickets), programmes (benefit grievances), and case management (escalation)

Case Management

Case Management supports structured social worker intervention for individuals, households, or groups — from intake through closure. It is built around configurable case types and intensity levels, with risk scoring, versioned intervention plans, and supervisor oversight, suitable for both regular caseloads and emergency response.

Case types with default intensity (L1/L2/L3), priority (low–urgent), and client type (individual/household/group)
Risk factors with severity weights; auto-classification into low/medium/high/critical based on score
Versioned intervention plans with approval; individual interventions track status and progress
Activities: structured visits, confidential case notes, external referrals with status tracking
Automated review scheduling via cron with next-review-date tracking and reminders
GRM escalation linking, programme benefit coordination, and CEL-based triage/assignment rules

Programs & Entitlements

The programmes module manages the full membership and distribution lifecycle for social protection interventions — cash and in-kind — with a pluggable manager architecture that allows each programme to configure its own eligibility, deduplication, payment, and compliance logic independently.

Entitlement lifecycle: draft → pending_validation → approved → trans2FSP → rdpd2ben (plus rejection/expiry states)
Cash: fund availability check before approval, ERN generation, transfer fee tracking, validity period enforcement
In-kind: triggers _action_launch_stock_rule() on approval for automatic procurement and warehouse operations
Cycle-based recurring distribution with per-cycle membership, compliance verification, and batch payment processing
Graduation criteria and exit workflows for time-bound programmes; session/training attendance for CCT compliance
Service point management for physical and virtual delivery; bank account management with IBAN computation

Change Requests

Change Requests are the controlled mechanism for modifying registry data after initial enrolment — covering everything from simple field edits to group splits and duplicate merges. The system supports both automated field mapping and human-applied strategies, with conflict detection and duplicate prevention built in.

Three apply strategies: field_mapping (auto-transfer), custom (Python method), manual (human-applied)
Conflict detection rules evaluate at registrant/group/field/custom scope with block/warn/log actions
Duplicate detection within configurable time window (default 48 h) with similarity threshold and optional auto-merge
Three-stage UI: details → documents → review; dynamic approval routing selects workflow based on modified field
Event-sourced CRs trigger automatically when ODK/KoBoToolbox/API data differs from existing records
Studio-editable types (is_studio_editable) vs. system types with locked_reason protection

GIS & Spatial Data

The GIS module adds PostGIS-backed spatial capabilities to the platform — interactive maps, coordinate-based area resolution, and OGC-compliant feature endpoints — without exposing individual-level data through geographic interfaces. All geographic outputs are aggregated and k-anonymity enforced before leaving the system.

find_by_coordinates() resolves a GPS point to the most specific containing area in one indexed SQL query
Choropleth visualisation with 15 colour palettes (Viridis, Plasma, Cividis, and others); classification methods: quantile, equal interval, manual breaks
Geographic reports with template wizard, area aggregation, normalisation (per km², per 1k pop, z-score, percentile), and hierarchical rollup
GeoJSON API at /api/v2/GISReport/<code>/geojson with cached data and scheduled job-queue refresh
OGC API Features Core (Part 1) + GovStack GIS BB conformance; thin-client architecture returns aggregates only, never PII
Export endpoints: GeoPackage for offline use, GeoJSON, QML style files for QGIS
Demo boundary data for Philippines, Sri Lanka, and Togo

Analytics, Metrics & Indicators

The analytics module provides a unified aggregation service across configurable scopes and demographic dimensions, with privacy enforcement built into the computation layer rather than applied as an afterthought. It feeds dashboards, GIS choropleth maps, and API endpoints from a single computation path.

spp.analytics.service.compute_aggregation() single entry point; up to 3 groupby dimensions simultaneously
Scope types: CEL expression, area (with child inclusion), area tags, GeoJSON polygon, lat/long buffer, explicit IDs
K-anonymity threshold configurable 1–100 per access rule; complementary suppression prevents re-identification via differencing
Fairness analysis (equity scores, disparity ratios), distribution statistics (Gini, Lorenz curve, percentiles)
Result caching with per-scope-type TTL and manual invalidation; dimension caching for repeated CEL evaluations
Publishable indicators based on CEL variables feed dashboards, GIS choropleth maps, and API endpoints

Scoring & Targeting

The scoring module supports PMT, Social Welfare Development Indices, and custom formulas, with version control and a simulation engine that lets programme managers evaluate targeting scenarios — coverage, exclusion errors, budget trade-offs — before any rules go live.

Scoring models with indicators, weights, field path mappings, and threshold-based classification (e.g., extremely poor / moderate / non-poor)
Version control with effective dates and scheduled activation — prepare new models without downtime
Batch scoring via queue_job with strict mode (fail on missing required indicators) and expected weight validation
Per-indicator breakdown in spp.scoring.result.detail: raw value, weight, weighted contribution, value snapshot
Simulation engine evaluates coverage, exclusion error, and budget trade-offs with results via REST API
Programme eligibility bridge integrates scoring results as CEL variables for targeting rules

Events & Documents

The events module records structured data from surveys, field visits, and external integrations — ODK, KoBoToolbox, and generic APIs — with a configurable lifecycle and automatic change request generation when incoming data conflicts with existing records.

Event types configure category (survey/visit/sync/manual), target type, source type, and data storage mode (dedicated model, JSON, custom fields)
State machine: draft → pending → active → superseded/expired/cancelled; auto-supersede replaces previous active events
External source connectors: ODK Central (form/project/server config), KoBoToolbox (field mapping), generic API
Automatic CR generation when incoming event data differs from existing registrant records
Document management with structured directory trees, integrity checksums, and per-programme/registrant-type custom fields
Scheduled cron expires events after configurable days; approval workflow via spp_approval mixin

Alerts & Hazard Management

The alert engine monitors thresholds, expiry dates, and deadlines across any model in the system, with daily evaluation, duplicate prevention, and a visual rule builder. The hazard module connects disaster events to geographic areas and programmes, enabling disaster-responsive social protection such as automatic top-up payments in affected areas.

Two rule types: numeric threshold (with comparison operators) and date/deadline (days-before window)
Alert lifecycle: active → acknowledged → resolved; auto-reference format ALR-YYYY-NNNNN
Priority levels (low/medium/high/critical); kanban view grouped by state for operations teams
Duplicate prevention skips records with existing active/acknowledged alerts
Hazard incidents link to geographic areas and programmes for emergency response
Pre-installed alert types: threshold, expiry, deadline, manual, system

Studio (No-Code Configuration)

Studio is the configuration layer that lets programme designers and business analysts build and modify eligibility rules, registry extensions, and programme logic without writing code. The governance model — with draft/approval/publish/archive states for all expressions — ensures that changes are reviewed and versioned before they affect live programmes.

Expression governance: draft → pending approval → published → archived; versioning with scheduled activation dates
Custom field builder: text, long_text, integer, decimal, date, datetime, boolean, selection, multi-select, link — with conditional visibility and placement zones
13 Logic Packs: cash transfer, PMT targeting, child benefit, social pension, disability assistance, CCT, vulnerability assessment, geographic targeting, GMI, public works, benefit adjustments, exclusion criteria, OVC support
Testing framework with personas and expected-outcome assertions validates logic before publishing
No-code builders for custom CR types and event data collection forms
API bridge (spp_studio_api_v2) auto-exposes custom fields and variables to REST API

CEL (Common Expression Language)

CEL is the expression language used throughout OpenSPP for eligibility rules, entitlement calculations, and filtered queries. Its SQL-first execution model means that expressions written by programme staff compile to optimised database queries, allowing the same logic to run against millions of records without application-layer bottlenecks.

Collection operations: members.count(m, cond), members.exists(m, cond), members.sum(m.field, cond), members.avg(), members.min(), members.max()
Variable sources: model field, external API, scoring result, vocabulary concept, computed (CEL), constant, member aggregate
Caching strategies per variable: none, session, TTL-based, manual refresh; period granularity: current, daily, monthly, quarterly, yearly, snapshot
Built-in functions: age_years(), between(), today(), months_ago(), has(), matches() (with 1 s regex timeout), size()
YAML-based profile extension: any module contributes symbols, functions, and constants via data/cel_profiles.yaml
Security: function whitelisting, parameterised SQL generation, ORM record rule injection in all subqueries

HXL (Humanitarian Exchange Language)

HXL integration tags exported data with HXL 1.1 hashtags and attributes so that outputs from OpenSPP are immediately compatible with humanitarian data exchange standards and tools. Mappings are bidirectional, supporting both export formatting and import-time field mapping.

HXL tag registry with hashtags and attributes; composed tags validated (hashtag starts with #, attributes with +)
Export profiles with dot-notation field paths, date format configuration, and manual or structured HXL tag assignment
CEL variable HXL mapping: import actions (map to field, create event, store as variable, skip) and export inclusion flags
Area-level HXL import and aggregation for humanitarian indicators and needs assessments

API & Interoperability

The REST API v2 provides a standards-compliant interface for external systems to read and write registry, programme, and entitlement data. It is designed for government-to-government integration scenarios where authentication, consent enforcement, and audit trails are regulatory requirements rather than optional features.

Identifier format: {system}|{value} (e.g., urn:openspp:id-type:national_id|12345); _elements for field filtering, _extensions for custom field loading
Consent enforcement: scoped API clients, organisation-type consent gating, field-level filtering, timing jitter against user enumeration
/$batch bundles multiple operations; /$bulk handles large imports; POST /{Resource}/search for CEL/domain queries
spp.api.extension model exposes Studio custom fields with optional JSON Schema; auto-install bridges for change requests, cycles, entitlements, products, service points, vocabulary
API client credentials use scrypt hashing (memory-hard, GPU-resistant); audit log tracks all operations
Source tracking records provenance (API, import, manual, external tool) per record for data quality auditing

DCI (Digital Convergence Initiative)

OpenSPP implements both the client and server sides of the DCI protocol, enabling it to query and serve data to other DCI-compliant systems in a national digital public infrastructure stack. Three connectors ship out of the box for the most common integration scenarios.

spp_dci_client: base infrastructure with httpx, OAuth2, and data source management
spp_dci_server: FastAPI routers with sender registry, transaction tracking, subscription management, and job queue integration
CRVS connector queries birth/death/marriage events; IBR connector performs identity verification and duplicate detection
DR connector queries disability status from external registries with local caching (synced / stale / error states)
Async callback pattern with signature verification on incoming responses (Ed25519 or RSA-256 via JWKS endpoints)
Birth verification demo: automated CRVS query for child benefit enrolment eligibility

Identity, Security & Compliance

Security and compliance capabilities are implemented as first-class platform features rather than add-ons — field-level encryption, antivirus scanning, multi-backend audit trails, and ISO-aligned consent management are all available out of the box and are on by default in recommended deployment configurations.

Pluggable encryption providers; JWKS distribution endpoint for key exchange; HSM/SoftHSM support
Audit module: per-model field tracking for create/update/delete/state changes; parent rule linking aggregates related changes
Tamper resistance: configuration changes always logged to non-database backends that cannot be silently disabled
Consent lifecycle: requested → given → renewed/refused/withdrawn/expired/invalidated; consent_summary JSON cache on res.partner
Privacy notice → consent record pattern: notice defines legal scope, consent must be a subset (informed consent enforcement)
MOSIP Claim 169 QR code identity credentials; import matching for cross-source deduplication

Infrastructure

Built on Odoo 19

OpenSPP extends Odoo 19 (Community Edition via OCA/OCB) with 90+ modules. The platform leverages Odoo's ORM, web framework, and module system while replacing its branding, theming, and URL routing with OpenSPP-specific equivalents. OCA dependencies include server-tools, server-ux, server-backend, and rest-framework.

Background Processing

A dedicated job worker process runs in a separate container from the web server, handling long-running operations — batch imports, bulk entitlement calculations, geographic boundary updates, scoring jobs, alert evaluation — in configurable batches (typically 5,000–10,000 records) with automatic retry and error logging. Cycle locking prevents race conditions during concurrent processing.

Branding & Theming

Full white-labelling via spp_branding_kit: custom system name, logos, documentation and support URLs, email signatures, report headers/footers, and telemetry control. Odoo promotional elements are disabled automatically on install. The OpenSPP theme (theme_openspp_muk) provides consistent styling with light and dark mode support.

URL Routing

User-friendly URLs via a route controller in spp_branding_kit that maps /openspp/<path> to Odoo's internal /odoo/<path> routing (e.g., /openspp/programs, /openspp/individuals, /openspp/change-requests). Both /odoo/ and /openspp/ prefixes remain functional for compatibility.

Optional Services

ClamAV antivirus — File upload scanning with quarantine, enabled via Docker Compose profile.

PRISM frontend — WFP crisis data visualisation, available as an optional integration.

OpenSPP v2.0.0 (Biliran)