# BTM Microbanking System - Technical Specification Document

## Document Information

- **Project Name**: BTM Microbanking System
- **Version**: 2.0
- **Last Updated**: February 23, 2026
- **Document Type**: Technical Specification & Requirements
- **Target Platform**: Web Application (Laravel-based)

---

## Implementation Status Legend

| Symbol | Meaning                                    |
| ------ | ------------------------------------------ |
| ✅     | Fully implemented (Backend + Frontend)     |
| 🔧     | Backend complete, Frontend partial/pending |
| ⏳     | Planned / Not started                      |

---

## Table of Contents

1. [Project Overview](#1-project-overview)
2. [Current System Analysis](#2-current-system-analysis)
3. [Business Rules](#3-business-rules)
4. [System Architecture](#4-system-architecture)
5. [Core Modules](#5-core-modules)
6. [Supporting Modules](#6-supporting-modules)
7. [Workflows](#7-workflows)
8. [Data Migration](#8-data-migration)
9. [Reporting Requirements](#9-reporting-requirements)
10. [User Roles & Permissions](#10-user-roles--permissions)
11. [Implementation Phases](#11-implementation-phases)

---

## 1. Project Overview

### 1.1 Organization Profile

- **Entity Name**: BTM (Baitul Maal wat Tamwil)
- **Entity Type**: Cooperative (Koperasi)
- **Core Business**: Sharia-compliant savings and financing (Simpan Pinjam)
- **Primary Focus**: Micro-business financing
- **Operating Principle**: Islamic Finance (Akad Murabahah - Fixed Margin Financing)

> [!IMPORTANT]
> This system does NOT implement profit-sharing (Mudharabah bagi hasil). Instead, we use a simplified Murabahah-based financing model with a fixed 10% margin. This decision was made to reduce complexity and align with actual operational practices.

### 1.2 Current Technology Stack (Legacy)

- **Application Type**: Desktop Application (Windows-based)
- **Application Name**: IBSS (Integrated Banking System Syariah)
- **Programming Language**: Delphi
- **Database**: MySQL
- **Architecture**: Client-Server

### 1.3 Target Technology Stack ✅ Implemented

| Layer                  | Technology        | Version  | Purpose                      | Status |
| ---------------------- | ----------------- | -------- | ---------------------------- | ------ |
| **Backend Framework**  | Laravel           | 12.x     | Core application framework   | ✅     |
| **Frontend Framework** | React             | 19.x     | UI components                | ✅     |
| **SPA Layer**          | Inertia.js        | 2.x      | Laravel + React bridge       | ✅     |
| **Styling**            | Tailwind CSS      | 4.x      | Utility-first CSS            | ✅     |
| **UI Components**      | Shadcn UI         | Latest   | Accessible component library | ✅     |
| **State Management**   | Inertia           | Built-in | Server-driven state          | ✅     |
| **Authentication**     | Laravel Fortify   | 1.x      | Auth scaffolding             | ✅     |
| **Authorization**      | Spatie Permission | 6.x      | RBAC (roles/permissions)     | ✅     |
| **Testing**            | Pest              | 4.x      | Testing framework            | ✅     |
| **Database**           | MySQL             | 8.x      | Production database          | ✅     |
| **Development**        | Laragon           | -        | Local WAMP stack             | ✅     |
| **Deployment**         | aaPanel VPS       | -        | Production hosting           | ⏳     |

### 1.4 Project Goals

| Goal                                         | Status |
| -------------------------------------------- | ------ |
| Digitize manual processes                    | ✅     |
| Eliminate paper-based workflows              | ✅     |
| Create integrated system with real-time data | ✅     |
| Implement proper audit trails                | ✅     |
| Improve operational efficiency               | ✅     |
| Enable remote access for field officers      | ✅     |
| Generate automated financial reports         | ✅     |

---

## 2. Current System Analysis

### 2.1 Operational Characteristics

- **Process Type**: Heavily manual and paper-based
- **Human Intervention**: High dependency
- **Documentation**: Physical documents with limited digital backup
- **Integration Level**: Fragmented, non-integrated systems
- **Technology Adoption**: Minimal (only offline forms)

### 2.2 Current Pain Points

#### 2.2.1 Savings Module Pain Points → ✅ Resolved

| Pain Point                        | Solution Implemented                      |
| --------------------------------- | ----------------------------------------- |
| Dual entry system                 | Single digital entry with auto-journals   |
| No real-time balance visibility   | Live balance tracking                     |
| Manual calculation errors         | Automated double-entry accounting         |
| Difficult account statements      | Transaction history with filters          |
| No automated transaction receipts | Digital transaction records (PDF pending) |

#### 2.2.2 Financing Module Pain Points → ✅ Resolved

| Pain Point                     | Solution Implemented                         |
| ------------------------------ | -------------------------------------------- |
| Paper-based approval workflow  | Digital approve/reject/disburse workflow     |
| No digital tracking            | Full lifecycle status tracking               |
| Manual document archival       | Digital records linked to financing          |
| No automated payment schedules | Auto-generated 100-day installment schedules |
| Manual collectibility analysis | Automated collectibility scoring (1-5 scale) |

#### 2.2.3 Accounting Module Pain Points → ✅ Resolved

| Pain Point                            | Solution Implemented                      |
| ------------------------------------- | ----------------------------------------- |
| Limited accounting features           | Full double-entry accounting system       |
| Manual journal entries                | Auto-journals from transactions           |
| Difficult month-end closing           | Digital trial balance & reports           |
| No automated financial statements     | Trial Balance, Balance Sheet, Income Stmt |
| Disconnected from transaction modules | Integrated (savings/financing auto-post)  |

---

## 3. Business Rules

### 3.1 Membership Rules ✅ Implemented

#### 3.1.1 Member Registration

```yaml
requirements:
    - Must register as member before applying for financing
    - Minimum initial savings balance: IDR 5,000
    - Required documents:
          - KTP (National ID Card)
          - KK (Family Card)
          - Recent photo (optional)

implementation_status: '✅ Complete'
implemented_features:
    - 16-digit KTP validation
    - Cascading region selectors (Province → Regency → District → Village)
    - Member verification workflow
    - Auto savings account creation on registration
    - Search by name, ID number, phone
```

#### 3.1.2 Account Numbering System ✅ Implemented

##### Current Format (Legacy)

```
Format: XX-XXX-XXXXXX
Example: 06-100-000001
```

##### New Format (Implemented)

```yaml
structure:
    format: 'YYYY-BB-NNNNNN'
    components:
        YYYY: Year (4 digits)
        BB: Branch/Office code (2 digits)
        NNNNNN: Sequential number (6 digits)

examples:
    - '2026-01-000001'
    - '2026-01-000002'

migration_mapping:
    old_format: '06-100-000001'
    new_format: '2006-01-000001'
    logic: |
        - First 2 digits (06) → Full year (2006)
        - Next 3 digits (100) → Branch code, take last 2 digits (00 or 01)
        - Last 6 digits remain the same
```

### 3.2 Savings Product Rules ✅ Implemented

#### 3.2.1 Product Type

```yaml
product_name: 'Simpanan Sukarela (Voluntary Savings)'
characteristics:
    - Single savings product only
    - No profit sharing (no bagi hasil)
    - Voluntary deposits and withdrawals
    - No minimum balance requirement (except initial IDR 5,000)
    - No administrative fees
```

#### 3.2.2 Transaction Rules

```yaml
deposits:
    minimum_amount: 1000 # Rp 1,000 validation implemented
    maximum_amount: 1000000000 # Rp 1B validation implemented
    frequency: unlimited

withdrawals:
    minimum_amount: 1000
    maximum_amount: current_balance
    frequency: unlimited
    restrictions:
        - Cannot withdraw below minimum balance if financing is active
```

### 3.3 Financing Product Rules ✅ Implemented

#### 3.3.1 Islamic Contract (Akad Murabahah)

> [!NOTE]
> The original specification referenced Mudharabah (profit-sharing). The implementation uses **Murabahah** (fixed margin) as decided during development for simplicity and alignment with actual operations.

```yaml
akad_type: 'Murabahah (Cost-Plus Financing with Fixed Margin)'
definition: |
    Simple markup financing where:
    - BTM provides financing with known cost and fixed margin
    - Member repays in fixed daily installments
    - No profit-sharing ratio calculations
    - Margin is fixed at 10% of principal amount

decision_rationale: |
    Simplified approach chosen to:
    - Reduce implementation complexity
    - Eliminate profit distribution calculations
    - Maintain Sharia compliance (Murabahah is accepted)
    - Align with current operational practices
    - Faster development and maintenance
```

#### 3.3.2 Payment Structure ✅ Implemented

```yaml
payment_scheme:
    type: 'Flat rate daily installment'
    installment_count: 100
    frequency: 'Daily'
    margin_rate: '10% (FIXED - no variations)'

calculation_example:
    principal_amount: 10000000
    margin: 10% (1000000)
    total_repayment: 11000000
    installment_count: 100
    daily_installment: 110000

    payment_split_per_day:
        principal_portion: 100000
        margin_portion: 10000

formula: |
    total_repayment = principal_amount * (1 + margin_rate)
    daily_installment = total_repayment / installment_count

    daily_principal = principal_amount / installment_count
    daily_margin = margin_amount / installment_count

implementation_notes:
    - Sunday-skipping logic in schedule generation
    - NaN-proof calculation system
    - Installment schedule auto-generated on approval
```

#### 3.3.3 Margin Recognition (Accounting) ✅ Implemented

```yaml
method: 'Straight-line recognition over 100 days'

daily_accounting_entry:
    debit:
        - 'Kas (Cash)': 110000 (full daily payment)
    credit:
        - 'Piutang Pembiayaan': 100000 (principal reduction)
        - 'Pendapatan Margin Pembiayaan': 10000 (income)

implementation:
    - Auto journal entries on payment recording
    - Account codes: Cash (101), Financing Receivable (104), Margin Revenue (401)
    - All entries atomic via DB::transaction()
```

#### 3.3.4 Late Payment Policy ✅ Implemented

```yaml
late_payment:
    penalty_fee: 0
    late_charge: false

    consequences:
        - Late payment recorded in system
        - Member receives collectibility rating (1-5)
        - Rating affects future financing approval

    collectibility_system:
        lancar: 'No late payments (DPD = 0)'
        kurang_lancar: '1-30 days past due'
        diragukan: '31-60 days past due'
        macet: '61-90 days past due'
        loss: '>90 days past due'

    implementation:
        - Overdue installments page with search
        - Direct payment processing from overdue list
        - Collectibility auto-calculated based on DPD
```

#### 3.3.5 Financing Transaction Numbering ✅ Implemented

```yaml
format: 'Same as savings account format'
current: '06-100-000001'
proposed: 'YYYY-BB-NNNNNN'

note: |
    Each financing transaction gets unique number
    Format follows savings account numbering convention
```

### 3.4 Collector Assignment Rules ⏳ Partial

#### 3.4.1 Territory-Based Assignment

```yaml
assignment_type: 'Territory/Area-based'
default_behavior:
    - Collector A → Always assigned to Area A
    - Collector B → Always assigned to Area B

flexibility:
    - Assignments can be modified based on circumstances
    - Backup coverage when primary collector unavailable

implementation_status: |
    ⏳ Daily Collection page exists as placeholder
    Backend models ready, service/controller pending
    Territory management not yet implemented
```

#### 3.4.2 Performance Tracking

```yaml
metrics:
    - Number of members registered by employee
    - Number of financing applications brought by employee
    - Collection success rate
    - Territory coverage (Optional)

purpose: 'Employee performance evaluation'
report_frequency: 'Monthly/Quarterly'
implementation_status: '⏳ Not yet implemented'
```

---

## 4. System Architecture ✅ Implemented

### 4.1 Application Architecture

```
┌─────────────────────────────────────────────────────────┐
│                   Frontend (React 19)                    │
│  Pages → Components → Forms (Inertia.js v2)             │
│  Shadcn UI + Tailwind CSS v4                             │
└─────────────────────────────────────────────────────────┘
                          ↕
┌─────────────────────────────────────────────────────────┐
│                 Controllers (HTTP)                       │
│  Inertia responses, Form Request validation              │
│  9 controllers + Settings controllers                    │
└─────────────────────────────────────────────────────────┘
                          ↕
┌─────────────────────────────────────────────────────────┐
│                  Service Layer (Business Logic)          │
│  MemberService, SavingsService, FinancingService         │
│  AccountingService, UserService, BranchService           │
└─────────────────────────────────────────────────────────┘
                          ↕
┌─────────────────────────────────────────────────────────┐
│                     Models (Data)                        │
│  18 Eloquent models with relationships, casts, events    │
└─────────────────────────────────────────────────────────┘
                          ↕
┌─────────────────────────────────────────────────────────┐
│                   Database (MySQL 8.x)                   │
│  15+ tables with foreign keys & indexes                  │
└─────────────────────────────────────────────────────────┘
```

### 4.2 Database Design ✅ Implemented

```yaml
key_tables:
    master_data:
        - members ✅
        - users ✅
        - branches ✅
        - savings_products ✅
        - financing_products ✅
        - provinces / regencies / districts / villages ✅

    transactional:
        - savings_accounts ✅
        - savings_transactions ✅
        - financings ✅
        - financing_installments ✅
        - financing_payments ✅
        - journal_entries ✅
        - journal_entry_lines ✅

    supporting:
        - audit_logs ✅
```

### 4.3 Security Architecture ✅ Implemented

```yaml
authentication:
    method: 'Laravel Fortify'
    features:
        - Email/username + password ✅
        - Session management ✅
        - Password policies ✅

authorization:
    method: 'Role-Based Access Control (RBAC)'
    implementation: 'Spatie Permission + Laravel Policies'
    roles: ['Administrator', 'Manager', 'Teller', 'Collector']
    total_permissions: 35

data_security:
    - SQL injection prevention (Eloquent ORM) ✅
    - XSS protection ✅
    - CSRF tokens ✅

audit_trail:
    - Every data modification logged ✅
    - User action tracking ✅
    - Old/new values stored in JSON ✅
    - IP address and user-agent captured ✅
```

---

## 5. Core Modules

### 5.1 Module: Member Management ✅ COMPLETE

```yaml
module_id: 'MM'
module_name: 'Member Management'
status: '✅ COMPLETE (Backend + Frontend + Testing)'
```

#### Implemented Features

| Feature ID | Feature Name           | Status | Notes                                          |
| ---------- | ---------------------- | ------ | ---------------------------------------------- |
| MM-01      | Member Registration    | ✅     | 16-digit KTP, cascading regions, auto-savings  |
| MM-02      | Member Profile View    | ✅     | Full profile with savings/financing summaries  |
| MM-03      | Member Search & Filter | ✅     | Name, ID, phone search. Optimized (10x faster) |
| MM-04      | Member Profile Update  | ✅     | Edit with audit trail                          |
| MM-05      | Member Verification    | ✅     | Verification workflow (not in original spec)   |
| MM-06      | Member Deactivation    | ✅     | Soft delete with pre-condition checks          |

#### Implemented Pages

- ✅ `/members` - Index with DataTable, search, filters, pagination
- ✅ `/members/create` - Registration form with cascading region selectors
- ✅ `/members/{member}/edit` - Profile update form
- ✅ `/members/{member}` - Detail view with summary

#### Backend Components

- `MemberController` (8 routes)
- `MemberService` (register, verify, update, search)
- `MemberPolicy` (view, create, update, delete, verify)
- `StoreMemberRequest`, `UpdateMemberRequest`
- 13 service tests passing

---

### 5.2 Module: Savings Management ✅ COMPLETE

```yaml
module_id: 'SM'
module_name: 'Savings Management'
status: '✅ COMPLETE (Backend + Frontend + Testing)'
dependencies: ['MM - Member Management']
```

#### Implemented Features

| Feature ID | Feature Name           | Status | Notes                             |
| ---------- | ---------------------- | ------ | --------------------------------- |
| SM-01      | Account Creation       | ✅     | Auto-generate account number      |
| SM-02      | Deposit Transaction    | ✅     | With auto journal entry           |
| SM-03      | Withdrawal Transaction | ✅     | Balance check, auto journal entry |
| SM-04      | Account Statement      | ✅     | Transaction history with filters  |
| SM-05      | Account Closure        | ✅     | Zero-balance validation           |
| SM-06      | Passbook Printing      | ⏳     | PDF receipt generation pending    |

#### Accounting Integration (Auto Journal Entries)

```
Deposit:     Debit Cash (101)              Credit Member Savings (201)
Withdrawal:  Debit Member Savings (201)    Credit Cash (101)
```

#### Implemented Pages

- ✅ `/savings` - Index with stats cards, search, filters
- ✅ `/savings/create` - Open new account form
- ✅ `/savings/{account}` - Account details with quick deposit/withdraw actions
- ✅ `/savings/{account}/transactions` - Full transaction history

#### Backend Components

- `SavingsController` (8 routes)
- `SavingsService` (deposit, withdraw, openAccount, closeAccount)
- `SavingsAccountPolicy`
- `DepositRequest`, `WithdrawalRequest`
- 18 service tests passing

---

### 5.3 Module: Financing Management ✅ COMPLETE

```yaml
module_id: 'FM'
module_name: 'Financing Management'
status: '✅ COMPLETE (Backend + Frontend + Testing)'
dependencies:
    - 'MM - Member Management'
    - 'SM - Savings Management'
    - 'AM - Accounting Module'
```

#### Implemented Features

| Feature ID | Feature Name              | Status | Notes                                     |
| ---------- | ------------------------- | ------ | ----------------------------------------- |
| FM-01      | Financing Application     | ✅     | Single-page form with MemberSelector      |
| FM-02      | Survey Assignment         | ⏳     | Planned for v2 (after user adoption)      |
| FM-03      | Field Survey Entry        | ⏳     | Planned for v2                            |
| FM-04      | Approval Workflow (MVP)   | ✅     | Manager approve/reject with modals        |
| FM-04-V2   | Multi-Step Approval       | ⏳     | Planned for v2                            |
| FM-05      | Disbursement              | ✅     | Cash or transfer-to-savings               |
| FM-06      | Payment Collection        | ✅     | Full payment recording with auto-journals |
| FM-07      | Payment Schedule          | ✅     | Auto-generated, Sunday-skipping           |
| FM-08      | Financing Account Details | ✅     | Full detail view with all sections        |
| FM-09      | Early Settlement          | ✅     | Write-off functionality available         |
| FM-10      | Collectibility Analysis   | ✅     | Auto-calculated DPD, 1-5 scale            |

#### Financing Lifecycle (Implemented)

```
Propose → Approve/Reject → Disburse → Collect Daily → Paid Off / Written Off
```

#### Accounting Integration (Auto Journal Entries)

```
Disbursement:
  Debit Financing Receivable (104)
  Credit Cash (101) or Member Savings (201)

Payment:
  Debit Cash (101) - full payment
  Credit Financing Receivable (104) - principal portion
  Credit Margin Revenue (401) - margin portion
```

#### Implemented Pages

- ✅ `/financings` - Index page with filters, stats, status badges
- ✅ `/financings/create` - Proposal form (refactored, single-page with MemberSelector)
- ✅ `/financings/{financing}` - Detail view with approval/disbursement actions
- ✅ `/financings/{financing}/installments` - Installment schedule visualization
- ✅ `/financings/{financing}/payments` - Payment history
- ✅ `/financings/{financing}/record-payment` - Payment recording form
- ✅ `/financings/overdue-installments` - Overdue installments with search & quick pay

#### Backend Components

- `FinancingController` (11 routes)
- `FinancingInstallmentController` (overdue installments)
- `FinancingService` (propose, approve, reject, disburse, recordPayment, writeOff)
- `FinancingPolicy`
- `ProposeFinancingRequest`, `ApproveFinancingRequest`, `RejectFinancingRequest`, `DisburseFinancingRequest`, `RecordPaymentRequest`
- 18+ service tests passing

---

### 5.4 Module: Collection Management ⏳ PLANNED

```yaml
module_id: 'CM'
module_name: 'Collection Management'
status: '⏳ Placeholder page exists, backend models ready'
dependencies:
    - 'FM - Financing Management'
    - 'UM - User Management'
```

#### Planned Features

| Feature ID | Feature Name                | Status | Notes                      |
| ---------- | --------------------------- | ------ | -------------------------- |
| CM-01      | Territory Management        | ⏳     | Not started                |
| CM-02      | Daily Collection Assignment | ⏳     | Placeholder page exists    |
| CM-03      | Collection Recording        | ⏳     | Can use financing payments |
| CM-04      | Collector Performance       | ⏳     | Not started                |

> [!NOTE]
> While the Collection Management module is not fully implemented yet, collectors can already use the existing financing payment recording feature (`/financings/{financing}/record-payment`) and the overdue installments page (`/financings/overdue-installments`) for daily collection work.

---

### 5.5 Module: Accounting & Financial Reporting ✅ COMPLETE

```yaml
module_id: 'AM'
module_name: 'Accounting Module'
status: '✅ COMPLETE (Backend + Frontend + Testing)'
dependencies:
    - 'SM - Savings Management'
    - 'FM - Financing Management'
```

#### Implemented Features

| Feature ID | Feature Name               | Status | Notes                                 |
| ---------- | -------------------------- | ------ | ------------------------------------- |
| AM-01      | Chart of Accounts          | ✅     | Hierarchical structure, CRUD pages    |
| AM-02      | Auto Journal Entries       | ✅     | From savings & financing transactions |
| AM-03      | Manual Journal Entry       | ✅     | With double-entry validation          |
| AM-04      | Special Journal - Cash In  | ✅     | Via manual journal entry              |
| AM-05      | Special Journal - Cash Out | ✅     | Via manual journal entry              |
| AM-06      | Budget Planning            | ⏳     | Not yet implemented                   |
| AM-07      | Year-End Closing           | ⏳     | Not yet implemented                   |
| AM-08      | Reverse Year-End Closing   | ⏳     | Not yet implemented                   |

#### Account Structure (Simplified, Implemented)

```
1xx - Assets (Kas, Piutang Pembiayaan)
2xx - Liabilities (Simpanan Anggota)
3xx - Equity (Modal)
4xx - Revenue (Pendapatan Margin)
5xx - Expenses (Beban Operasional)
```

#### Implemented Pages

- ✅ `/accounting/accounts` - Chart of accounts index
- ✅ `/accounting/accounts/create` - Create new account
- ✅ `/accounting/accounts/{account}` - Account details
- ✅ `/accounting/accounts/{account}/edit` - Edit account
- ✅ `/accounting/journals` - Journal entry index
- ✅ `/accounting/journals/create` - Create manual journal entry
- ✅ `/accounting/journals/{journal}` - Journal entry details

#### Financial Reports ✅ Implemented

- ✅ `/accounting/trial-balance` - Trial Balance
- ✅ `/accounting/balance-sheet` - Balance Sheet (Neraca)
- ✅ `/accounting/income-statement` - Income Statement (Laba Rugi)

#### Backend Components

- `AccountingController` (8 routes)
- `AccountingService` (createJournalEntry, voidJournalEntry, updateAccountBalance)
- `JournalEntryPolicy`, `AccountPolicy`
- `StoreJournalEntryRequest`
- 10 service tests passing
- 24-hour void window for journal entries

---

## 6. Supporting Modules

### 6.1 Module: User Management ✅ COMPLETE

```yaml
module_id: 'UM'
module_name: 'User Management'
status: '✅ COMPLETE'
```

#### Implemented Roles

| Role          | Permissions | Description                                |
| ------------- | ----------- | ------------------------------------------ |
| Administrator | 35          | Full system access                         |
| Manager       | 26          | Can approve financing, accounting, reports |
| Teller        | 11          | Daily transactions only                    |
| Collector     | 4           | View members, record payments, dashboard   |

#### Implemented Pages

- ✅ `/users` - Index with DataTable, search, modal CRUD
- ✅ User creation, editing, role assignment
- ✅ Password management

#### Backend Components

- `UserController` (7 routes)
- `UserService`
- `UserPolicy`

### 6.2 Module: Branch Management ✅ COMPLETE

```yaml
module_id: 'BM'
module_name: 'Branch Management'
status: '✅ COMPLETE'
```

- ✅ `/branches` - Index with DataTable, modal CRUD
- `BranchController` (7 routes), `BranchService`, `BranchPolicy`

### 6.3 Module: Document Management ⏳ PLANNED

```yaml
module_id: 'DM'
module_name: 'Document Management'
status: '⏳ Not yet implemented'
priority: 'Medium (v2)'
```

### 6.4 Module: Notification System ⏳ PARTIAL

```yaml
module_id: 'NS'
module_name: 'Notification System'
status: '⏳ Toast notifications only (Sonner library)'
```

- ✅ In-app toast notifications (success, error, warning, info)
- ⏳ Email notifications not implemented
- ⏳ SMS notifications not implemented

---

## 7. Workflows

### 7.1 Member Registration ✅ Implemented

```yaml
workflow_id: 'WF-001'
status: '✅ Fully implemented'
steps: 1. Teller enters member data with cascading region selectors
    2. System validates (KTP uniqueness, 16-digit check)
    3. System auto-generates member number
    4. System auto-creates savings account
    5. Teller processes initial deposit (IDR 5,000 minimum)
    6. System creates journal entry automatically
```

### 7.2 Financing Application (MVP) ✅ Implemented

```yaml
workflow_id: 'WF-002-MVP'
status: '✅ Fully implemented'
steps: 1. Teller submits application (single-page form with MemberSelector)
    2. Manager reviews and approves/rejects
    3. System auto-generates 100-day payment schedule
    4. Teller/Admin disburses (cash or to savings)
    5. Daily collection and payment recording
```

### 7.3 Financing Application (Full v2) ⏳ Planned

```yaml
workflow_id: 'WF-002-FULL'
status: '⏳ Planned for v2'
additional_steps:
    - Survey assignment to field officers
    - Field survey data entry
    - Survey results review by manager
    - Mobile app for field officers
```

### 7.4 Daily Collection ⏳ Partial

```yaml
workflow_id: 'WF-003'
status: '⏳ Partially supported'
currently_available:
    - Overdue installments page (with search)
    - Direct payment processing from overdue list
    - Payment recording from financing detail page
pending:
    - Territory assignment
    - Daily task list auto-generation
    - Collection route planning
    - Cash handover reconciliation
```

---

## 8. Data Migration ⏳ Planned

```yaml
status: '⏳ Not yet started'
approach: 'Phased migration with parallel run'

phases: 1. Analyze IBSS database structure
    2. Map tables to new schema
    3. Create migration scripts
    4. Migrate master data (members, accounts)
    5. Migrate transaction data
    6. Parallel run (2-4 weeks)
    7. Cutover
```

---

## 9. Reporting Requirements

### 9.1 Financial Reports ✅ Implemented

| Report           | Status | Page                           |
| ---------------- | ------ | ------------------------------ |
| Trial Balance    | ✅     | `/accounting/trial-balance`    |
| Balance Sheet    | ✅     | `/accounting/balance-sheet`    |
| Income Statement | ✅     | `/accounting/income-statement` |

### 9.2 Operational Reports ✅ Partial

| Report                     | Status | Notes                            |
| -------------------------- | ------ | -------------------------------- |
| Dashboard KPIs             | ✅     | Members, savings, financing, NPF |
| Overdue Installments       | ✅     | With search and quick payment    |
| Savings Transaction Report | ✅     | Via account transaction history  |
| Collectibility Analysis    | ✅     | Auto-calculated in financing     |

### 9.3 Reports Pending ⏳

| Report                  | Status | Notes                        |
| ----------------------- | ------ | ---------------------------- |
| PDF Receipts            | ⏳     | Transaction & payment PDFs   |
| CSV/Excel Export        | ⏳     | Data export functionality    |
| Collector Performance   | ⏳     | Depends on Collection module |
| Savings Mutation Report | ⏳     | Printable PDF format         |
| Budget vs Actual        | ⏳     | Depends on budget planning   |

---

## 10. User Roles & Permissions ✅ Implemented

### Role Permission Matrix

| Permission Area          | Administrator | Manager | Teller | Collector |
| ------------------------ | ------------- | ------- | ------ | --------- |
| **Members**              |               |         |        |           |
| View members             | ✅            | ✅      | ✅     | ✅        |
| Create members           | ✅            | ✅      | ✅     | ❌        |
| Update members           | ✅            | ✅      | ✅     | ❌        |
| Delete members           | ✅            | ❌      | ❌     | ❌        |
| Verify members           | ✅            | ✅      | ❌     | ❌        |
| **Savings**              |               |         |        |           |
| View accounts            | ✅            | ✅      | ✅     | ❌        |
| Open accounts            | ✅            | ✅      | ✅     | ❌        |
| Process deposits         | ✅            | ✅      | ✅     | ❌        |
| Process withdrawals      | ✅            | ✅      | ✅     | ❌        |
| Close accounts           | ✅            | ✅      | ❌     | ❌        |
| **Financing**            |               |         |        |           |
| View financing           | ✅            | ✅      | ✅     | ✅        |
| Propose financing        | ✅            | ✅      | ✅     | ❌        |
| Approve/Reject financing | ✅            | ✅      | ❌     | ❌        |
| Disburse financing       | ✅            | ✅      | ❌     | ❌        |
| Record payments          | ✅            | ✅      | ✅     | ✅        |
| **Accounting**           |               |         |        |           |
| View journals            | ✅            | ✅      | ❌     | ❌        |
| Create journals          | ✅            | ✅      | ❌     | ❌        |
| Void journals            | ✅            | ✅      | ❌     | ❌        |
| View reports             | ✅            | ✅      | ❌     | ❌        |
| **System**               |               |         |        |           |
| Manage users             | ✅            | ❌      | ❌     | ❌        |
| Manage branches          | ✅            | ❌      | ❌     | ❌        |
| View dashboard           | ✅            | ✅      | ✅     | ✅        |

---

## 11. Implementation Phases

### Phase Progress Overview

| Phase       | Description                   | Status         | Completion |
| ----------- | ----------------------------- | -------------- | ---------- |
| **Phase 1** | Foundation & Models           | ✅ Complete    | 100%       |
| **Phase 2** | Service Layer                 | ✅ Complete    | 100%       |
| **Phase 3** | Model Cleanup & Form Requests | ✅ Complete    | 100%       |
| **Phase 4** | Form Requests Validation      | ✅ Complete    | 100%       |
| **Phase 5** | Controllers & Routes          | ✅ Complete    | 100%       |
| **Phase 6** | Policies & Authorization      | ✅ Complete    | 100%       |
| **Phase 7** | Frontend Implementation       | ✅ Complete    | 100%       |
| **Phase 8** | Testing & QA                  | 🔄 In Progress | 60%        |
| **Phase 9** | Deployment & Migration        | ⏳ TODO        | 0%         |

### Current Statistics

| Metric              | Value                         |
| ------------------- | ----------------------------- |
| **Models**          | 18 Eloquent models            |
| **Services**        | 6 service classes             |
| **Controllers**     | 9 controllers + settings      |
| **Routes**          | 51+ registered routes         |
| **Policies**        | 8 policy classes              |
| **Permissions**     | 35 permissions across 4 roles |
| **Tests**           | 170+ tests passing            |
| **Frontend Pages**  | 30+ React/Inertia pages       |
| **Database Tables** | 15+ tables                    |

### Remaining Work

#### High Priority (v1 Release)

- [ ] PDF receipt generation (transactions, payments)
- [ ] CSV/Excel export
- [ ] Complete integration testing
- [ ] Production deployment (VPS setup, SSL, domain)
- [ ] User documentation & staff training
- [ ] Data migration from IBSS

#### Medium Priority (v2 Enhancements)

- [ ] Collection Management module (territory, daily tasks)
- [ ] Survey workflow for financing (FM-02, FM-03, FM-04-V2)
- [ ] Document Management module
- [ ] Budget Planning & Year-End Closing (AM-06, AM-07, AM-08)
- [ ] Email/SMS notification system
- [ ] Savings passbook printing

#### Low Priority (Future)

- [ ] Mobile PWA for collectors
- [ ] Offline-first capability
- [ ] Payment gateway integration
- [ ] Multi-branch support expansion
- [ ] Advanced analytics & charting

---

## Appendix: Key Design Decisions

| Decision                 | Choice Made                | Rationale                                    |
| ------------------------ | -------------------------- | -------------------------------------------- |
| **Islamic Contract**     | Murabahah (not Mudharabah) | Simpler, no profit-sharing calculations      |
| **Margin Rate**          | Fixed 10%                  | Aligned with current operations              |
| **Installment Count**    | Fixed 100 days             | Standard product offering                    |
| **Service Layer**        | Plain PHP classes          | No interfaces/base classes, simple injection |
| **Frontend State**       | Immutability pattern       | React best practice, Inertia props readonly  |
| **Validation**           | Form Request classes       | Separated from controllers                   |
| **Financial Operations** | DB::transaction() always   | Atomic, no partial state                     |
| **Audit Trail**          | Model events               | Auto-logging, no manual calls                |
| **UI Language**          | Indonesian                 | Target user base                             |
| **Journal Void Window**  | 24 hours                   | Balance between flexibility and control      |
| **Account Codes**        | Code-based (not ID-based)  | Stable across environments                   |

---

**END OF DOCUMENT**

**Document Version:** 2.0
**Last Updated:** February 23, 2026
**Next Review:** Pre-deployment (Phase 9)