# Vision and Scope

**PURPOSE:** Defines what Tamkeen is, what it does, and where its boundaries lie. This file answers "what is the system?" — it contains zero implementation details.

---

## Executive Summary

"تمكين" (Tamkeen) is a comprehensive financial system designed to manage installment operations with precision and transparency. The system operates as a backend providing APIs for consumption by mobile or web applications.

**Core Differentiator:** A strict financial engine that maintains data integrity through the principle of "Append-only Ledger + Audit Log," preventing any manipulation of historical records.

---

## In-Scope Features

- **Unified Identity Management:** A single entity represents all human roles (Customer, Agent, Investor) with dynamic role assignment. A person can hold multiple roles simultaneously.
- **Contract Math Validation:** The system validates (does not calculate) installment amounts sent from external clients, preventing fractional payments.
- **Contract Lifecycle Management:** Explicit state machine (draft → active → completed) with creation, signing, draft deletion, and automatic completion.
- **Company Payout Recording:** Automatic registration of product cost upon contract creation for accounting and verification purposes.
- **Strict Payment Engine:** Exact-match payments with strict sequencing, explicit installment linking, and LIFO-only reversal.
- **Agent Shares Management:** Share tracking with dynamic investor profit calculation.
- **Financial Analytics:** Time-filtered dashboards (max 365 days) with collection and overdue tracking.
- **Customer Listing:** Sortable and filterable customer list with nearest-due-installment priority.
- **Role-Based Access Control:** Flexible permission system supporting team expansion without code changes.
- **Notification Templates:** Text generation from configurable templates (no actual message sending occurs).
- **Async Report Export:** Non-synchronous report generation for large datasets.
- **Reference Numbers:** Unique functional numbers for Customers and Contracts for paper document usage.
- **Profile Attachments:** Customer, agent, and investor profiles support avatar image upload.
- **Multi-language Support:** Arabic as default language with extensibility for additional languages.

---

## Out-of-Scope Features

- User interface (UI/UX) or Frontend applications
- Actual message sending (WhatsApp, SMS, etc.) — text generation only
- Electronic Payment Gateway for automatic collection
- Complex tax invoicing system
- Customer or Agent login portals (system is managed by admin users only)