LedgerFlow — Backend API

REST API for LedgerFlow, a full-stack financial management application developed as the Final Project for the Ironhack Web Development Bootcamp.

The API handles authentication, users, clients, invoices, expenses, categories, and dashboard financial data.

---

🌐 Links

Live API

https://ledgerflow-api-lfry.onrender.com/

Frontend Application

https://ledger-flow-frontend-three.vercel.app/

GitHub Repositories

• Backend: https://github.com/AndreRibeiro24/LedgerFlow-Backend
• Frontend: https://github.com/AndreRibeiro24/LedgerFlow-Frontend

---

🛠️ Tech Stack

• Node.js — Server-side JavaScript runtime
• Express 5 — REST API framework
• MongoDB — NoSQL database
• MongoDB Atlas — Cloud database hosting
• Mongoose — MongoDB object modelling and schema validation
• JSON Web Token (JWT) — Authentication
• bcrypt — Password hashing
• CORS — Cross-origin request handling
• Morgan — HTTP request logging
• dotenv — Environment variable management
• Nodemon — Development server auto-reloading

---

🏗️ Architecture

React Frontend
      │
      │ HTTPS / Axios
      ▼
┌─────────────────────┐
│   Express REST API  │
│                     │
│  Routes             │
│     ↓               │
│  Middleware         │
│     ↓               │
│  Controllers        │
│     ↓               │
│  Mongoose Models    │
└──────────┬──────────┘
           │
           ▼
     MongoDB Atlas

The backend follows a modular structure separating:

• Routes
• Controllers
• Models
• Middleware
• Database configuration

---

📁 Project Structure

server/
├── config/
│   └── db.js
│
├── controllers/
│   ├── auth.controller.js
│   ├── category.controller.js
│   ├── client.controller.js
│   ├── dashboard.controller.js
│   ├── expense.controller.js
│   └── invoice.controller.js
│
├── middleware/
│   ├── auth.middleware.js
│   └── error.middleware.js
│
├── models/
│   ├── Category.model.js
│   ├── Client.model.js
│   ├── Expense.model.js
│   ├── Invoice.model.js
│   └── User.model.js
│
├── routes/
│   ├── auth.routes.js
│   ├── categories.routes.js
│   ├── clients.routes.js
│   ├── dashboard.routes.js
│   ├── expenses.routes.js
│   └── invoices.routes.js
│
├── app.js
└── server.js

---

🔐 Authentication

LedgerFlow uses JWT authentication.

Registration

When registering:

1. Required fields are validated.
2. The API checks whether the user already exists.
3. Password strength requirements are validated.
4. The password is hashed using bcrypt.
5. The user is stored in MongoDB.

Login

When logging in:

1. The API searches for the user by email.
2. The account status is verified.
3. bcrypt compares the submitted password with the stored hash.
4. A JWT is generated after successful authentication.

Protected endpoints expect:

Authorization: Bearer <token>

The authentication middleware verifies the token and makes the authenticated user's information available to subsequent controllers.

---

🛡️ Security & Validation

The API implements several security and validation mechanisms:

• Password hashing with bcrypt
• Password complexity requirements
• JWT-based authentication
• Protected API routes
• Resource ownership validation
• Required field validation
• Mongoose schema validation
• Duplicate user detection
• Duplicate client tax number detection
• Duplicate invoice number detection
• Duplicate category detection
• Client ownership validation for invoices
• Inactive user account validation
• Centralized Express error handling
• Environment variables for sensitive configuration

Sensitive values such as database credentials and JWT secrets are never committed to source control.

---

👤 Resource Ownership

Application resources are associated with the authenticated user through an owner field.

For example:

const owner = req.user.userId;

Database operations include the owner when searching for resources:

const client = await Client.findOne({
  _id: id,
  owner: req.user.userId
});

This prevents authenticated users from reading, updating, or deleting resources belonging to another account.

---

📡 API Endpoints

Base production URL:

https://ledgerflow-api-lfry.onrender.com/api

Authentication

Method	Endpoint	Description	Auth
POST	/auth/register	Register a new user	No
POST	/auth/login	Authenticate user	No

Clients

Method	Endpoint	Description	Auth
GET	/clients	Get all user clients	Yes
GET	/clients/:id	Get client by ID	Yes
POST	/clients	Create client	Yes
PUT	/clients/:id	Update client	Yes
DELETE	/clients/:id	Delete client	Yes

