kaunter/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Repository Overview

This is the Kaunter application, part of the Arrahn PKB (Pajak Gadai Sistem) - an Islamic pawn shop/mortgage management system. This Laravel 7.x application serves as the counter/teller interface for managing pawn transactions, customer interactions, and branch operations within a larger microservices architecture.

Application Architecture

Core Business Domain

The application manages Islamic financial transactions including:

• Gadaian - Pawn/mortgage transactions with Islamic finance compliance
• Penebusan - Redemption and repayment processes
• Customer Management - Customer records with document management
• Marhun - Collateral item management (primarily gold jewelry)
• Treasury Operations - Cash flow and financial reconciliation

Role-Based Access Control

The system implements 8 distinct user roles with dedicated middleware:

• teller - Front desk operations
• khazanah - Treasury/financial management
• operasi - Operations management
• admin - Administrative functions
• penilai - Item appraisers
• callcenter - Customer service
• audit - Financial auditing
• akaun - Accounting functions

Each role has specific controllers, views, and middleware (app/Http/Middleware/).

API-First Architecture

Controllers primarily delegate to external APIs rather than direct database operations:

• API URLs configured via config('api.url')
• API verification settings via config('app.api_verify')
• Multi-zone API support for different business units

Development Commands

Laravel Application Commands

# Install dependencies (use Docker containers as per parent repository)
docker compose run --rm composer install
docker compose run --rm npm install

# Generate application key
docker compose run --rm artisan key:generate

# Run migrations
docker compose run --rm artisan migrate
docker compose run --rm artisan migrate:fresh

# Clear caches
docker compose run --rm artisan cache:clear
docker compose run --rm artisan config:clear
docker compose run --rm artisan view:clear

Frontend Asset Management

# Development build with watch
docker compose run --rm npm run dev
docker compose run --rm npm run watch

# Production build
docker compose run --rm npm run production

# Hot reload for development
docker compose run --rm npm run hot

Testing

# Run all tests
docker compose run --rm vendor/bin/phpunit

# Run specific test suites
docker compose run --rm vendor/bin/phpunit --testsuite=Unit
docker compose run --rm vendor/bin/phpunit --testsuite=Feature

# Run with coverage
docker compose run --rm vendor/bin/phpunit --coverage-html coverage

Custom Artisan Commands (Financial Operations)

# Daily financial operations
docker compose run --rm artisan akru:daily
docker compose run --rm artisan imbangduga:daily

# Monthly operations
docker compose run --rm artisan backup:stokaudit

# System maintenance
docker compose run --rm artisan reset:role-daily
docker compose run --rm artisan check:lelong-tawarruq

Key Application Components

Core Models & Relationships

• Gadaian - Central pawn transaction model with customer and marhun relationships
• Customer - Uses Spatie MediaLibrary for document management
• Penebusan - Redemption transactions linked to gadaian records
• Marhun - Collateral items with detailed specifications
• HargaEmas - Gold pricing with historical tracking
• ImbangDuga - Trial balance for financial reconciliation

Business Services

• CustomerService - Customer operations including automated number generation
• ImbangdugaServices - Financial reconciliation and trial balance operations

Event System

Real-time dashboard updates via Laravel Events:

• Dashboard notifications: GadaiNotify, TebusNotify, KeuntunganNotify
• Process events: AutoSerahan, SerahanPenilai
• User notifications: NotifikasiPembayaran, NotifikasiKelulusan

Configuration Files

• config/redeemoption.php - Business logic toggles for redemption features
• config/adminlte.php - AdminLTE dashboard configuration
• Environment files - Multiple environment configurations in env.docker.example/

Technology Stack

Laravel Packages

• AdminLTE 3 (jeroennoten/laravel-adminlte) - Administrative interface
• Spatie MediaLibrary - File and document management
• DomPDF (barryvdh/laravel-dompdf) - PDF report generation
• Pusher - Real-time notifications
• Twilio SDK - SMS communication
• DataTables (yajra/laravel-datatables-oracle) - Advanced table management
• QR Code & Barcode - Document generation utilities

Frontend Stack

• Laravel Mix - Asset compilation (Webpack wrapper)
• AdminLTE 3 - Bootstrap-based admin template
• jQuery - DOM manipulation and AJAX
• Socket.io - Real-time communication client
• Bootstrap 4 - CSS framework

Development Workflow

Environment Setup

1. Copy appropriate environment file from env.docker.example/ directory
2. Configure database connections for multi-zone setup
3. Set API endpoints for microservices communication
4. Configure Pusher for real-time features
5. Set up Twilio credentials for SMS functionality

Working with Roles

When developing role-specific features:

1. Check relevant middleware in app/Http/Middleware/
2. Use role-specific views in resources/views/homepage/{role}/
3. Follow role-based routing patterns in routes/web.php
4. Ensure API calls respect role permissions

API Integration Pattern

When adding new functionality:

1. Controllers should primarily make API calls rather than direct DB operations
2. Use Laravel HTTP client for external API communication
3. Handle API responses consistently across controllers
4. Implement proper error handling for API failures

Testing Islamic Finance Logic

• Use php artisan check:lelong-tawarruq to verify Islamic compliance
• Test accrual calculations with php artisan akru:daily
• Validate trial balance with php artisan imbangduga:daily

File Structure Notes

View Organization

• Versioned views - v1/ and v2/ directories indicate system evolution
• Role-based dashboards - Separate homepage views for each user role
• Business-specific templates - Islamic finance compliance features

Custom Commands Location

All financial operation commands are in app/Console/Commands/ with descriptive names indicating their business purpose.

Configuration Patterns

• Business logic configuration separated into dedicated config files
• Environment-specific settings in docker example files
• Multi-zone database configuration support

Important Development Notes

• This application is part of a Docker microservices architecture
• Changes should maintain Islamic finance compliance requirements
• Real-time features depend on Pusher configuration
• Role-based access control is fundamental to all operations
• API integrations are critical - local database operations are minimal
• Multi-language support focuses on Malaysian Malay context