# Software Requirements Specification (SRS)
## Kampong Speu Provincial Demographic Management System (KSP-DMS)

**Document Identifier:** KSP-DMS-DOC-SRS-01  
**Standard:** IEEE 830-1998 Compatible  
**Version:** 1.0 (Draft Proposal)  
**Date:** November 2026  

---

## 1. Introduction

### 1.1 Purpose
This Software Requirements Specification (SRS) details the complete functional and non-functional requirements for the Kampong Speu Provincial Demographic Management System (KSP-DMS). It serves as the definitive engineering contract for backend architects, frontend developers, and QA engineers.

### 1.2 Scope
KSP-DMS is a responsive web application and API engine engineered to digitize household registration, vital life event tracking, and spatial demographic intelligence across the 8 districts/municipalities of Kampong Speu Province, Kingdom of Cambodia.

### 1.3 Definitions and Acronyms
- **KSP-DMS:** Kampong Speu Provincial Demographic Management System
- **PII:** Personally Identifiable Information
- **RBAC:** Role-Based Access Control
- **Geo-Scope:** Geographic boundary access confinement
- **Head of Household (HoH):** The designated primary representative of a household unit.

---

## 2. Overall Description

### 2.1 Product Perspective
KSP-DMS is an autonomous modular monolith built with Laravel 10/11, utilizing MySQL/MariaDB for relational storage, Leaflet for GIS rendering, and Laravel Sanctum for API token management.

### 2.2 User Classes and Characteristics
1. **Super Administrator:** System deployment, configuration, database backup, role management.
2. **Provincial Administrator:** Province-wide view, final baseline approvals, executive report extraction.
3. **District Reviewer:** District-level scope, cross-commune verification, submission approvals.
4. **Commune Reviewer:** Commune-level scope, village data review, vital event verification.
5. **Village Data Collector:** Village-level scope, drafting household updates, recording event notices.
6. **Data Protection / Legal Officer:** Audit trail inspection, compliance reporting.

---

## 3. Specific Functional Requirements

### 3.1 Geographic Administration Module (GEO)
- **SRS-GEO-001:** System shall store and maintain hierarchical administrative entities:
  - Province: Kampong Speu (Code: `KSP`)
  - Districts: Chbar Mon, Basedth, Kong Pisei, Aoral, Oudong Me Chey, Phnom Sruoch, Samraong Tong, Thpong.
  - Communes: Hierarchically linked to parent District.
  - Villages: Hierarchically linked to parent Commune.
- **SRS-GEO-002:** Deletion of any geographic entity shall be soft-deleted to preserve referential historical integrity.

### 3.2 Household Registry Module (HH)
- **SRS-HH-001:** System shall assign a unique synthetic household code (e.g., `HH-KSP-BM-00001`) to each registered dwelling unit.
- **SRS-HH-002:** Each household record shall include: Village ID, Address / Street description, Household Type, Poverty/IDPoor Status (Synthetic indicator), Registration Date, and Active Status.
- **SRS-HH-003:** Exactly one active member per household shall be designated as Head of Household (`is_head = true`).

### 3.3 Person Registry Module (PER)
- **SRS-PER-001:** Each person shall have a unique system-generated identifier.
- **SRS-PER-002:** Attributes: Full Name in Khmer, Full Name in Latin/English, Gender, Date of Birth, National ID / Birth Cert No (Synthetic placeholder), Marital Status, and Relationship to Head of Household.
- **SRS-PER-003:** Persons shall be linked to a Household via `household_members` with start date, end date, and residency status (`permanent`, `temporary_absent`, `moved_out`, `deceased`).

### 3.4 Vital Events Module (EVT)
- **SRS-EVT-001 (Birth):** System shall record child details, mother ID, father ID, birthdate, birth location, and automatically create a pending addition to the target household.
- **SRS-EVT-002 (Death):** System shall record deceased person ID, date of death, cause category, and upon approval automatically update the person's status to `deceased` and close active household membership.
- **SRS-EVT-003 (Migration):** System shall record origin household/village, destination household/village, migration date, and reason category.

### 3.5 Submission & Approval Workflow Module (WF)
- **SRS-WF-001:** Submissions shall follow the state transitions:
  `DRAFT` -> `SUBMITTED_TO_COMMUNE` -> `COMMUNE_VERIFIED` -> `APPROVED_BY_DISTRICT` or `REJECTED`.
- **SRS-WF-002:** Rejections must require mandatory reviewer justification comments.
- **SRS-WF-003:** Approved submissions atomically apply staged mutations to the core registry tables within an ACID transaction.

### 3.6 Data Quality Engine (DQ)
- **SRS-DQ-001:** Automatic flag generation for:
  - Age anomalies (e.g., parent younger than child).
  - Multiple active heads of household in the same unit.
  - Active persons marked with a date of death.
  - Household units with zero active members.

### 3.7 GIS & Reporting Module (GIS/REP)
- **SRS-GIS-001:** The GIS module shall aggregate population counts by commune and render colored choropleth overlays using GeoJSON polygons.
- **SRS-GIS-002:** The system shall strictly prohibit exporting individual GPS points or street addresses via public or GIS endpoints.
- **SRS-REP-001:** Demographic pyramid generator: 5-year cohort distributions grouped by male and female.

---

## 4. Non-Functional Requirements

### 4.1 Security Requirements
- All passwords hashed using `bcrypt` (work factor >= 12).
- Protection against OWASP Top 10 vulnerabilities (SQLi, XSS, CSRF, IDOR).
- Geographic scope enforced at the database query builder level (Global Scopes).

### 4.2 Performance Requirements
- Intranet dashboard rendering < 1.0 second.
- Database index optimization for all foreign keys and frequently queried fields (`village_id`, `status`, `gender`, `created_at`).

### 4.3 Reliability & Backup
- Database backup scripts executable on demand and via scheduled task.
- Zero data corruption guarantee via foreign key constraints and InnoDB engine transactions.
