Cleanup agent documentation.

This commit is contained in:
Elisiário Couto
2025-09-09 16:22:50 +01:00
committed by Elisiário Couto
parent 16afa1ed8a
commit bc947183e3
4 changed files with 47 additions and 176 deletions

41
AGENTS.md Normal file
View File

@@ -0,0 +1,41 @@
# Agent Guidelines for Leggen
## Build/Lint/Test Commands
### Frontend (React/TypeScript)
- **Dev server**: `cd frontend && npm run dev`
- **Build**: `cd frontend && npm run build`
- **Lint**: `cd frontend && npm run lint`
### Backend (Python)
- **Lint**: `uv run ruff check .`
- **Format**: `uv run ruff format .`
- **Type check**: `uv run mypy leggen leggend --check-untyped-defs`
- **All checks**: `uv run pre-commit run --all-files`
- **Run all tests**: `uv run pytest`
- **Run single test**: `uv run pytest tests/unit/test_api_accounts.py::TestAccountsAPI::test_get_all_accounts_success -v`
- **Run tests by marker**: `uv run pytest -m "api"` or `uv run pytest -m "unit"`
## Code Style Guidelines
### Python
- **Imports**: Standard library → Third-party → Local (blank lines between groups)
- **Naming**: snake_case for variables/functions, PascalCase for classes
- **Types**: Use type hints for all function parameters and return values
- **Error handling**: Use specific exceptions, loguru for logging
- **Path handling**: Use `pathlib.Path` instead of `os.path`
- **CLI**: Use Click framework with proper option decorators
### TypeScript/React
- **Imports**: React hooks first, then third-party, then local components/types
- **Naming**: PascalCase for components, camelCase for variables/functions
- **Types**: Use `import type` for type-only imports, define interfaces/types
- **Styling**: Tailwind CSS with `clsx` utility for conditional classes
- **Icons**: lucide-react with consistent naming
- **Data fetching**: @tanstack/react-query with proper error handling
- **Components**: Functional components with hooks, proper TypeScript typing
### General
- **Formatting**: ruff for Python, ESLint for TypeScript
- **Commits**: Use conventional commits, run pre-commit hooks before pushing
- **Security**: Never log sensitive data, use environment variables for secrets

View File

@@ -1,69 +0,0 @@
# 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

View File

@@ -1,91 +0,0 @@
# Leggen Web Transformation Project
## Overview
Transform leggen from CLI-only to web application with FastAPI backend (`leggend`) and SvelteKit frontend (`leggen-web`).
## Progress Tracking
### ✅ Phase 1: FastAPI Backend (`leggend`)
#### 1.1 Core Structure
- [x] Create directory structure (`leggend/`, `api/`, `services/`, etc.)
- [x] Add FastAPI dependencies to pyproject.toml
- [x] Create configuration management system
- [x] Set up FastAPI main application
- [x] Create Pydantic models for API responses
#### 1.2 API Endpoints
- [x] Banks API (`/api/v1/banks/`)
- [x] `GET /institutions` - List available banks
- [x] `POST /connect` - Connect to bank
- [x] `GET /status` - Bank connection status
- [x] Accounts API (`/api/v1/accounts/`)
- [x] `GET /` - List all accounts
- [x] `GET /{id}/balances` - Account balances
- [x] `GET /{id}/transactions` - Account transactions
- [x] Sync API (`/api/v1/sync/`)
- [x] `POST /` - Trigger manual sync
- [x] `GET /status` - Sync status
- [x] Notifications API (`/api/v1/notifications/`)
- [x] `GET/POST/PUT /settings` - Manage notification settings
#### 1.3 Background Jobs
- [x] Implement APScheduler for sync scheduling
- [x] Replace Ofelia with internal Python scheduler
- [x] Migrate existing sync logic from CLI
### ⏳ Phase 2: SvelteKit Frontend (`leggen-web`)
#### 2.1 Project Setup
- [ ] Create SvelteKit project structure
- [ ] Set up API client for backend communication
- [ ] Design component architecture
#### 2.2 UI Components
- [ ] Dashboard with account overview
- [ ] Bank connection wizard
- [ ] Transaction history and filtering
- [ ] Settings management
- [ ] Real-time sync status
### ✅ Phase 3: CLI Refactoring
#### 3.1 API Client Integration
- [x] Create HTTP client for FastAPI calls
- [x] Refactor existing commands to use APIs
- [x] Maintain CLI user experience
- [x] Add API URL configuration option
### ✅ Phase 4: Docker & Deployment
#### 4.1 Container Setup
- [x] Create Dockerfile for `leggend` service
- [x] Update docker-compose.yml with `leggend` service
- [x] Remove Ofelia dependency (scheduler now internal)
- [ ] Create Dockerfile for `leggen-web` (deferred - not implementing web UI yet)
## Current Status
**Active Phase**: Phase 2 - CLI Integration Complete
**Last Updated**: 2025-09-01
**Completion**: ~80% (FastAPI backend and CLI refactoring complete)
## Next Steps (Future Enhancements)
1. Implement SvelteKit web frontend
2. Add real-time WebSocket support for sync status
3. Implement user authentication and multi-user support
4. Add more comprehensive error handling and logging
5. Implement database migrations for schema changes
## Recent Achievements
- ✅ Complete FastAPI backend with all major endpoints
- ✅ Configurable background job scheduler (replaces Ofelia)
- ✅ CLI successfully refactored to use API endpoints
- ✅ Docker configuration updated for new architecture
- ✅ Maintained backward compatibility and user experience
## Architecture Decisions
- **FastAPI**: For high-performance async API backend
- **APScheduler**: For internal job scheduling (replacing Ofelia)
- **SvelteKit**: For modern, reactive frontend
- **Existing Logic**: Reuse all business logic from current CLI commands
- **Configuration**: Centralize in `leggend` service, maintain TOML compatibility

