Getting Started

Follow these structured steps to clone, configure, and boot the application locally.

Prerequisites

• Node.js: version 18+ (20+ recommended)
• MongoDB: A local server instance or an active cloud cluster connection string
• OpenSSL: Installed and accessible in terminal for key pair generation

Step-by-Step Setup

git clone https://github.com/your-username/project-finance-management-software.git
cd project-finance-management-software

cd backend
npm install

# Generate Private Key
openssl genpkey -algorithm RSA -out private_key.pem -pkeyopt rsa_keygen_bits:2048

# Generate Public Key from Private Key
openssl rsa -pubout -in private_key.pem -out public_key.pem

PORT=3021
MONGO_URI=mongodb://localhost:27017/cost-management
JWT_SECRET=your_jwt_secret_phrase
ALLOWED_ORIGINS=http://localhost:5173

# Paste your \n formatted RSA keys here
RSA_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----\nMIIEvgIBADANBgkqhkiG9w0BAQEFAASCBKgwggSkAgEAAoIBAQ...\n-----END PRIVATE KEY-----\n"
RSA_PUBLIC_KEY="-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA...\n-----END PUBLIC KEY-----\n"

# Start in live-reloading Dev Mode
npm run dev

# Start in Standard Mode (Runs compiled script)
npm run start

cd ../frontend
npm install

VITE_API_URL=http://localhost:3021/api/v1
VITE_SECURE_STORAGE_KEY=your-secure-storage-key

# Paste the matching \n formatted RSA Public Key here
VITE_RSA_PUBLIC_KEY="-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA...\n-----END PUBLIC KEY-----\n"

npm run dev

Technical Specifications

Comprehensive list of languages, libraries, frameworks and packages utilized across this application.

Frontend Stack

Backend Stack

Architecture & Core Modules

Technical breakdown of directories, modules, and execution procedures.

Project File Map

A comprehensive directory mapping outlining the complete layout of code files, configurations, schemas, and routes across both servers and user interfaces:

