FinanceX - Retirement Calculator

A comprehensive retirement planning application with Brazilian Real (BRL) support. Built with Django REST Framework backend and Next.js 14 frontend.

🚀 Features

• 📊 Comprehensive Calculations: Two-phase retirement planning (accumulation + sustainability)
• 📈 Interactive Charts: Beautiful visualizations with Recharts showing wealth accumulation
• 💰 BRL Currency Support: Full Brazilian Real formatting and localization
• 🎯 Advanced Options:
  • Custom inflation rates
  • Annual return rates
  • Monthly contribution increases
  • One-time deposits and withdrawals
• 📱 Responsive Design: Mobile-first approach with modern UI
• ⚡ Real-time Updates: Instant calculations with interactive sliders
• 🎨 Modern UI: Built with Tailwind CSS and shadcn/ui components

📋 Prerequisites

• Python 3.10 or higher
• Node.js 18.0 or higher
• npm, yarn, or pnpm

🛠️ Installation

Option 1: Quick Setup with UV (Recommended - 10x Faster! ⚡)

UV is a blazingly fast Python package installer. Setup time: ~3 seconds!

# Install UV (one time)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Run automated setup
./setup-uv.sh

Or manually:

# Backend
cd backend
uv venv
source .venv/bin/activate
uv pip install -r requirements.txt
python manage.py migrate
python manage.py runserver

See backend/UV_SETUP.md for detailed UV instructions.

Option 2: Traditional Setup with pip

Backend Setup (Django)

1. Navigate to the backend directory:

cd backend

2. Create and activate a virtual environment:

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

3. Install dependencies:

pip install -r requirements.txt

4. Run migrations:

python manage.py migrate

5. Start the development server:

python manage.py runserver

The API will be available at http://localhost:8000

Frontend Setup (Next.js)

1. Navigate to the frontend directory:

cd frontend

2. Install dependencies:

npm install
# or
yarn install
# or
pnpm install

3. Create environment file:

echo "NEXT_PUBLIC_API_URL=http://localhost:8000" > .env.local

4. Start the development server:

npm run dev
# or
yarn dev
# or
pnpm dev

The application will be available at http://localhost:3000

📖 Usage

1. Configure Basic Parameters:

   • Current age
   • Initial investment
   • Monthly contributions
   • Desired retirement age
   • Monthly expenses after retirement

2. Advanced Settings (Optional):

   • Annual return rate (default: 10%)
   • Annual inflation rate (default: 5%)
   • Annual contribution increase rate

3. Add One-time Events (Optional):

   • One-time deposits (e.g., inheritance, bonus)
   • One-time withdrawals (e.g., emergency expenses)

4. Calculate: Click the "CALCULAR APOSENTADORIA" button to see your results

🏗️ Project Structure

financex/
├── backend/                 # Django REST API
│   ├── calculator/         # Calculator app
│   │   ├── calculations.py # Core calculation engine
│   │   ├── serializers.py  # DRF serializers
│   │   ├── views.py        # API views
│   │   └── urls.py         # URL routing
│   ├── financex/           # Django project settings
│   └── manage.py           # Django management script
│
└── frontend/               # Next.js application
    ├── src/
    │   ├── app/           # Next.js 14 App Router
    │   ├── components/    # React components
    │   │   ├── ui/       # shadcn/ui components
    │   │   ├── BasicInputs.tsx
    │   │   ├── AdvancedInputs.tsx
    │   │   ├── OneTimeEventsModal.tsx
    │   │   ├── RetirementChart.tsx
    │   │   ├── ResultsDisplay.tsx
    │   │   └── RetirementCalculator.tsx
    │   └── lib/          # Utilities and types
    │       ├── api.ts    # API client
    │       ├── types.ts  # TypeScript interfaces
    │       └── utils.ts  # Helper functions
    └── package.json

🧮 How It Works

Accumulation Phase

The calculator uses compound interest formulas to project wealth accumulation:

Monthly Rate = (1 + Annual Rate)^(1/12) - 1
Balance = Balance × (1 + Monthly Rate) + Monthly Contribution

Features:

• Monthly compounding
• Annual contribution increases
• One-time deposits/withdrawals
• Inflation adjustment

Retirement Phase

Calculates sustainability of retirement funds:

Balance = Balance × (1 + Monthly Rate) - Monthly Withdrawal
Withdrawal adjusted annually for inflation

Continues until balance reaches zero or age 120.

🌐 API Endpoints

POST /api/calculate/

Calculate retirement plan.

Request Body:

{
  "current_age": 32,
  "initial_investment": 200000.00,
  "monthly_contribution": 1200.00,
  "retirement_age": 65,
  "monthly_expenses_retirement": 5000.00,
  "annual_return_rate": 10.0,
  "annual_inflation_rate": 5.0,
  "annual_contribution_increase": 0.0,
  "one_time_deposits": [
    {"year": 2025, "month": 6, "value": 10000.00}
  ],
  "one_time_withdrawals": []
}

Response:

{
  "total_accumulated": "1505154.14",
  "sustainability_age": 89,
  "years_of_retirement": 24,
  "monthly_data": [...],
  "summary": {...}
}

GET /api/health/

Health check endpoint.

🎨 Tech Stack

Backend

• Django 5.0: Web framework
• Django REST Framework: API development
• django-cors-headers: CORS support
• Python Decimal: Precise financial calculations

Frontend

• Next.js 14: React framework with App Router
• TypeScript: Type safety
• Tailwind CSS: Styling
• shadcn/ui: UI components (Radix UI)
• Recharts: Data visualization
• Axios: HTTP client
• Zustand: State management

🔧 Configuration

Backend Configuration

Edit backend/financex/settings.py:

• ALLOWED_HOSTS: Add production domains
• CORS_ALLOWED_ORIGINS: Update for production frontend URL
• DEBUG: Set to False in production

Frontend Configuration

Environment variables in .env.local:

• NEXT_PUBLIC_API_URL: Backend API URL

📝 Example Calculation

Input:

• Current age: 32
• Initial investment: R$ 200,000
• Monthly contribution: R$ 1,200
• Retirement age: 65
• Monthly expenses: R$ 5,000
• Annual return: 10%
• Annual inflation: 5%

Output:

• Total accumulated: R$ 1,505,154.14
• Sustainability age: 89 years
• Years in retirement: 24 years

🚀 Deployment

Backend (Django)

1. Set DEBUG=False in settings
2. Configure database (PostgreSQL recommended)
3. Collect static files: python manage.py collectstatic
4. Use gunicorn or similar WSGI server
5. Set up reverse proxy (nginx)

Frontend (Next.js)

1. Build the application: npm run build
2. Start production server: npm start
3. Or deploy to Vercel/Netlify for automatic deployment

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📄 License

This project is open source and available under the MIT License.

👤 Author

Built with ❤️ for better financial planning in Brazil.

🙏 Acknowledgments

• Inspired by InvestNews Retirement Simulator
• UI components from shadcn/ui
• Charts powered by Recharts

---

Note: This calculator provides estimates based on the parameters you input. Actual investment returns may vary. Always consult with a financial advisor for personalized advice.