mirror of
https://github.com/elisiariocouto/leggen.git
synced 2025-12-13 16:02:16 +00:00
feat: Transform to web architecture with FastAPI backend
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>
This commit is contained in:
committed by
Elisiário Couto
parent
73d6bd32db
commit
91f53b35b1
69
CLAUDE.md
Normal file
69
CLAUDE.md
Normal file
@@ -0,0 +1,69 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user