# Comprehensive Project Proposal: Khandan (خاندان)

A Private, Unified, Clan-Centric Relational, Financial, and Testamentary Platform.

---

## 1. Executive Summary
**Khandan (خاندان)** is a highly secure, private web application designed to act as the digital anchor for a lineage (clan). Unlike general-purpose social networks, Khandan is completely self-hosted, private, and integrates three critical pillars of family continuity:
1. **Relational History & Genealogy:** An interactive family tree linked to rich social profiles and memoirs.
2. **Cooperative Finance:** An internal family fund (Qard al-Hasan) and emergency assistance pool.
3. **Estate & Legacy Management:** Secure, encrypted wills and a digital safety deposit box that auto-delivers credentials and assets to heirs under predefined conditions.

Built with **pure PHP and zero external CSS/JS libraries**, the application is lightweight, responsive, offline-ready (PWA), and designed to last across generations without dependency rot.

---

## 2. Problem Statement
Extended families face three primary threats to their unity and continuity over generations:
- **Spiritual & Historical Decay:** The oral histories, recipes, old letters, and wisdom of grandparents are lost when they pass away. Public social networks are cluttered and do not categorize family heritage.
- **Financial Disconnection:** Families lack unified cooperative savings programs. Traditional banking does not cater to interest-free internal family lending or anonymous emergency aid.
- **Estate & Probate Chaos:** Settling an estate in courts or notary publics is slow and stressful. Wills are lost, inheritance shares are disputed, and digital assets (crypto keys, online profiles, accounts) vanish because heirs do not have access to passwords.

---

## 3. The Unified Solution: Pillars of Khandan

Instead of separate, fragmented systems, Khandan unifies all features into a cohesive, private social ecosystem centered around the family tree and personal profiles.

```
                  +--------------------------------+
                  |      Dynamic Family Tree       |
                  |     (Genealogical Core)        |
                  +---------------+----------------+
                                  | (Click Node)
                                  v
                  +--------------------------------+
                  |         Member Profile         |
                  | (Oral History, Health, Legacy) |
                  +-------+---------------+--------+
                          |               |
          +---------------+               +---------------+
          v                                               v
+-----------------------+                       +-----------------------+
|  Private Clan Feed    |                       | Financial & Legal Hub |
| - Travel Logs         |                       | - Family Fund         |
| - Recipe Archives     |                       | - Emergency Assistance|
| - Video Assemblies    |                       | - Wills & Crypto Vault|
+-----------------------+                       +-----------------------+
```

### Pillar A: Relational & Historical Core
- **Interactive SVG Family Tree:** A dynamic visualization where users can zoom, pan, and drag-and-drop connections. It maps generations (alive and deceased) and handles complex relationships (spouses, multiple marriages, adoptions).
- **Dynamic Profiles:** Clicking a node in the tree opens that member's social profile.
  - **For the Living:** Displays their biography, timeline, achievements (Wall of Fame), and private health history.
  - **For the Deceased:** Transitions into a **Memorial Guestbook**, displaying their oral biography, voice/video files, and a GPS-enabled grave locator.

### Pillar B: Unified Social Feed & Shared Archives
Instead of individual modules, family activities are aggregated in a private social feed categorized by hashtags:
- `#اسناد_قدیمی` (Old Document Archives): Digitized old letters, marriage contracts, and historical records.
- `#سفرنامه` (Travel Journals): Collaborative diaries and photo logs of family trips.
- `#دستور_پخت` (Family Recipes): Traditional recipes passed down through generations, with video tutorials.
- `#فیلم_مجلس` (Past Assembly Registry): Storing long-form videos of reunions, weddings, and memorial gatherings.

### Pillar C: Legal & Testamentary Vault
- **Multimedia Wills:** Members can record audio/video testaments or type written wills, signed digitally. These are stored securely and remain locked until verified by the Patriarch.
- **Smart Inheritance Calculator:** Fully integrated with the active family tree. Using rules from Iranian Civil Law, it automatically calculates the exact inheritance shares (first, second, and third degree heirs) of a deceased member's estate.
- **Digital Safety Deposit Box:** A secure vault where members store encrypted credentials (users/passwords), cryptographic private keys, OTP credentials, and title deeds. Using AES-256 encryption, these are automatically decrypted and delivered to designated heirs upon proof of death or administrative trigger.

### Pillar D: Cooperative Financials & Governance
- **Family Fund (صندوق قرض‌الحسنه):** A transparent ledger managing monthly contributions, micro-loan queues, and interest-free loan distributions.
- **Emergency Assist (صندوق همیاری):** A secure, anonymous sub-fund where members can request emergency aid, which is funded by voluntary donations from other members.
- **Dispute Arbitration (شورای حل اختلاف):** A private panel of family elders (ریش‌سفیدان) where disputes (over loans, estate, or relations) can be registered, debated, and resolved confidentially.
- **Internal Proxy Voting:** If a member cannot attend family decisions or fund votes, they can digitally assign their vote to another relative via an internal Power of Attorney.

---

## 4. Technical Architecture
Khandan is built with strict architectural guidelines to ensure long-term stability and security:
- **No External Packages:** Writing custom CSS (with variables and backdrop-filters) and vanilla Javascript (for dragging nodes and recording media) ensures zero dependency rot.
- **PDO SQLite Layer:** Uses a single `khandan.db` file, which is highly portable, lightweight, and easy to backup or transfer.
- **End-to-End Encryption:** Vault items are encrypted server-side using AES-256-CBC via PHP's `openssl` functions, using a key derived from the user's secret passcode and database salt.
- **PWA Capabilities:** Service worker caching allows family members to access the shajareh and read profiles offline. It can be installed as a standalone app on iOS and Android.

---

## 5. Security & Permission Matrix
The app defines three primary roles to ensure privacy:
1. **Patriarch (پدر خاندان):** Initializes the tree, creates invitation PINs, confirms relationships, approves loan allocations, and acts as the legal registrar for death triggers.
2. **Active Member (عضو فعال):** Can post to the feed, contribute to funds, request loans, manage their own digital vault, and draft their testament.
3. **Deceased Member (مرحوم):** Node lock is activated. The system freezes the account, opens the Memorial page, and automatically initiates the Digital Vault release protocols.