Budget Management System (BMS)

A role-based Django web app for managing department budgets, expenses, and budget increment requests. It provides dashboards for Managers and Admins, workflows to request and approve budget increments, and an activity history.

Overview

• Roles

  • Admin: Manages departments, users, budgets; reviews budget increment requests; views analytics and history.
  • Manager: Manages components and expenses for their department; requests incremental budget; views department analytics and request history.

• Key Features

  • Monthly base budget + incremental budget per department
  • Manager expense tracking by components
  • Budget increment request workflow (pending → approved/rejected/revised)
  • Admin dashboard with KPI cards and charts
  • Activity History (audit log) for requests and entity CRUD

Tech Stack

• Backend: Django 5, Python 3.11
• DB: SQLite (default) or any Django-supported DB
• Frontend: Django templates + Chart.js
• Auth: Django auth + role-based access via UserProfile

Project Structure

• finance app: domain models (Budget, Expense, Component, BudgetRequest, ActivityLog), analytics views (admin dashboard), utilities (log_activity)
• userapp: auth, role redirects, manager/admin UI views, request workflow
• templates: UI for dashboards, requests, history, CRUD pages

Data Model (simplified)

• Department
  • name, code, description
  • managers via UserProfile.role='manager'
• UserProfile
  • user (FK), role ('admin'|'manager'), department (FK nullable)
• Component
  • department (FK), name, amount (used as configurable metadata), created_at
• Expense
  • component (FK), amount (Decimal), description, expense_date (DateField), status, created_by (FK), created_at
• Budget
  • department (FK), budget_type ('monthly'|'increment'), month (DateField: first day of month), amount (Decimal), notes, created_by (FK), created_at
  • UNIQUE(department, budget_type, month) enforced by code (use update_or_create/get_or_create)
• BudgetRequest
  • department (FK), requested_by (FK), requested_amount (Decimal), month (DateField), reason, status ('pending'|'approved'|'rejected'|'revised'), admin_notes, reviewed_by (FK), reviewed_at, requested_at
• ActivityLog
  • actor (FK User), action_type (choices), target_type, target_id, description, metadata (JSON), created_at

Workflow

1. Manager requests incremental budget

• Manager fills amount/reason → BudgetRequest(status='pending', month=first-day-of-month).
• Admin reviews in “Budget Requests”:
  • Approve → add amount to Budget increment for that department+month (upsert and add).
  • Reject → mark request rejected with optional note.
  • Revise → mark request revised and overwrite the increment amount to new value.
• Logging: Each action is recorded in ActivityLog for admin history.

2. Budgets

• Monthly budget: one record per department per month (base).
• Increment: one record per department per month (single upsert row; total increments are added to this amount).
• Total assigned budget for a month = base + increment.

3. Expenses

• Managers add expenses against components in their department.
• Charts show distribution and trends (per-department, across months).

Dashboards

• Manager Dashboard

  • KPI: current budget, expenses, remaining, pending requests
  • Charts: Pie (components), Line (last 6 months), Double Bar (budget vs expenses last 6)
  • Recent expenses list

• Admin Dashboard

  • Top 4 KPI cards (full-width row):
    • Total Budget (month sum across departments)
    • Total Expenses (month sum across departments)
    • Remaining Budget
    • Pending Requests count
  • Charts: Pie (dept expense distribution), Line (last 6 months per dept), Double Bar (assigned vs expenses, last 6), plus placeholder component

• Admin History

  • Filterable list of ActivityLog showing:
    • Budget request actions (create/approve/reject/revise)
    • Entity CRUD (department, budget, component, user)
  • Pagination, search, action filter

Setup

• Requirements

  • Python 3.11+
  • pip, virtualenv
  • Windows Terminal or VS Code integrated terminal

• Installation

  cd e:\Project2\bms\BMS
  python -m venv ..\env
  ..\env\Scripts\activate
  pip install -r requirements.txt
  

• Django Configuration

  • settings.py
    • Add apps: 'finance', 'userapp'
    • Ensure templates and static settings
    • DB defaults are fine for SQLite

• Migrations

  ..\env\Scripts\activate
  python manage.py makemigrations
  python manage.py migrate
  

• Create Superuser

  python manage.py createsuperuser
  

• Run Server

  python manage.py runserver 8000
  # If it crashes, use:
  python manage.py runserver 8000 --noreload
  

• Access

  • Admin Dashboard: http://127.0.0.1:8000/admin-dashboard/
  • Budget Requests: http://127.0.0.1:8000/admin-dashboard/budget-requests/
  • Admin History: http://127.0.0.1:8000/admin-dashboard/history/
  • Manager Dashboard: http://127.0.0.1:8000/manager-dashboard/

Important Implementation Notes

• Month Field

  • Budget.month is a DateField storing the first day of month (canonical key).
  • Always upsert using update_or_create/get_or_create with month=first-day-of-month to avoid UNIQUE conflicts.

• Increment Logic

  • Approve: add requested_amount to existing increment row (get_or_create, then inc.amount += requested_amount).
  • Revise: overwrite increment row with new_amount (inc.amount = new_amount) and mark request as 'revised'.

• History Logging

  • Implement log_activity in finance/utils.py and call it in:
    • manager_request_budget (create)
    • admin_approve_budget_request
    • admin_reject_budget_request
    • admin_revise_budget_request
    • entity CRUD (departments, budgets, components, users)
  • Migrate after adding ActivityLog.

• Template Safety

  • Use Django template comments {# ... #} instead of HTML when disabling {% url %} tags.
  • For Chart.js data, pass JSON via context and parse with escapejs:

    const labels = JSON.parse('{{ labels_json|default:"[]"|escapejs }}');
    

Troubleshooting

• NoReverseMatch for template link

  • Ensure route name exists and is included in project URLs.
  • Comment out with {# ... #} if route not ready.

• “no such table: finance_activitylog”

  • Run migrations: makemigrations finance, migrate.

• UNIQUE constraint on Budget

  • Use get_or_create/update_or_create for (department, budget_type, month).
  • Do not create duplicate increment rows for the same month.

• “site can’t be reached”

  • Ensure server running and on correct port.
  • Fix import errors in urls/views; remove dead routes (e.g., unused accountant pages).

Future Enhancements

• Role-based nav consolidation via base template
• Advanced permissions and audit details (IP, request data)
• Export logs as CSV
• Alerts for overspending thresholds
• Tests for workflows (requests, budget upserts, charts)

License

Internal project. Avoid committing secrets or production credentials.