mirror of
https://github.com/elisiariocouto/leggen.git
synced 2025-12-16 07:42:23 +00:00
91f53b35b1
This major update transforms leggen from CLI-only to a web-ready architecture while maintaining full CLI compatibility. New Features: - FastAPI backend service (leggend) with comprehensive REST API - Background job scheduler with configurable cron (replaces Ofelia) - All CLI commands refactored to use API endpoints - Docker configuration updated for new services - API client with health checks and error handling API Endpoints: - /api/v1/banks/* - Bank connections and institutions - /api/v1/accounts/* - Account management and balances - /api/v1/transactions/* - Transaction retrieval with filtering - /api/v1/sync/* - Manual sync and scheduler configuration - /api/v1/notifications/* - Notification settings management CLI Enhancements: - New --api-url option and LEGGEND_API_URL environment variable - Enhanced sync command with --wait and --force options - Improved transactions command with --full and --limit options - Automatic fallback and health checking Breaking Changes: - compose.yml structure updated (leggend service added) - Ofelia scheduler removed (internal scheduler used instead) 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
69 lines
3.1 KiB
Markdown
69 lines
3.1 KiB
Markdown
# CLAUDE.md
|
|
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
|
|
|
## Project Overview
|
|
|
|
Leggen is an Open Banking CLI tool built in Python that connects to banks using the GoCardless Open Banking API. It allows users to sync bank transactions to SQLite/MongoDB databases, visualize data with NocoDB, and send notifications based on transaction filters.
|
|
|
|
## Development Commands
|
|
|
|
- **Install dependencies**: `uv sync` (uses uv package manager)
|
|
- **Run locally**: `uv run leggen --help`
|
|
- **Lint code**: `ruff check` and `ruff format` (configured in pyproject.toml)
|
|
- **Build Docker image**: `docker build -t leggen .`
|
|
- **Run with Docker Compose**: `docker compose up -d`
|
|
|
|
## Architecture
|
|
|
|
### Core Structure
|
|
- `leggen/main.py` - Main CLI entry point using Click framework with custom command loading
|
|
- `leggen/commands/` - CLI command implementations (balances, sync, transactions, etc.)
|
|
- `leggen/utils/` - Core utilities for authentication, database operations, network requests, and notifications
|
|
- `leggen/database/` - Database adapters for SQLite and MongoDB
|
|
- `leggen/notifications/` - Discord and Telegram notification handlers
|
|
|
|
### Key Components
|
|
|
|
**Configuration System**:
|
|
- Uses TOML configuration files (default: `~/.config/leggen/config.toml`)
|
|
- Configuration loaded via `leggen/utils/config.py`
|
|
- Supports GoCardless API credentials, database settings, and notification configurations
|
|
|
|
**Authentication & API**:
|
|
- GoCardless Open Banking API integration in `leggen/utils/gocardless.py`
|
|
- Token-based authentication via `leggen/utils/auth.py`
|
|
- Network utilities in `leggen/utils/network.py`
|
|
|
|
**Database Operations**:
|
|
- Dual database support: SQLite (`database/sqlite.py`) and MongoDB (`database/mongo.py`)
|
|
- Transaction persistence and balance tracking via `utils/database.py`
|
|
- Data storage patterns follow bank account and transaction models
|
|
|
|
**Command Architecture**:
|
|
- Dynamic command loading system in `main.py` with support for command groups
|
|
- Commands organized as modules with individual click decorators
|
|
- Bank management commands grouped under `commands/bank/`
|
|
|
|
### Data Flow
|
|
1. Configuration loaded from TOML file
|
|
2. GoCardless API authentication and bank requisition management
|
|
3. Account and transaction data retrieval from banks
|
|
4. Data persistence to configured databases (SQLite/MongoDB)
|
|
5. Optional notifications sent via Discord/Telegram based on filters
|
|
6. Data visualization available through NocoDB integration
|
|
|
|
## Docker & Deployment
|
|
|
|
The project uses multi-stage Docker builds with uv for dependency management. The compose.yml includes:
|
|
- Main leggen service with sync scheduling via Ofelia
|
|
- NocoDB for data visualization
|
|
- Optional MongoDB with mongo-express admin interface
|
|
|
|
## Configuration Requirements
|
|
|
|
All operations require a valid `config.toml` file with GoCardless API credentials. The configuration structure includes sections for:
|
|
- `[gocardless]` - API credentials and endpoint
|
|
- `[database]` - Storage backend selection
|
|
- `[notifications]` - Discord/Telegram webhook settings
|
|
- `[filters]` - Transaction matching patterns for notifications |