# Kampong Speu Provincial Demographic Management System (KSP-DMS)
## Master Project Plan (English Edition)

**Document Reference:** KSP-DMS-DOC-MP-EN-01  
**Classification:** Official Proposal & Master Technical Blueprint  
**Jurisdiction:** Kampong Speu Province, Kingdom of Cambodia  
**Version:** 1.0 (Draft Proposal)  
**Author:** Antigravity Engineering Architecture Team  
**Date:** November 2026  

---

## 1. Background and Project Justification

Kampong Speu Province is a strategically significant province located in southwestern Cambodia, functioning as an economic, agricultural, and industrial corridor connecting Phnom Penh to the deep-sea port of Sihanoukville. The province comprises eight administrative districts and municipalities:
1. Chbar Mon Municipality (ក្រុងច្បារមន)
2. Basedth District (ស្រុកបាសិត)
3. Kong Pisei District (ស្រុកគងពិសី)
4. Aoral District (ស្រុកឱរ៉ាល់)
5. Oudong Me Chey Municipality / Samaki Meanchey District (ស្រុកឧដុង្គម៉ែជ័យ / សាមគ្គីមានជ័យ)
6. Phnom Sruoch District (ស្រុកភ្នំស្រួច)
7. Samraong Tong District (ស្រុកសំរោងទង)
8. Thpong District (ស្រុកថ្ពង)

Rapid industrialization, factory expansion along National Highway 4, and seasonal agrarian migrations have significantly increased demographic velocity within the province. Currently, village administration records household demographic data using conventional physical ledgers (such as physical family books and commune logbooks). This decentralized, paper-first recording produces substantial administrative challenges:
- **Transmission Latency:** Statistics take weeks or months to trickle upwards to commune, district, and provincial planners.
- **Data Inconsistencies:** Discrepancies between village tallies and civil registration data due to double-counting or unrecorded migrations.
- **Vulnerability to Physical Loss:** Ledgers are susceptible to humidity, water damage, fire, and wear.
- **Inability to Perform Spatial Planning:** Provincial authorities lack real-time thematic demographic maps to plan healthcare, infrastructure, education, and social safety nets.

KSP-DMS directly resolves these challenges by introducing a sovereign, local-first, privacy-by-design provincial information system tailored to the administrative hierarchy of the Kingdom of Cambodia.

---

## 2. Vision, Mission, and Core Objectives

### 2.1 Vision
To establish Kampong Speu as a premier model of digitized provincial governance in Cambodia through timely, accurate, transparent, and privacy-preserving demographic intelligence.

### 2.2 Mission
To provide grassroots administrators (from village chiefs to provincial directors) with an intuitive, bilingual, offline-resilient digital platform that standardizes household registration, tracks vital events, safeguards citizen privacy, and empowers evidence-based socio-economic development.

### 2.3 Strategic Objectives
1. **Digitize Household & Person Registries:** Maintain accurate, auditable digital records of all households and resident individuals across all 8 districts of Kampong Speu.
2. **Standardize Life Event Tracking:** Streamline the reporting of births, deaths, in-migrations, and out-migrations with cryptographic-grade audit logging.
3. **Enforce Hierarchical Four-Eye Approval:** Institute a multi-tier review workflow ensuring data integrity from Village Collector -> Commune Reviewer -> District Reviewer -> Provincial Administrator.
4. **Deliver Spatial Intelligence:** Provide dynamic GIS thematic heatmaps down to the commune level without exposing private household coordinates or identities.
5. **Ensure Sovereign, Secure Local Operations:** Build on standard open-source technologies (PHP/Laravel, MySQL/MariaDB, Linux/Windows XAMPP) capable of autonomous operation during network isolations.

---

## 3. Project Scope and Explicit Exclusions

### 3.1 In-Scope Capabilities
- **Geographic Hierarchy Management:** Configurable administrative division modeling (Province -> District -> Commune -> Village) with synthetic reference baseline data.
- **Household & Citizen Registry:** Normalized tracking of households (physical dwelling, head of household) and members (kinship, age, gender, residency status).
- **Vital Demographic Events:** Recording and workflow verification of births, deaths, and domestic migrations.
- **Hierarchical Approval Workflow:** Multi-step submission batches with status transitions (`draft`, `submitted`, `verified`, `approved`, `rejected`).
- **Data Quality Engine:** Automated detection of anomalous records (e.g., duplicated names, impossible birthdates, orphaned minors).
- **Audit & Governance Logging:** Tamper-evident recording of every create, update, and delete operation with user identity and timestamp.
- **GIS Thematic Map Visualizer:** Interactive Leaflet map displaying commune/district demographic densities using synthetic GeoJSON boundaries.
- **REST API v1:** Standardized JSON endpoints protected by Laravel Sanctum tokens for secure mobile sync.
- **Bilingual Interface:** Full localization in Khmer (ភាសាខ្មែរ) and English.