project-root/
├── backend/                             # REST API Backend Service
│   ├── src/                             # Source code folder
│   │   ├── config/                      # Server-level config setups
│   │   │   └── logger.ts                # Winston rotation logger settings
│   │   ├── constants/                   # System-wide static variables
│   │   ├── controllers/                 # Route controllers (holds core database handlers)
│   │   │   ├── AuthController.ts        # Client session registration & access checks
│   │   │   ├── CategoryController.ts    # Income and expense categorization logic
│   │   │   ├── CostController.ts        # Project expense ledger entries CRUD
│   │   │   ├── DashboardController.ts   # System-wide KPIs & aggregations computation
│   │   │   ├── ProjectController.ts     # Main client projects tracker logic
│   │   │   ├── SettingsController.ts    # Corporate style customization properties
│   │   │   └── income.controller.ts     # Cash inflow ledger entry controls
│   │   ├── middleware/                  # Route level Express validation checks
│   │   │   ├── authMiddleware.ts        # Custom JWT security checks & RSA token filters
│   │   │   ├── rateLimiters.ts          # Express API route rate limiting controls
│   │   │   ├── requestLogger.ts         # Server call tracking and winston logging
│   │   │   ├── upload.ts                # Multer local image storage settings
│   │   │   └── validator.ts             # Zod data validation schema wrapper
│   │   ├── models/                      # MongoDB models (Mongoose collections)
│   │   │   ├── Category.ts              # Categories database fields model
│   │   │   ├── Cost.ts                  # Cost entry database fields model
│   │   │   ├── OTP.ts                   # Single use verification security codes model
│   │   │   ├── Project.ts               # Project details & outstanding model
│   │   │   ├── Settings.ts              # Customizable brand styling variables model
│   │   │   ├── User.ts                  # User accounts and user levels model
│   │   │   └── income.model.ts          # Cash entries database fields model
│   │   ├── routes/                      # API endpoint mappings
│   │   │   ├── auth.routes.ts           # Authentication route collection
│   │   │   ├── category.routes.ts       # Category management route collection
│   │   │   ├── cost.routes.ts           # Cost tracking endpoints collection
│   │   │   ├── dashboard.routes.ts      # Analytical graphs aggregate collection
│   │   │   ├── income.routes.ts         # Cash entries endpoints collection
│   │   │   ├── project.routes.ts        # Project metrics endpoints collection
│   │   │   ├── settings.routes.ts       # Branding colors mapping collection
│   │   │   ├── upload.routes.ts         # Media assets linking collection
│   │   │   └── v1/
│   │   │       └── index.ts             # Central REST API registry (points to /api/v1)
│   │   ├── schemas/                     # Payload checks using Zod library
│   │   │   ├── auth.schema.ts           # Client credentials format tests
│   │   │   ├── category.schema.ts       # Ledger category labels layout checks
│   │   │   ├── cost.schema.ts           # Expense values layout checks
│   │   │   └── project.schema.ts        # New project data format tests
│   │   ├── scripts/                     # Local data migration runners
│   │   ├── services/                    # Shared operational services
│   │   │   └── EmailService.ts          # Nodemailer transaction emails setting
│   │   ├── utils/                       # Shared utility helpers
│   │   │   ├── encryption.ts            # RSA file signers & key conversion helpers
│   │   │   ├── logger.ts                # Winston log format helper functions
│   │   │   └── responseHandler.ts       # Unified API response builders
│   │   └── server.ts                    # Primary backend runtime entrance file
│   ├── scripts/                         # Command automation shell helpers
│   │   └── migrateCategories.js         # Script to normalize database category ids
│   ├── seed.ts                          # DB initial seeding routines
│   ├── tsconfig.json                    # Backend compiler specifications
│   ├── package.json                     # Main dependencies & runtime scripts
│   └── .env                             # Port rules, databases, and JWT/RSA keypairs
│
├── frontend/                            # Vite & React Single Page Application
│   ├── src/                             # Front-end UI code base
│   │   ├── components/                  # Global reusable UI modules
│   │   │   ├── ThemeProvider.tsx        # Responsive light/dark system toggle wrapper
│   │   │   ├── common/                  # General shared page controls
│   │   │   ├── layout/                  # Page frame visual layout wrappers
│   │   │   │   ├── AppLayout.tsx        # General shell framework container
│   │   │   │   └── Sidebar.tsx          # Dynamic slider drawer sidebar panel
│   │   │   └── ui/                      # Styled Radix & custom primitive parts
│   │   │       ├── DateRangePicker.tsx  # Dynamic multi-day range selector
│   │   │       ├── InfiniteSelect.tsx   # Scrolling database dynamic chooser
│   │   │       ├── LoadingSpinner.tsx   # Modern rotating loading indicator
│   │   │       ├── NoDataPlaceholder.tsx# Blank status container indicator
│   │   │       ├── alert-dialog.tsx     # Modern interactive alert popups
│   │   │       ├── avatar.tsx           # User initials badge generator
│   │   │       ├── badge.tsx            # Inline data highlight tags
│   │   │       ├── button.tsx           # Standard button with loading/disabled states
│   │   │       ├── card.tsx             # Rounded dashboard panel wrapper
│   │   │       ├── command.tsx          # Search lists selector overlay
│   │   │       ├── dialog.tsx           # Standard popup modal window
│   │   │       ├── input.tsx            # Form textbox with custom borders
│   │   │       ├── label.tsx            # Floating textbox title element
│   │   │       ├── pagination.tsx       # Record page controllers
│   │   │       ├── popover.tsx          # Hover tooltip popover box
│   │   │       ├── select.tsx           # Dropdown list custom box
│   │   │       ├── separator.tsx        # Visual styling border line
│   │   │       ├── sheet.tsx            # Slide-out sidebar sheet drawers
│   │   │       └── tabs.tsx             # Responsive dashboard tabs controller
│   │   ├── hooks/                       # Tannstack query caching functions
│   │   ├── lib/                         # Front-end configuration clients
│   │   │   ├── api.ts                   # Axios client containing interceptors & tokens
│   │   │   ├── auth.ts                  # Secure RSA decryption & session tools
│   │   │   ├── toast.tsx                # Sonner toast visual notify wrappers
│   │   │   └── utils.ts                 # Dynamic tailwind classes assembler
│   │   ├── pages/                       # Multi-view pages structures
│   │   │   ├── auth/                    # Client login, PIN entry & verify views
│   │   │   ├── categories/              # Category CRUD boards & tables
│   │   │   ├── costs/                   # Cost tracking registers & modals
│   │   │   ├── dashboard/               # Main analytical graphs, metrics & charts
│   │   │   ├── entries/                 # Shared financial ledger view list
│   │   │   ├── income/                  # Income entries & tracking boards
│   │   │   ├── projects/                # Projects list, details & invoices
│   │   │   └── settings/                # Corporate customization, themes & logos
│   │   ├── App.tsx                      # App router config & layout registry
│   │   ├── index.css                    # Tailwind rulesets & animations CSS
│   │   └── main.tsx                     # React client bootstrap mount script
│   ├── public/                          # Static assets and browser icon resources
│   ├── .env                             # Frontend environment setup variables
│   ├── .gitignore                       # Standard version control exclusions
│   ├── eslint.config.js                 # Frontend static analysis & linting parameters
│   ├── index.html                       # HTML page mount skeleton for Vite compile
│   ├── postcss.config.js                # Style preprocessor runner configurations
│   ├── tailwind.config.js               # Theme style token matching files
│   ├── tsconfig.json                    # Bundler TypeScript compilation specs
│   ├── tsconfig.app.json                # React App TypeScript parameters
│   ├── tsconfig.node.json               # Node process TypeScript context
│   ├── vite.config.ts                   # Vite bundler, proxy & packaging rules
│   └── package.json                     # Frontend dependencies & run scripts
│
├── docs/                                # Documentation and guides
│   └── developer-guide.html             # Premium interactive developer handbook
│
├── postman_collection.json              # Complete Postman REST API endpoints package
└── README.md                            # Comprehensive user manual

