Skip to main content

Overview

This guide walks you through FinAI’s core workflow: from account creation to recording your first AI-categorized transaction. By the end, you’ll understand how to leverage natural language processing for effortless expense tracking.
Prerequisites: Complete the Installation Guide and ensure the application is running at http://127.0.0.1:5000

Create Your Account

1

Navigate to Registration

Open your browser and go to:
http://127.0.0.1:5000/register
You’ll see the registration form where you can create your personal FinAI account.
2

Fill in Your Details

Provide the following information:
FieldDescriptionExample
Full NameYour display name in the appJohn Doe
EmailUsed for login and password reset[email protected]
PasswordMinimum 6 characters recommended•••••••••
Confirm PasswordMust match the password above•••••••••
Passwords must match exactly. The system validates this before account creation.
3

Submit and Login

Click the Register button. Upon successful registration:
app/routes/auth.py
# 1. Creates user account
new_user = User(id=new_user_id, name=fullname, email=email)
new_user.set_password(password)

# 2. Creates default settings
db.session.add(UserSetting(user_id=new_user_id))

# 3. Creates default cash wallet with 0 balance
db.session.add(Wallet(
    id=str(uuid.uuid4())[:8],
    user_id=new_user_id,
    name="Ví tiền mặt",
    type="Tiền mặt",
    balance=0
))
You’ll be redirected to the login page. Use your email and password to sign in.

Dashboard Overview

After logging in, you’ll land on the main dashboard which displays:

Wallet Summary

Total balance across all your wallets with breakdown by type (Cash, Bank, Credit Card)

Recent Transactions

Latest income, expense, and transfer activities with AI-detected categories

Visual Charts

Interactive pie and bar charts showing spending patterns by category

AI Chatbot

Context-aware assistant ready to answer questions about your finances

Set Up Additional Wallets

While you start with a default cash wallet, you can add multiple fund sources:
1

Open Wallet Management

Navigate to the Wallets section from the dashboard sidebar or menu.
2

Add New Wallet

Click Add Wallet and provide:
  • Wallet Name: e.g., “Vietcombank Checking”, “Credit Card”
  • Wallet Type: Cash, Bank Account, Credit Card, or E-Wallet
  • Initial Balance: Starting amount (optional)
Example wallets to set up:
NameTypeInitial Balance
Cash WalletTiền mặt1,000,000 VND
VietcombankNgân hàng5,000,000 VND
MomoVí điện tử500,000 VND
3

View Wallet Balances

All wallets are now tracked separately. Transactions will automatically update the respective wallet balances.
Balance Tracking: FinAI automatically adjusts wallet balances based on income (increases), expenses (decreases), and transfers (moves between wallets).

Record Your First Transaction

This is where FinAI’s AI-powered categorization shines. Let’s record an expense using natural language:
1

Open Transaction Form

From the dashboard, click Add Transaction or navigate to the Transactions page.Select the transaction type:
  • Expense (Chi): Money going out
  • Income (Thu): Money coming in
  • Transfer (Chuyển): Moving money between your wallets
2

Use Natural Language Description

Instead of manually selecting categories, simply describe the transaction naturally:
Dinner with friends at restaurant 500k
FinAI’s AI will analyze your description and automatically:
  1. Detect the category (Dining, Transportation, Shopping)
  2. Extract the amount (500,000 / 75,000 / 1,200,000 VND)
  3. Provide a confidence score
The ai_service.py module sends your description to Google Gemini 2.0 Flash:
app/ai_service.py
def predict(self, text, user_categories):
    prompt = f"""
    Bạn là một hệ thống phân loại tài chính tự động. 
    Phân loại giao dịch sau vào đúng MỘT trong các danh mục người dùng đã tạo.
    
    Danh mục hiện có: {', '.join(user_categories)}
    Giao dịch cần phân loại: "{text}"
    
    Trả về JSON: {{"category": "Tên danh mục", "confidence": 95}}
    """
    
    response = self.client.models.generate_content(
        model='gemini-2.5-flash',
        contents=prompt,
        config=types.GenerateContentConfig(
            response_mime_type="application/json"
        )
    )
    
    result = json.loads(response.text.strip())
    return result
The AI returns structured JSON with the detected category and confidence level.
3

Select Wallet and Confirm

Choose which wallet to debit/credit:
  • For Expenses: Select the wallet to deduct money from
  • For Income: Select the wallet to add money to
  • For Transfers: Select both source and destination wallets
Review the AI-suggested category (you can override it manually if needed) and click Save Transaction.
4

Transaction Saved

Your transaction is now recorded! The system automatically:
app/routes/transaction.py
# 1. Creates transaction record
new_trans = Transaction(
    id=str(uuid.uuid4())[:8],
    user_id=user_id,
    wallet_id=final_wallet_id,
    category_id=data.get('category_id'),
    type='chi',  # expense
    amount=amount,
    description=data.get('description'),
    date=datetime.now(),
    ai_category_id=data.get('ai_category_id'),
    ai_confidence=data.get('ai_confidence')
)

# 2. Updates wallet balance
wallet = Wallet.query.get(final_wallet_id)
wallet.balance -= amount  # Deduct for expense

db.session.commit()
Balance updates happen atomically - if the transaction fails, the wallet balance is rolled back automatically.