Invoices

Method	Endpoint	Description	Auth
GET	/invoices	Get all user invoices	Yes
GET	/invoices/:id	Get invoice by ID	Yes
POST	/invoices	Create invoice	Yes
PUT	/invoices/:id	Update invoice	Yes
DELETE	/invoices/:id	Delete invoice	Yes

Expenses

Method	Endpoint	Description	Auth
GET	/expenses	Get all user expenses	Yes
GET	/expenses/:id	Get expense by ID	Yes
POST	/expenses	Create expense	Yes
PUT	/expenses/:id	Update expense	Yes
DELETE	/expenses/:id	Delete expense	Yes

Categories

Method	Endpoint	Description	Auth
GET	/categories	Get all user categories	Yes
GET	/categories/:id	Get category by ID	Yes
POST	/categories	Create category	Yes
PUT	/categories/:id	Update category	Yes
DELETE	/categories/:id	Delete category	Yes

Dashboard

The dashboard API provides aggregated data for the authenticated user, including:

• Financial summary
• Invoice status distribution
• Recent invoices
• Recent expenses
• Expenses grouped by category

---

🗃️ Data Models

User

Stores account and authentication information.

Main fields:

name
email
password
role
isActive

Client

Stores customer information and is associated with its owner.

Main fields:

name
email
phone
taxNumber
address
notes
owner
isActive

Invoice

Stores invoice information and its associated client.

Main information includes:

invoiceNumber
client
owner
issueDate
dueDate
currency
items
subtotal
taxTotal
total
billingDetails
issuerDetails
notes
status

Expense

Stores business expenses.

Main information includes:

description
amount
date
category
paymentMethod
notes
owner

Category

Stores custom expense categories associated with the authenticated user.

Main fields:

name
owner

---

📊 Dashboard Aggregation

The API uses MongoDB/Mongoose queries and aggregation pipelines to generate dashboard information.

Examples include:

• Counting clients, invoices, and expenses
• Calculating paid invoice revenue
• Calculating total expenses
• Calculating profit
• Grouping invoices by status
• Grouping expenses by category
• Retrieving the five most recent invoices
• Retrieving the five most recent expenses

---

💱 Currency Handling

Invoices support:

EUR
USD
GBP

Currency is stored at invoice level.

The current dashboard aggregates numerical invoice totals without performing foreign exchange conversion.

Automatic currency conversion and configurable base currencies are planned as future improvements.

---

🚀 Running Locally

Requirements

Make sure you have:

• Node.js
• npm
• MongoDB Community Server or access to MongoDB Atlas

1. Clone the repository

git clone https://github.com/AndreRibeiro24/LedgerFlow-Backend.git
cd LedgerFlow-Backend

2. Install dependencies

npm install

3. Environment Variables

Create a .env file in the project root:

PORT=5005
MONGO_URL=your_mongodb_connection_string
JWT_SECRET=your_jwt_secret

Never commit the .env file to source control.

4. Start development server

npm run dev

The API will be available locally at:

http://localhost:5005

Production

npm start

---

📜 Scripts

npm run dev

Starts the API using Nodemon for development.

npm start

Starts the API using Node.js.

---

☁️ Deployment

The backend is deployed using Render.

Production architecture:

Vercel Frontend
       │
       ▼
Render Express API
       │
       ▼
MongoDB Atlas

Production secrets such as MONGO_URL and JWT_SECRET are configured using Render environment variables.

MongoDB Atlas Network Access is configured to allow connections from the deployed backend.

---

🔮 Future Improvements

Possible future backend improvements include:

• Automatic foreign exchange conversion
• Configurable base currency
• Advanced financial reporting
• PDF invoice generation
• Notification and reminder system
• User/business settings
• Administrative functionality
• Advanced filtering and pagination
• Additional analytics endpoints
• Automated testing

---

👨‍💻 Author

André Ribeiro

Final Project — Ironhack Web Development Bootcamp

Project Links

Backend Repository:
https://github.com/AndreRibeiro24/LedgerFlow-Backend

Frontend Repository:
https://github.com/AndreRibeiro24/LedgerFlow-Frontend

Live Application:
https://ledger-flow-frontend-three.vercel.app/

Backend API:
https://ledgerflow-api-lfry.onrender.com/