Project Root Directory & File Dictionary

The system is highly organized and decoupled. Below is an exhaustive breakdown explaining the purpose, tech stack, and significance of every single entry in the project root directory:

Primary Modules & Usage

1. Dashboard & Analytical Processing

Consolidates database financial inputs. It processes the net cash margins by fetching accumulated cost categories, and returns visual distributions via the Recharts components. It automatically monitors and warns developers about outstanding invoice limits.

2. Secure Ledger Entry (Income & Expense)

All items in the project's financial history are saved as sub-entries associated with a specific project id. The database models track category relationships to maintain accurate, query-optimized summaries.

3. Report Generation System

Using ExcelJS on the server-side, the project offers custom report exports. The system parses document database properties, converts them into standard tabular formats, and streams binary Excel spreadsheets directly to the client browser.

User Guide

Introduction

Welcome to the Project Finance Management Software User Guide.

This solution is designed to help businesses efficiently manage:

• Project receivables
• Project expenses and costs
• Income and revenue tracking
• Profitability analysis
• Outstanding payments
• Financial reporting
• Cost & income categorization
• Company branding and visual settings

The platform provides a centralized dashboard to monitor the financial health of all projects while allowing users to manage individual project records with ease.

This documentation explains every module and feature in detail so that first-time users can easily understand and use the software.

1. Getting Started

Main Navigation Menu

The left sidebar contains the primary navigation:

2. Dashboard Module

The Dashboard provides a complete financial overview of all projects.

It helps users quickly understand:

• Total receivables
• Outstanding amounts
• Total received income
• Total project count
• Total expenditure
• Project distribution
• Cost distribution
• Outstanding analysis

Dashboard KPIs

2.1 All Projects Receivable

Displays the total expected revenue across all projects.

Example:
₹16,20,000 Total Portfolio Budget

Purpose:

• Understand total business receivables
• Track overall portfolio value

2.2 Total Outstanding

Shows pending payments that are yet to be received.

Example:
₹4,50,000 Pending Payments

Purpose:

• Monitor unpaid amounts
• Track collection performance

2.3 Total Received

Displays all recorded income received across projects.

Example:
₹11,70,000 Actual Cash Inflow

Purpose:

• Understand completed collections
• Track cash flow performance

2.4 Total Projects

Displays the total number of active projects.

Example:
7 Active Engagements

Purpose:

• Monitor active business operations
• Understand project volume

2.5 Total Expenditure

