nikdoof/leggen
1
1
Fork 0
mirror of https://github.com/elisiariocouto/leggen.git synced 2025-12-13 16:02:16 +00:00
Code Issues Packages Projects Releases Wiki Activity
Files
91f53b35b18740869ee9cebfac394db2e12db099
leggen/CLAUDE.md
Elisiário Couto 91f53b35b1 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>
2025-09-09 19:39:11 +01:00

3.1 KiB
Raw Blame History

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