Guidance for developing and maintaining the Pecunia personal finance management system with PHP, MySQL, AI integration, and Telegram bot support
This skill has safety concerns that you should review before use. Some patterns were detected that may pose a risk.Safety score: 75/100.
KillerSkills scans all public content for safety. Use caution before installing or executing flagged content.
This skill provides comprehensive guidance for working with Pecunia, a personal finance management system built with PHP and MySQL/MariaDB. It features AI-powered document analysis using Google Gemini API, Telegram bot integration for receipt processing, and multi-currency support with stock portfolio tracking.
Pecunia follows a traditional PHP MVC-like architecture with the following key components:
```
.env → config.php → Database/Language/PDO → Individual modules
↓
Session management → User context → Feature modules
```
1. **Installation Options**:
- Automated CLI: `php install.php`
- Web-based: Visit `http://localhost/install_web.php`
- Manual: `composer install`, copy `.env.example` to `.env`, import `database/database.sql`
2. **Create Secure Upload Directory**:
```bash
mkdir secure_uploads
chmod 755 secure_uploads
```
3. **Verify Installation**:
```bash
php verify_installation.php
```
4. **Set Up Telegram Bot** (requires HTTPS):
```bash
php telegram/telegram_bot.php
```
**No build process required** - PHP changes reflect immediately on Apache/Nginx.
**Testing** is manual through the web interface (no automated test suite).
**Background Tasks**:
```bash
php cron/cron_borsa.php
php cron/cron_borsa_worker.php
php backup.php backup # Create backup
php backup.php list # List backups
php backup.php restore backup_file.sql.gz
php backup.php auto # For cron automation
```
**Example crontab**:
```
0 * * * * /usr/bin/php /path/to/project/cron/cron_borsa.php
0 2 * * * /usr/bin/php /path/to/project/backup.php auto
```
**View Logs** (admin only):
**Key Debugging Endpoints**:
**Test API Endpoints**:
```bash
curl -X POST http://localhost/api.php \
-H "Cookie: PHPSESSID=your_session_id" \
-d "action=get_summary&month=1&year=2025"
curl -X POST http://localhost/api/exchange_rate_refresh.php \
-H "Cookie: PHPSESSID=your_session_id" \
-d "from_currency=USD&to_currency=TRY"
```
**Monitor Performance**:
```bash
SELECT table_name, index_name
FROM information_schema.statistics
WHERE column_name = 'user_id';
grep "Gemini API" /path/to/logs/* | wc -l
SELECT * FROM information_schema.INNODB_TRX;
```
**Every protected page MUST follow this sequence**:
1. `require_once 'config.php'` → Environment loading → Database connection → Language initialization
2. `checkLogin()` → Session validation → User context establishment
3. All subsequent operations use `$_SESSION['user_id']` for user scoping
**Security Features**:
**All API modules follow this consistent structure**:
1. **Centralized Routing**: `api.php` dispatches to specialized modules
2. **Exception-Based Validation**: Uses `api/validate.php` utilities
3. **Transaction Safety**: Database transactions with rollback on errors
4. **User Scoping**: All operations validate user ownership via `$user_id`
5. **Standardized Responses**: JSON format with `status` and `message`
**API Modules**:
**Core Tables**:
**JavaScript Modules**:
Follow this exact pattern:
1. **Create API Module** (`api/newmodule.php`):
```php
<?php
require_once __DIR__ . '/../config.php';
checkLogin();
function addNewItem() {
global $pdo, $user_id;
// Validation with validate.php functions
validateRequired($_POST, ['field1', 'field2']);
validateNumeric($_POST, ['amount']);
// Database transaction with try-catch
try {
$pdo->beginTransaction();
$stmt = $pdo->prepare("INSERT INTO new_items (user_id, field1, field2) VALUES (?, ?, ?)");
$stmt->execute([$user_id, $_POST['field1'], $_POST['field2']]);
$pdo->commit();
return true;
} catch (Exception $e) {
$pdo->rollBack();
throw $e;
}
}
```
2. **Update Main Router** (`api.php`):
```php
case 'add_new_item':
try {
if (addNewItem()) {
$response = ['status' => 'success', 'message' => t('newmodule.add_success')];
}
} catch (Exception $e) {
$response = ['status' => 'error', 'message' => $e->getMessage()];
}
break;
```
3. **Add JavaScript Module** (`js/newmodule.js`):
```javascript
function addNewItem(data) {
// Client-side validation
if (!data.field1 || !data.field2) {
showError(t('validation.required_fields'));
return;
}
ajaxRequest('api.php', { action: 'add_new_item', ...data }, function(response) {
if (response.status === 'success') {
showSuccess(response.message);
refreshList();
}
});
}
```
4. **Add Language Keys** (`lang/tr.php` and `lang/en.php`):
```php
'newmodule' => [
'add_success' => 'Successfully added',
'validation.required_fields' => 'Required fields missing'
]
```
5. **Database Schema**: Add table with `user_id` foreign key and proper indexes
1. Create `commands/NewCommand.php` extending `UserCommand`
2. Implement `execute()` method with error handling
3. Commands are auto-discovered by TelegramBot framework
Example:
```php
<?php
namespace TelegramBot\Commands;
class NewCommand extends UserCommand {
protected $name = 'newcommand';
protected $description = 'Description of command';
public function execute() {
// Command logic
$this->replyToChat('Response message');
}
}
```
**Multi-Channel Document Processing**:
1. **Input Sources**: Web upload (PDF/Excel/CSV/images) + Telegram photos
2. **Security Validation**: MIME type, file size, malicious content scanning
3. **AI Processing**: Google Gemini Vision API with structured prompts
4. **Approval Workflow**: AI results → `ai_analysis_temp` table → user review → batch approval
5. **Data Integration**: Approved items automatically added to financial tables
**Rate Limiting** (Built-in protection):
When working with this codebase, always follow these security patterns:
1. **Input Validation**: Use `api/validate.php` functions before processing
2. **SQL Queries**: Always use prepared statements with parameterized queries
3. **File Uploads**: Validate MIME type, file size, and scan for malicious content
4. **Session Management**: Never bypass `checkLogin()` for protected pages
5. **XSS Protection**: Use `api/xss.php` functions for HTML escaping
6. **User Scoping**: Always filter queries by `$_SESSION['user_id']`
7. **Transaction Safety**: Wrap multi-query operations in transactions with rollback
**Architectural Bottlenecks**:
1. **Database**: 30+ queries filter by `user_id` - ensure all `user_id` columns are indexed
2. **Summary Calculations**: Complex subqueries in `api/summary.php` - consider materialized views
3. **Exchange Rates**: Fetched per transaction - implement aggressive caching (1+ hours)
4. **AI Processing**: Files loaded entirely in memory - consider streaming for large files
5. **Session Storage**: PHP file sessions don't scale - migrate to Redis/Memcached for high traffic
```bash
php telegram_bot.php && curl -s "https://api.telegram.org/bot$TOKEN/getWebhookInfo"
ls -la /tmp/sess_* | wc -l
for i in {1..15}; do
curl -X POST http://localhost/api/exchange_rate_refresh.php \
-H "Cookie: PHPSESSID=your_session_id" \
-d "from_currency=USD&to_currency=TRY"
done
curl -X POST http://localhost/upload_handler.php \
-F "file=@test_receipt.jpg" \
-F "type=ai_analysis" \
-H "Cookie: PHPSESSID=your_session_id"
SELECT currency_from, currency_to, rate, updated_at
FROM exchange_rates
WHERE updated_at > DATE_SUB(NOW(), INTERVAL 1 HOUR);
```
1. **Authentication Required**: All protected pages MUST call `checkLogin()` after including `config.php`
2. **User Scoping**: All database queries for user data MUST filter by `$_SESSION['user_id']`
3. **Transaction Safety**: Multi-query operations MUST use database transactions with proper rollback
4. **Input Validation**: All API endpoints MUST validate input before processing
5. **Error Handling**: Use exception-based error handling with standardized JSON responses
6. **Language Support**: All user-facing strings MUST use `t()` function with translation keys
7. **Rate Limiting**: Respect built-in rate limits for external API calls
8. **File Security**: All file uploads MUST validate MIME type and scan for malicious content
Leave a review
No reviews yet. Be the first to review this skill!
# Download SKILL.md from killerskills.ai/api/skills/personal-finance-management-system-guide/raw