View File

@@ -2,9 +2,7 @@
An Open Banking CLI and API service for managing bank connections and transactions.
This tool provides both a **FastAPI backend service** (`leggend`) and a **command-line interface** (`leggen`) to connect to banks using the GoCardless Open Banking API.
**New in v0.6.11**: Web-ready architecture with FastAPI backend, enhanced CLI, and background job scheduling.
This tool provides **FastAPI backend service** (`leggend`), a **React Web Interface** and a **command-line interface** (`leggen`) to connect to banks using the GoCardless Open Banking API.
Having your bank data accessible through both CLI and REST API gives you the power to backup, analyze, create reports, and integrate with other applications.
@@ -18,8 +16,8 @@ Having your bank data accessible through both CLI and REST API gives you the pow
### 📦 Storage
- [SQLite](https://www.sqlite.org): for storing transactions, simple and easy to use
### 📊 Visualization
- [NocoDB](https://github.com/nocodb/nocodb): for visualizing and querying transactions, a simple and easy to use interface for SQLite
### Frontend
[ADD INFO]
## ✨ Features
@@ -39,8 +37,6 @@ Having your bank data accessible through both CLI and REST API gives you the pow
### 📡 API & Integration
- **REST API**: Complete FastAPI backend with comprehensive endpoints
- **CLI Interface**: Enhanced command-line tools with new options
- **Health Checks**: Service monitoring and dependency management
- **Auto-reload**: Development mode with file watching
### 🔔 Notifications & Monitoring
- Discord and Telegram notifications for filtered transactions
@@ -48,12 +44,6 @@ Having your bank data accessible through both CLI and REST API gives you the pow
- Account expiry notifications and status alerts
- Comprehensive logging and error handling
### 📊 Visualization & Analysis
- NocoDB integration for visual data exploration
- Transaction statistics and reporting
- Account balance tracking over time
- Export capabilities for further analysis
## 🚀 Quick Start
### Prerequisites
@@ -216,7 +206,7 @@ The FastAPI backend provides comprehensive REST endpoints:
- `GET /api/v1/banks/status` - Connection status
- `GET /api/v1/banks/countries` - Supported countries
### Accounts & Balances
### Accounts & Balances
- `GET /api/v1/accounts` - List all accounts
- `GET /api/v1/accounts/{id}` - Account details
- `GET /api/v1/accounts/{id}/balances` - Account balances
@@ -262,7 +252,7 @@ Run the comprehensive test suite with:
# Run all tests
uv run pytest
# Run unit tests only
# Run unit tests only
uv run pytest tests/unit/
# Run with verbose output
@@ -293,7 +283,7 @@ leggen/ # CLI application
├── utils/ # Shared utilities
└── api_client.py # API client for leggend service
leggend/ # FastAPI backend service
leggend/ # FastAPI backend service
├── api/ # API routes and models
├── services/ # Business logic
├── background/ # Background job scheduler