### 3.2 Explicit Project Exclusions
- **No National Production ID Integration:** The prototype does not connect to the national identification database or Ministry of Interior production servers.
- **No Real Personal Citizen Data:** Only synthetic Cambodian-style demo data is used throughout development and testing.
- **Education & Employment Tracking Disabled:** Detailed employment history and academic micro-tracking are intentionally disabled in the core schema until formal legal directives and privacy decrees are enacted.
- **No Exact Geolocation of Citizens:** GPS coordinates of individual citizen dwellings are strictly forbidden; spatial analytics operate exclusively at aggregated commune/village boundaries.

---

## 4. Stakeholder Analysis and Organizational Matrix

| Stakeholder Group | Primary Role & Responsibilities | Key Interests | Engagement Strategy |
| :--- | :--- | :--- | :--- |
| **Provincial Governor & Board** | Executive sponsorship, provincial demographic policy, budget sanction. | Accurate provincial statistics, evidence-based resource allocation. | Bi-weekly executive dashboard briefings and quarterly milestones. |
| **Provincial IT Department** | Local infrastructure management, server maintenance, backup enforcement. | System reliability, data security, ease of maintenance. | Joint technical architecture design and administrator training. |
| **District Administration Offices** | Supervision of commune submissions, cross-commune validation. | Timely district reports, discrepancy resolution. | Structured review workflows and regional workshop training. |
| **Commune Councils (ឃុំ/សង្កាត់)** | Review and verification of village-level demographic entries. | Simplicity of workflow, formal record verification. | Khmer-first user interface and hands-on tablet/desktop training. |
| **Village Chiefs (មេភូមិ)** | Primary grassroots data collection, initial event notice recording. | Low barrier to entry, offline support, zero English requirement. | Icon-rich Khmer mobile/web data entry and peer-support networks. |
| **Data Protection Officer** | Privacy auditing, compliance monitoring, access control oversight. | Citizen privacy, least privilege enforcement, audit integrity. | Dedicated audit trail views and automated anomaly alerting. |

---

## 5. Functional and User Requirements

### 5.1 User Requirements (UR)
- **UR-01 (Bilingual Switching):** Any user can toggle between Khmer and English instantly without page reload latency or lost form state.
- **UR-02 (Geographic Confinement):** A user logged in as a Commune Reviewer for Chbar Mon must never view or edit records belonging to Basedth District.
- **UR-03 (Drafting & Submission):** Village data collectors can prepare batches of demographic changes offline or in draft state before submitting them for formal review.
- **UR-04 (Traceability):** Any modification to a citizen's household status must record who initiated the change, who approved it, and the date/time of approval.

### 5.2 Functional Requirements (FR)
- **FR-GEO-01:** System must maintain hierarchical tree structure of Provinces, Districts, Communes, and Villages with soft deletion.
- **FR-HH-01:** System must enforce exactly one active Head of Household per registered household unit.
- **FR-EVT-01:** Recording a death event must automatically mark the person record as deceased and log the departure from the active household member list.
- **FR-WF-01:** Submissions must follow the state machine: `draft` -> `pending_commune` -> `pending_district` -> `approved` or `rejected`.
- **FR-REP-01:** Generate tabular and graphical population pyramids (male vs. female across 5-year age cohorts) exportable to CSV/PDF.
- **FR-GIS-01:** Render choropleth population density overlays on Leaflet without transferring individual citizen coordinates to the browser client.

---

## 6. Non-Functional Requirements (NFR)

- **Performance (NFR-01):** Page load times under 1.5 seconds on local intranet connections; API responses under 250ms for paginated datasets.
- **Security (NFR-02):** Bcrypt password hashing, CSRF tokens on all state-changing web requests, PDO prepared statements for 100% of SQL interactions, rate limiting at 60 requests/minute on public API endpoints.
- **Reliability & Availability (NFR-03):** 99.5% uptime target on local server environments; daily automated database dumps.
- **Usability (NFR-04):** Adherence to WCAG 2.1 AA accessibility guidelines, native rendering of Khmer Unicode fonts without clipping subscripts (ជើងអក្សរ).
- **Maintainability (NFR-05):** Clean Laravel modular monolith pattern, PSR-12 code compliance, and complete unit/feature test coverage.

---

## 7. Technical and Database Architecture

### 7.1 Technology Stack
- **Operating System:** Microsoft Windows 11 / Windows Server (Local-first deployment).
- **Web Server:** Apache 2.4 (via XAMPP).
- **Backend Framework:** Laravel 10.x LTS / 11.x (PHP 8.2).
- **Database Engine:** MySQL / MariaDB 10.4.32 (InnoDB engine, utf8mb4 collation).
- **Frontend Stack:** Laravel Blade templates, Bootstrap 5.3, Vite asset compilation.
- **Spatial Visualization:** Leaflet JS v1.9 + GeoJSON boundary layers.
- **API Engine:** Laravel Sanctum token-based authentication (v1 REST endpoints).

