satmachineclient/DCA-System-Implementation-Plan.md

DCA System Implementation Plan

Current State

• Base Extension: SatoshiMachine (template extension)
• Structure: Complete LNBits extension with all necessary files
• Status: Ready to be overwritten with DCA functionality

Updated System Design Based on Clarifications

1. Data Integration Solution - CSV Fetch Approach

Implementation: Admin extension will fetch CSV data using the provided bash script pattern:

• Execute SSH commands to export transaction data from Lamassu server
• Download CSV files: cash_out_txs.csv, cash_in_txs.csv, cash_out_actions.csv
• Process CSV data to identify new successful transactions
• Alternative: Direct Postgres connection (read-only) for real-time processing

Benefits:

• Secure (read-only access)
• Reliable data export from Lamassu
• Network security through SSH

2. Proportional Distribution Logic (CLARIFIED)

Flow Mode Distribution:

# Example: Client A: 9,000 GTQ, Client B: 1,000 GTQ (Total: 10,000 GTQ)
# New transaction: 2,000 GTQ principal after commission

client_a_share = (9000 / 10000) * 2000 = 1800 GTQ worth of BTC
client_b_share = (1000 / 10000) * 2000 = 200 GTQ worth of BTC

# Convert to satoshis using transaction exchange rate
client_a_sats = 1800 * (crypto_atoms / fiat_amount)
client_b_sats = 200 * (crypto_atoms / fiat_amount)

3. System Architecture - Shared Database Approach

Admin Extension (Primary):

• Hosts all data models and business logic
• Processes transaction data (CSV/Postgres)
• Manages DCA distributions
• Provides internal API endpoints
• Must be active for system to function

Client Extension (Interface):

• User-facing dashboard
• Calls admin extension's internal APIs
• No direct database access
• Lightweight interface layer

4. Fixed Mode Configuration

System-Wide Settings:

• Admin configures Fixed Mode timing globally
• Maximum daily limit: 2000 GTQ per client
• Insufficient funds handling: LNBits wallet "top-up" or Nostr notification

5. Authentication & User Mapping

Client Identification:

• User selects DCA wallet in client extension (standard LNBits pattern)
• Wallet cannot be changed after initiation (maintains transaction integrity)
• Admin manually adds clients using user_id + deposit amount
• No separate registration process required

6. Real-Time Updates Strategy

Recommended Approach: Polling-based for this use case

• Client dashboard polls admin APIs every 30-60 seconds
• Lower complexity than WebSocket for this scenario
• Sufficient responsiveness for DCA monitoring
• LNBits handles actual payment notifications

Implementation Architecture

Phase 1: Admin Extension (Core System)

1. Database Models:

   • DCA clients and deposits
   • Transaction processing tracking
   • Commission distribution configuration
   • Distribution history

2. Transaction Processing:

   • CSV data fetching and parsing
   • Duplicate detection using transaction IDs
   • Flow Mode distribution calculations
   • Commission distribution system

3. Admin Interface:

   • Client management dashboard
   • Transaction monitoring
   • Commission distribution configuration
   • System health monitoring

Phase 2: Client Extension (User Interface)

1. Dashboard Components:

   • DCA overview and metrics
   • Transaction history
   • Settings management
   • Performance analytics

2. API Integration:

   • Read-only access to admin extension APIs
   • Real-time balance and status updates
   • Settings synchronization

Technical Specifications

Data Flow

Lamassu ATM → CSV Export → Admin Extension → Process & Distribute → Client Extensions Display

Security Model

• Admin extension: Full database access, transaction processing
• Client extension: Read-only API access, user-specific data only
• CSV/SSH: Secure remote data fetching with credentials management

Commission Distribution System

• Configurable percentage allocation to specified wallets
• Can include DCA clients in commission distribution
• Separate from Flow Mode distribution
• Admin-controlled allocation rules

Error Handling

• Insufficient Fixed Mode funds: LNBits wallet top-up + Nostr notification
• Failed transactions: Comprehensive logging and admin alerts
• Network issues: Retry mechanisms and offline mode handling

File Structure Transformation

From Current Template:

dca_admin/
├── templates/dca_admin/
│   ├── index.html
│   ├── dca_admin.html
│   └── _dca_admin.html
├── static/
├── models.py
├── crud.py
├── views.py
├── views_api.py
└── config.json

To DCA System:

dca_admin/                    # Admin Extension
├── templates/dca_admin/
│   ├── index.html
│   ├── client_management.html
│   ├── transaction_monitor.html
│   └── commission_config.html
├── static/
├── models.py                 # DCA clients, transactions, distributions
├── crud.py                   # Database operations
├── views.py                  # Admin interface
├── views_api.py             # Internal APIs for client extension
├── transaction_processor.py # CSV processing & distribution logic
└── config.json

dca_client/                   # Client Extension  
├── templates/dca_client/
│   ├── index.html
│   ├── dashboard.html
│   └── analytics.html
├── static/
├── models.py                 # Minimal client-side models
├── views.py                  # Client interface
├── views_api.py             # Client API endpoints
└── config.json

Next Steps

1. Create updated specifications for both extensions
2. Transform current template into DCA admin extension
3. Create new client extension from scratch
4. Implement CSV processing and distribution logic
5. Build admin interface for system management
6. Create client dashboard with analytics
7. Test integration and distribution calculations

Key Decisions Confirmed

✅ Data Source: CSV fetch with SSH (+ optional direct Postgres) ✅ Architecture: Shared database via admin extension APIs ✅ Distribution: Proportional by deposit amounts ✅ Fixed Mode: System-wide 2000 GTQ daily limit ✅ Authentication: LNBits user_id + selected wallet ✅ Updates: Polling-based (30-60 seconds) ✅ Commission: Separate configurable distribution system

The system is now fully specified and ready for implementation! 🚀