InvestCLI - Conversational Investment Portfolio Management

A modern, chat-first investment portfolio management CLI built with Node.js/TypeScript and PostgreSQL. Features natural language understanding, intelligent entity resolution, and conversational interaction.

🚀 Features

Conversational Interface

• Chat-first design: Natural language interaction instead of complex commands
• Session management: Maintains context across conversation
• Intent classification: Understands what you want to do
• Entity resolution: Resolves account and asset names intelligently
• Action confirmation: Shows preview before executing changes

Portfolio Management

• Query balances and positions
• Register transactions (buy, sell, transfer, deposit, withdrawal)
• Track multi-currency holdings
• Geographic distribution analysis
• Account reconciliation

Architecture

• Domain-Driven Design: Clean separation of concerns
• Double-entry bookkeeping: Accurate transaction tracking
• Audit logging: Full history of all changes
• PostgreSQL: Robust data persistence
• TypeScript: Type-safe implementation

🏗️ Architecture

src/
├── chat/                    # Session and conversation state
│   ├── conversation-state.ts
│   └── session-manager.ts
├── ai/                      # Natural language processing
│   ├── intent-classifier.ts
│   ├── entity-resolver.ts
│   └── action-planner.ts
├── application/             # Business logic
│   └── action-executor.ts
├── domain/                  # Core entities
│   └── entities.ts
├── infrastructure/          # Database layer
│   └── database.ts
├── repositories/            # Data access
│   ├── account-repository.ts
│   └── transaction-repository.ts
├── shared/                  # Common types
│   └── enums.ts
└── cli/                     # User interface
    ├── chat-agent.ts
    └── interactive-agent.ts

📦 Installation

Global Installation

npm install -g investcli

Local Installation

npm install investcli

From Source

git clone https://github.com/yourusername/investcli.git
cd investcli
npm install
npm run build

🎯 Quick Start

Set up database connection

export DATABASE_URL="postgresql://user:password@host:port/database"

Start the chat interface

investcli

Or with npm:

npm run chat

💬 Usage Examples

Queries

> quanto tenho em XP João?
> minhas posições
> distribuição geográfica
> onde está meu dinheiro?

Transactions

> transfere 5000 da Nubank para IBKR
> adiciona 10000 para Inter Investimentos
> remove 2000 de XP João
> vendi metade de google
> comprei 10 ações da apple a 150 dólares

Commands

> /help          # Show all commands
> /status        # Session status
> /context       # Current context
> /cancel        # Cancel pending action
> /clear         # Clear screen
> /exit          # Exit

🤖 How It Works

1. Intent Classification

When you type a message, the system classifies your intent:

"transfere 5000 da XP para Inter" → REGISTER_TRANSFER
"quanto tenho em dólar?" → QUERY_BALANCE
"minhas posições" → QUERY_POSITIONS

2. Entity Resolution

Resolves natural language references to database entities:

"XP" → Account: "XP João"
"google" → Asset: "GOOGL"
"5000" → Amount: 5000 BRL

3. Action Planning

Creates a structured action with preview:

Ação Proposta:
- tipo: transferência
- origem: XP João
- destino: Inter Investimentos
- valor: BRL 5.000,00

Confirmar? (y/n)

4. Execution

After confirmation, executes the action with full audit trail.

System Design Principles

Event Sourcing

• Transactions are the source of truth
• Positions and balances are derived from transaction history
• No direct editing of aggregated values

Immutability

• Transactions are immutable once created
• Corrections are done via reversal or adjustment transactions
• Complete audit trail maintained

Multi-Currency

• Every monetary value carries its currency
• No implicit currency assumptions
• FX rates can be tracked separately

Reconciliation

• Compare observed balances (from statements) with calculated balances
• Detect discrepancies automatically
• Suggest possible causes with confidence scores

AI Safety

• AI never writes directly to database
• All actions go through domain validation
• Confirmation required for ambiguous or high-risk operations
• Canonical action schema prevents SQL injection

Project Structure

investcli/
├── src/
│   ├── domain/              # Domain entities and services
│   │   ├── entities.py
│   │   ├── value_objects.py
│   │   └── services/
│   ├── application/         # Use cases and DTOs
│   │   ├── dtos.py
│   │   └── use_cases/
│   ├── repositories/        # Data access layer
│   ├── infrastructure/      # Database, logging
│   ├── ai/                  # AI orchestration
│   └── cli/                 # Command-line interface
├── migrations/              # SQL migrations
├── scripts/                 # Utility scripts
├── requirements.txt
├── .env
└── investcli.py            # Main entry point

🔧 Technical Stack

• Language: TypeScript/Node.js
• Database: PostgreSQL with pg driver
• CLI Framework: Native readline
• UI: chalk, ora, boxen, cli-table3
• Architecture: DDD + Event Sourcing
• Build: TypeScript compiler

⚙️ Configuration

Environment variables:

• DATABASE_URL: PostgreSQL connection string (required)

Example:

export DATABASE_URL="postgresql://user:password@localhost:5432/investcli"

🔧 Development

Build

npm run build

Run in development

npm run chat

Run tests

npm test

Engineering Principles

1. No Prisma migrations - Only raw SQL migrations
2. Idempotent operations - Safe to run multiple times
3. Event-driven - All state changes are events
4. Auditable - Complete audit trail
5. Type-safe - Full TypeScript coverage

🌍 Multi-Currency Support

Supports multiple currencies with automatic detection:

• BRL (Brazilian Real)
• USD (US Dollar)
• EUR, GBP, and others

📊 Database Schema

The system uses PostgreSQL with the following main tables:

• Account: Investment accounts (bank, broker, wallet, etc.)
• Asset: Tradable assets (stocks, bonds, funds, etc.)
• Transaction: Financial events
• Entry: Double-entry bookkeeping entries
• AuditLog: Complete audit trail

📝 License

MIT

🤝 Contributing

Contributions welcome! Please open an issue or PR.

📧 Support

For issues and questions, please open a GitHub issue.

Built with ❤️ using TypeScript, PostgreSQL, and modern CLI tools