Try the AI Chatbot

FinAI’s chatbot uses Retrieval Augmented Generation (RAG) to provide context-aware answers based on your actual financial data:
1

Open Chatbot Interface

Look for the chatbot icon in the bottom-right corner of the dashboard or navigate to the AI Assistant page.
2

Ask Financial Questions

Try these example queries:
How much money do I have left in my Vietcombank account?
3

Receive Real-Time Insights

The chatbot analyzes your transaction history and wallet balances to provide accurate, personalized responses:
app/ai_service.py
def chat_with_data(self, user_question, context_data):
    prompt = f"""
    Bạn là FinAI – một trợ lý tài chính cá nhân thông minh.

    Dữ liệu tài chính gần đây của người dùng:
    {context_data}

    Câu hỏi: "{user_question}"

    QUY TẮC KẾ TOÁN (BẮT BUỘC):
    - "CHI TIÊU" = tiền ra khỏi hệ thống.
    - "CHUYỂN KHOẢN" = tiền chuyển giữa ví → KHÔNG phải chi tiêu.
    - Khi tính tổng chi tiêu: TUYỆT ĐỐI không cộng chuyển khoản.
    """
    
    response_stream = self.client.models.generate_content_stream(
        model='gemini-2.5-flash',
        contents=prompt
    )
    return response_stream
The chatbot correctly distinguishes between expenses (money leaving your system) and transfers (money moving between your wallets). Transfers are NOT counted as spending.

Manage Categories

FinAI adapts to YOUR spending patterns by learning from custom categories:
1

View Default Categories

Navigate to Categories from the sidebar. You’ll see system-provided categories like:
  • Income Categories: Salary, Freelance, Investment
  • Expense Categories: Food, Transportation, Shopping, Entertainment, Bills
2

Create Custom Categories

Click Add Category and define:
  • Category Name: e.g., “Coffee Addiction”, “Gym Membership”
  • Type: Income or Expense
  • Parent Category (optional): Group under existing categories
Example custom categories:
Parent: Food
├── Breakfast
├── Lunch
└── Dinner

Parent: Transportation
├── Grab/Taxi
├── Bus/Metro
└── Parking
3

AI Learns Your Categories

Once created, the AI will automatically map future transactions to your custom categories:
app/ai_service.py
# AI receives your custom category list
def predict(self, text, user_categories):
    prompt = f"""
    Danh mục hiện có: {', '.join(user_categories)}
    Giao dịch cần phân loại: "{text}"
    """
This ensures categorization is personalized to your financial habits.

View Reports and Analytics

Visualize your financial health with built-in reporting tools:
Access from the Reports or Dashboard page:
  • Pie Chart: Spending breakdown by category
  • Bar Chart: Monthly expense trends
  • Line Chart: Cash flow over time
All charts are powered by Chart.js and update in real-time as you add transactions.
Download your transaction history for offline analysis:
  1. Navigate to ReportsExport Data
  2. Select date range
  3. Click Export to Excel
  4. Opens a .xlsx file with all transaction details
app/routes/report.py
# Uses Pandas to generate Excel files
df = pd.DataFrame(transactions)
df.to_excel('transactions_export.xlsx', index=False)

Common Workflows

Scenario: You just paid 45k for lunch.
1

Quick Add

Click Add Transaction → Select Expense
2

Natural Description

Type: Lunch at office cafeteria 45k
3

AI Categorizes

FinAI detects: Category = “Food”, Amount = 45,000 VND
4

Select Wallet & Save

Choose “Cash Wallet” → Click Save
Time taken: ~15 seconds
Scenario: Check if you’re staying within your entertainment budget.
1

Ask Chatbot

Open chatbot and ask: How much did I spend on entertainment this month?
2

Review Chart

Go to Reports → View category pie chart
3

Compare Budget

Navigate to Budgets → Check Entertainment budget progress
Scenario: You withdrew 1,000,000 VND from your bank to cash wallet.
1

Add Transfer

Click Add Transaction → Select Transfer
2

Select Wallets

  • From: Vietcombank
  • To: Cash Wallet
  • Amount: 1,000,000 VND
3

Save Transaction

System automatically deducts from bank and adds to cash
app/routes/transaction.py
# Transfer logic
if db_type == 'chuyen':
    wallet.balance -= amount          # Deduct from source
    dest_wallet.balance += amount     # Add to destination

Pro Tips

Consistent Descriptions

Use similar phrasing for recurring expenses to improve AI accuracy:
  • “Coffee at Starbucks” vs “Starbucks coffee”
  • “Grab to office” vs “Taxi to work”

Regular Chatbot Checks

Ask the chatbot weekly: “How’s my spending this week?” to catch unusual patterns early

Review AI Suggestions

When AI miscategorizes, manually correct it by editing the transaction category in the dashboard

Export Monthly

Download Excel reports at month-end for tax preparation or personal record-keeping

What’s Next?

Now that you’ve mastered the basics, explore advanced features:

API Integration

Integrate FinAI with other apps via REST API

Budget Planning

Set monthly spending limits and alerts

Admin Dashboard

Manage users and system settings (admin only)
Need Help? If you encounter issues or have questions, check the Installation Guide or reach out to the developer at [email protected].

Build docs developers (and LLMs) love