# Domain Model

**PURPOSE:** Defines the core entities of the system, their characteristics, and their conceptual relationships. This file answers "what exists in the system?" — it contains zero implementation details.

> **Constraints and lifecycle rules governing these entities:** `03_BUSINESS_RULES.md`
> **Database representation of these entities:** `../../04_DATABASE/01_TABLES.md`

---

## Admin

The person authorized to access the system, enter data, manage contracts, and view analytics.

**Characteristics:**
- Has login credentials (email + password)
- Assigned roles and permissions via RBAC
- Stored separately from clients

**Relationships:**
- Belongs to Roles
- Has Permissions (via roles)

---

## Client (Unified Entity)

A single entity representing all human parties in the system. Role is determined dynamically via flags.

**Why Unified?**
- A single person can be Customer AND Agent AND Investor simultaneously
- Avoids data duplication across separate tables
- Simplifies referral tracking (agent brings customer)

**Shared Attributes:** name, phone, avatar, description

---

### Customer

A person who purchased a product via installment, or could purchase in the future, or has completed all payments.

> **Flag assignment timing:** `03_BUSINESS_RULES.md` → BR-001-4
> **Reference Number format:** `CUS-XXXXXXXXXX` (10 digits, leading zeros)

---

### Agent

A person who brought a customer to the company.

> **Flag assignment timing (explicit conversion or safety measure via contract):** `03_BUSINESS_RULES.md` → BR-001-5
> **Reference Number:** Uses the unified `CUS-XXXXXXXXXX` format

---

### Investor

A person who owns shares (or previously owned shares) in the company.

**Key Rules:**
- Investor status requires at least 1 share to be added — a person cannot be "registered as investor" without owning shares
- Investor status is permanent — never removed, even if all shares are withdrawn later
- An existing client (customer, agent, or both) can be converted to investor
- A client who already has investor status cannot be converted again

> **Reference Number:** Uses the unified `CUS-XXXXXXXXXX` format
> **Full creation rules:** `03_BUSINESS_RULES.md` → BR-001-8

---

## Contract

An installment agreement between the company and a customer for a specific product.

**Relationships:**
- Belongs to one Customer (required)
- Belongs to one Agent (optional)
- Has many Installments
- Has many Payments
- Has many Audit Logs

> **Reference Number format:** `CTR-XXXXXXXXXX` (10 digits, leading zeros)
> **Lifecycle rules:** `03_BUSINESS_RULES.md` → BR-002-1 through BR-002-8

---

## Installment

A single scheduled payment within a contract.

**Characteristics:**
- Pre-generated upon contract creation (not calculated dynamically)
- Has a fixed due date that never changes
- Has a fixed amount (all installments in a contract have equal amounts)
- Status: pending, overdue, or paid

**Relationships:**
- Belongs to one Contract
- May be linked to one Payment

> **Rules:** `03_BUSINESS_RULES.md` → BR-003-1 through BR-003-5

---

## Payment

A financial transaction recorded in the ledger.

**Types:**
- `company_payout` — Money paid by company to supplier
- `initial_payment` — Down payment from customer
- `installment_payment` — Monthly installment payment

**Relationships:**
- Belongs to one Contract
- Linked to one Installment (only for `installment_payment` type — this link is the sole source of truth for which payment settled which installment)

> **Rules:** `03_BUSINESS_RULES.md` → BR-004-1 through BR-004-9

---

## Audit Log

An immutable record of all financial events with independent narrative text.

**Characteristics:**
- Narrative text is self-contained — it does not depend on the payments table for any data
- Records create, update, and delete actions
- Deleted along with the contract if the contract is a cancelled draft (no history for cancelled drafts)

**Relationships:**
- Belongs to one Contract
- Optionally linked to one Payment (link breaks on payment deletion, becoming null)

> **Narrative independence rule:** `03_BUSINESS_RULES.md` → BR-004-9

---

## Shares Log

A historical record of share movements for investors.

**Types:** `add` (positive), `withdraw` (negative)

**Statuses:**
- `active` — Counted in balance calculation
- `modified` — Excluded from calculation (record was edited)
- `deleted` — Excluded from calculation (record was logically deleted)

**Key Fields:**
- `shares_count` — Always positive; the type (add/withdraw) determines the sign
- `acquisition_date` — The date the investor acquired the shares (may differ from the system record date)

**Relationships:**
- Belongs to one Client (who must have investor status)

> **Rules:** `03_BUSINESS_RULES.md` → BR-005-1 through BR-005-10

---

## Notification Template

A text template with dynamic variables for message generation.

**Standalone:** No relationships to other entities.

**Types:** `overdue`, `due_soon_1day`, `due_later`, `paid_receipt`