mirror of
https://github.com/elisiariocouto/leggen.git
synced 2025-12-11 17:22:18 +00:00
Cleanup agent documentation.
This commit is contained in:
committed by
Elisiário Couto
parent
16afa1ed8a
commit
bc947183e3
41
AGENTS.md
Normal file
41
AGENTS.md
Normal 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
|
||||
69
CLAUDE.md
69
CLAUDE.md
@@ -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
|
||||
91
PROJECT.md
91
PROJECT.md
@@ -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
|
||||
22
README.md
22
README.md
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user