### 7.2 Database Schematics & Normalization
The database schema is fully normalized to Third Normal Form (3NF) to eliminate data redundancy while maintaining audit fidelity:
- `provinces`, `districts`, `communes`, `villages` (Geographic hierarchy).
- `households`, `persons`, `household_members` (Demographic core).
- `birth_events`, `death_events`, `migration_events` (Vital statistics).
- `data_submissions`, `data_submission_items` (Workflow queue).
- `audit_logs`, `data_quality_issues`, `system_settings` (Governance).

---

## 8. Privacy, Security, and Sovereign Data Governance

### 8.1 Least Privilege and Geographic Isolation
Security is enforced using multi-layered middleware and model scopes:
1. **Role Scope:** Super Admin, Provincial Admin, District Reviewer, Commune Reviewer, Village Collector.
2. **Geographic Scope:** Every database query automatically appends the user's assigned administrative boundary constraint (`where village_id = ?`, etc.).
3. **No Direct URL Tampering:** Any attempt by a commune reviewer to inspect another commune's ID via URL parameter tampering results in an immediate HTTP 403 Forbidden response and an automated security audit entry.

### 8.2 Synthetic Data Covenant
To strictly prevent inadvertent exposure of private citizen information:
- All test identities use synthetically generated Khmer names (e.g., សុខ ចាន់ថា, សេង វណ្ណា, កែវ ពិសិដ្ឋ).
- All identification numbers are randomized fictional format strings (`KSP-DEMO-XXXXX`).
- Real citizen data is strictly prohibited in development, testing, and Git version control.

---

## 9. Implementation Roadmap (Indicative 20-Week Lifecycle)

```
Week: 01 02 03 04 05 06 07 08 09 10 11 12 13 14 15 16 17 18 19 20
P0:   [==]                                                           (Inspection & Baseline)
P1:      [====]                                                      (Bilingual Master Plan)
P2:           [==]                                                   (Architecture Modeling)
P3:              [==]                                                (Khmer PDF Generation)
P4:                 [====]                                           (Laravel Foundation)
P5:                      [====]                                      (Household & Person Registry)
P6:                           [====]                                 (Vital Events & Approvals)
P7:                                [====]                            (GIS, Reports & API)
P8:                                     [====]                       (Security & Automated QA)
P9:                                          [====]                  (GitHub Version Control)
P10:                                              [====]             (Handover & Pilot Launch)
```

---

## 10. Financial Budget Estimates (USD)

*Disclaimer: All financial figures are indicative planning estimates for local development and capacity building. They do not represent official government budget sanctions or contractual pricing.*

| Cost Category | Item Description | Estimated Cost (USD) |
| :--- | :--- | :--- |
| **System Architecture & Design** | Requirements engineering, bilingual documentation, database design | \$7,500 |
| **Software Engineering** | Laravel backend, Blade UI, Leaflet GIS, Sanctum REST API | \$18,500 |
| **Quality Assurance & Security** | Automated test suites, vulnerability assessments, penetration testing | \$6,000 |
| **Documentation & Translation** | Khmer/English technical manuals, user guides, PDF publication | \$4,500 |
| **Training & Capacity Building** | Workshops for provincial, district, and commune personnel (pilot) | \$7,000 |
| **Contingency Reserve** | Unforeseen technical adaptation and hardware interface tooling (10%) | \$5,000 |
| **Total Estimated Initial Project Cost** | | **\$48,500** |

### Annual Recurring Operating Expenses (OPEX)
- Local Server Maintenance & Patching: \$2,400 / year
- Backup Storage Media & Offsite Rotation: \$1,200 / year
- Technical Support & Refresher Training: \$3,600 / year
- **Total Estimated Annual OPEX:** **\$7,200 / year**

---

## 11. Risk Management Register Summary

1. **Risk: Grassroots Computer Literacy Disparity:** Addressed through simplified icon-driven Khmer UI, step-by-step video guides, and district-level support hotlines.
2. **Risk: Intermittent Electricity & Connectivity in Remote Villages:** Addressed via offline-ready batch submission architecture allowing local data caching.
3. **Risk: Data Tampering or Unauthorized Access:** Mitigated by immutable audit logs, strict geographic query scoping, and database-level foreign key integrity.

---

## 12. Acceptance Gates and Final Verification

Project milestone sign-off requires 100% completion of the following verification gates:
1. Environment and baseline inspection verified.
2. Complete bilingual documentation and verified Khmer PDF generation.
3. Clean automated test suite execution (Zero failures).
4. Full geographic isolation validation (positive and negative permission tests).
5. Codebase cleanly committed to a private GitHub repository with strict exclusion of private credentials and `.env` files.