Displays the total expenses recorded.

Example:
₹45,000 Total Expenditure

Purpose:

• Monitor operational spending
• Analyze expense utilization

Dashboard Analytics

2.6 Project Distribution Chart

This pie chart shows the revenue distribution across projects.

Purpose:

• Identify high-value projects
• Compare project contribution percentages

2.7 Outstanding by Project

Displays pending receivables project-wise.

Purpose:

• Identify projects with high outstanding balances
• Improve payment follow-ups

2.8 Cost Distribution Chart

Displays expense distribution across categories.

Purpose:

• Understand where money is being spent
• Track major expense categories

Creating a New Project from Dashboard

Steps

3. Project Management Module

The Projects module provides detailed financial management for:

• All projects combined
• Individual project performance
• Profitability analysis
• Cost analysis
• Reporting

Projects Overview Screen

This screen displays portfolio-wide KPIs.

Available KPIs

Analytics in Projects Module

Profit vs Cost Chart

Displays profitability compared with project costs.

Purpose:

• Analyze business margins
• Compare revenue against spending

Category Cost Breakdown

Shows how expenses are distributed across categories.

Purpose:

• Identify high-spending categories
• Improve cost planning

Top 5 Profitable Projects

Displays projects generating the highest profit.

Purpose:

• Identify best-performing projects
• Compare profitability rankings

4. Individual Project Overview

When a user opens a specific project, they can view detailed financial insights for that project.

Available Information

Project Header

The top section displays:

• Project Name
• Project Status
• Payment Status

Example:

• Zenith Manufacturing Portal
• In-Progress
• Fully Paid

Project-Level KPIs

Total Receivable

Displays total expected project revenue.

Total Received

Displays income already recorded.

Total Outstanding

Displays remaining unpaid amount.

Total Expenses

Displays total project cost.

Net Profitability

Displays overall project profit margin.

Purpose:

• Analyze project success
• Track financial performance

Project Charts

Profit vs Cost Distribution

Visual representation of:

• Cost
• Profit percentage

Category Cost Split

Displays expense distribution by categories.

Project Actions

The following action buttons are available:

5. Adding Expense Entries

The Costs module is used to record all project expenses.

Examples

• Employee salary
• Server hosting
• Software subscription
• Marketing cost
• Vendor payments
• Equipment purchases

How to Add a Cost Entry

6. Adding Income Entries

The Income module is used to record project revenue or received payments.

Examples

• Milestone payments
• Client advance payments
• Final settlements
• Monthly retainers

How to Add an Income Entry

7. Category Management

The Categories module allows users to create reusable categories for:

• Costs
• Income

Categories help maintain consistency in reporting and analytics.

Category Dashboard

This screen displays:

Creating a New Category

Existing Categories Table

The table displays:

Search & Filter Features

Users can:

• Search categories
• Filter by status
• Sort categories

Purpose:

• Quickly manage large category lists

8. Downloading Project Reports

Users can export reports for analysis or sharing.

How to Download Reports

9. Settings Module

The Settings module allows administrators to customize:

• Company identity
• Branding
• UI color system
• Theme appearance

Branding Section

Features Available

Supported Formats

• SVG
• PNG
• JPG

How to Update Branding

10. Visual Theme System

The platform allows users to customize interface colors.

Available Customization Areas

Chart Palette

Users can configure colors used in:

• Pie charts
• Graphs
• Distribution analytics

Reset Theme

Click:

Reset Defaults

to restore the default color palette.

11. Recommended Workflow

For best results, follow this sequence:

12. Understanding Key Financial Terms

13. Best Practices

Keep Categories Consistent

Avoid creating duplicate categories.

Example

Use “Employee Salary” consistently instead of:

• Salary
• Staff Salary
• Employee Cost

Update Entries Regularly

Add costs and income immediately after transactions.

Benefits

• Accurate analytics
• Reliable reporting
• Real-time profitability

Monitor Outstanding Payments

Review the dashboard regularly to:

• Follow up pending invoices
• Improve cash flow
• Reduce payment delays

Export Reports Frequently

Maintain periodic backups and reporting records.

Recommended

• Weekly reports
• Monthly reports
• Project completion reports