Skip to main content

​
Prerequisites

Before installing FinAI, ensure you have the following:

Python 3.11+

Download from python.org

Google Gemini API Key

Get your free key from Google AI Studio

Git

Version control system to clone the repository

Email Account (Optional)

Gmail account for password reset functionality
AI Key Required: The Google Gemini API key is essential for AI categorization and chatbot features. FinAI will not function properly without it.

​
Installation Steps

1

Clone the Repository

Download the FinAI source code from GitHub:
git clone https://github.com/Montero52/finai-expense-manager.git
cd finai-expense-manager
This will create a finai-expense-manager directory with all the necessary source files.
2

Create Virtual Environment

Set up an isolated Python environment to avoid dependency conflicts:
python -m venv venv
venv\Scripts\activate
You should see (venv) prefix in your terminal prompt when activated.
3

Install Dependencies

Install all required Python packages using pip:
pip install -r requirements.txt
This installs the following core dependencies:
requirements.txt
Flask==3.1.2
flask_mail==0.10.0
flask_sqlalchemy==3.1.1
pandas==2.3.3
python-dotenv==1.2.1
SQLAlchemy==2.0.45
Werkzeug==3.1.5
google-generativeai
Installation typically takes 2-3 minutes depending on your internet speed.
4

Configure Environment Variables

Create a .env file in the root directory to store sensitive configuration:
touch .env
Add the following environment variables:
.env
# Security Key (Required)
# Generate a random string for production: python -c "import secrets; print(secrets.token_hex(32))"
SECRET_KEY=your_secret_key_here

# Google Gemini AI Key (Required)
# Get your key from: https://aistudio.google.com/app/apikey
GEMINI_API_KEY=your_google_gemini_api_key_here

# Email Configuration (Optional - for password reset)
# Use Gmail App Password (not your regular password)
[email protected]
MAIL_PASSWORD=your_gmail_app_password
Security Best Practice: Never commit your .env file to version control. Add it to .gitignore to keep your credentials safe.

​
Environment Variable Details

VariablePurposeRequiredDefault
SECRET_KEYFlask session encryption and CSRF protectionYeskhoa-mac-dinh-khong-an-toan (dev only)
GEMINI_API_KEYGoogle Gemini 2.0 Flash AI API accessYesNone
MAIL_USERNAMEGmail address for sending password reset emailsNoNone
MAIL_PASSWORDGmail App Password (not regular password)NoNone
Run this command in your terminal:
python -c "import secrets; print(secrets.token_hex(32))"
Copy the output and paste it as your SECRET_KEY value.
  1. Enable 2-Factor Authentication on your Gmail account
  2. Go to Google Account → Security → 2-Step Verification → App passwords
  3. Generate a new app password for “Mail”
  4. Copy the 16-character password (without spaces) to MAIL_PASSWORD
5

Initialize Database

FinAI uses SQLite for data storage, which requires no additional configuration. The database is automatically created when you run the application.
Automatic Setup: The database file will be created at instance/quanlychitieu.db on first run. This path is configured in config.py:
config.py
SQLALCHEMY_DATABASE_URI = 'sqlite:///' + os.path.join(BASE_DIR, 'instance', 'quanlychitieu.db')
The application automatically creates the instance directory and initializes all required tables:
app/__init__.py
# Auto-create instance directory
try:
    os.makedirs(app.instance_path)
except OSError:
    pass

# Initialize database
with app.app_context(): 
    db.create_all()
6

Create Admin Account

Run the setup script to create a superuser account for system management:
python create_admin.py
You should see this confirmation:
========================================
ĐÃ TẠO TÀI KHOẢN ADMIN THÀNH CÔNG!
Email: [email protected]
Pass:  admin123
========================================
Change Default Password: For production use, immediately change the admin password after first login. The default credentials are:

​
What the Script Does

The create_admin.py script performs the following operations:
create_admin.py
# 1. Creates admin user with role='admin'
admin_user = User(
    id=user_id,
    name="Quản Trị Viên Hệ Thống",
    email=ADMIN_EMAIL,
    role='admin',
    status=1
)
admin_user.set_password(ADMIN_PASS)

# 2. Creates default user settings
setting = UserSetting(user_id=user_id)

# 3. Creates a test wallet with 999,999,999 VND
wallet = Wallet(
    id=str(uuid.uuid4())[:8],
    user_id=user_id,
    name="Kho bạc Admin",
    type="Tiền mặt",
    balance=999999999
)
7

Launch the Application

Start the Flask development server:
python run.py
You should see output similar to:
* Serving Flask app 'app'
* Debug mode: on
* Running on http://127.0.0.1:5000
* Press CTRL+C to quit
Open your browser and navigate to:
http://127.0.0.1:5000
The development server runs with debug=True as configured in run.py. This enables automatic reloading when you modify code.

​
Verification

Confirm your installation is successful by checking:
Verify the SQLite database exists:
ls instance/
You should see quanlychitieu.db
Try logging in with:You should be redirected to the Admin Dashboard.
After logging in, try the chatbot or add a transaction with a natural language description. If the AI categorizes it correctly, your Gemini API key is configured properly.

​
Project Structure

Understanding the directory layout: 
finai-expense-manager/
├── app/
│   ├── __init__.py          # Flask app initialization, blueprint registration
│   ├── models.py            # SQLAlchemy models (User, Transaction, Wallet, etc.)
│   ├── ai_service.py        # Google Gemini AI integration
│   ├── utils.py             # Helper functions and decorators
│   └── routes/
│       ├── auth.py          # Login, register, password reset
│       ├── transaction.py   # Transaction CRUD operations
│       ├── ai.py            # AI categorization and chatbot endpoints
│       ├── report.py        # Data export and report generation
│       ├── admin.py         # Admin dashboard and user management
│       ├── budget.py        # Budget management (in development)
│       └── settings.py      # User settings and preferences
├── config.py                # Application configuration
├── create_admin.py          # Admin account setup script
├── run.py                   # Application entry point
├── requirements.txt         # Python dependencies
├── .env                     # Environment variables (you create this)
└── instance/
    └── quanlychitieu.db     # SQLite database (auto-generated)

​
Troubleshooting

Your virtual environment is not activated or dependencies are not installed.Solution:
# Activate virtual environment first
source venv/bin/activate  # macOS/Linux
venv\Scripts\activate     # Windows

# Then install dependencies
pip install -r requirements.txt
Your GEMINI_API_KEY is missing or invalid.Solution:
  1. Verify the key exists in your .env file
  2. Check for extra spaces or quotes around the key
  3. Generate a new key at Google AI Studio
  4. Restart the application after updating .env
Another process is accessing the SQLite database.Solution:
  • Close any database browsers (DB Browser for SQLite, etc.)
  • Ensure only one instance of the app is running
  • Restart the Flask server
Another application is using port 5000.Solution: Edit run.py to use a different port:
run.py
if __name__ == "__main__":
    app.run(debug=True, port=5001)  # Changed from default 5000

​
Next Steps

Your FinAI installation is complete! Continue to the Quick Start guide to:

Quick Start Guide

Create your first user account and record transactions

API Reference

Explore the REST API endpoints for integration
Production Deployment: This guide covers local development setup. For production deployment on platforms like AWS, Render, or Docker, see the Production Deployment guide.

Build docs developers (and LLMs) love

Get started for freeTalk to us