Open Cap Stack: Financial Report API Documentation

[urbantech]

---

Open Cap Stack: Financial Report API Documentation

Date: 11-5-24
Author: Toby Morning

---

Overview

This documentation provides an in-depth look at the newly added and refactored controllers, validation logic, and API endpoints for the Financial Report API. It’s intended to help the development team understand the functionality, structure, and purpose of each module to ensure a smooth handover and facilitate ongoing collaboration.

---

1. Financial Report Data Model

The Financial Report API utilizes a MongoDB model, FinancialReport, structured as follows:

Schema Definition

Field	Type	Required	Description
ReportID	UUID	Yes	Unique identifier for each report
Type	String (Enum)	Yes	Type of report (e.g., Annual, Quarterly)
Data	JSON	Yes	JSON data for report content
TotalRevenue	Decimal	Yes	Total revenue for the reporting period
TotalExpenses	Decimal	Yes	Total expenses for the reporting period
NetIncome	Decimal	Yes	Calculated net income (TotalRevenue - TotalExpenses)
EquitySummary	Array of UUIDs	No	List of share class IDs related to report
Timestamp	Date	Yes	Date when the report was generated

Model File: models/financialReport.js

The data model is defined with Mongoose and includes validation requirements as well as data types and default values.

---

2. Controllers

The Financial Report API is structured with three primary controllers to handle various aspects of the business logic, authorization, and CRUD operations.

2.1 Business Logic Controller (financialReportLogicController.js)

This controller manages calculations and data validation related to financial reporting. It includes:

• Net Income Calculation: Automatically calculates NetIncome based on TotalRevenue and TotalExpenses.
• Reporting Period Validation: Ensures that the Timestamp field aligns with the designated Type (e.g., quarterly, annual).
• Data Validation: Validates required fields and verifies that financial figures (e.g., TotalRevenue, TotalExpenses) are non-negative.

Key Functions:

1. calculateNetIncome
   Calculates net income based on revenue and expenses.

   function calculateNetIncome(totalRevenue, totalExpenses) {
       return totalRevenue - totalExpenses;
   }

2. validateReportType
   Validates that the report type (Annual, Quarterly) is correctly formatted and consistent with the Timestamp.

   function validateReportType(reportType, timestamp) {
       // Custom logic to match report period to type
   }

3. validateFields
   Ensures all required fields are present and non-negative.

---

2.2 Authorization Controller (financialReportAuthController.js)

This controller enforces user role permissions, validates API keys, and restricts access based on report ownership.

Key Functions:

1. authorizeUserRole
   Authorizes users based on roles such as admin or report_owner.

   function authorizeUserRole(req, res, next) {
       // Check user role from JWT or API key, validate for `admin` or specific permissions
   }

2. validateAPIKey
   Checks if the API key is provided and valid.

   function validateAPIKey(req, res, next) {
       // Logic to validate the API key against stored values or tokens
   }

3. authorizeReportAccess
   Restricts access to reports based on user permissions.

---

2.3 CRUD Controller (financialReportCRUDController.js)

This controller provides standard create, read, update, and delete operations for financial reports. It includes validations for fields, checks for report existence, and error handling for database operations.

Key Functions:

1. createReport
   Creates a new financial report, ensuring unique ReportID and valid data.

   async function createReport(req, res, next) {
       try {
           const newReport = new FinancialReport(req.body);
           await newReport.save();
           res.status(201).json(newReport);
       } catch (error) {
           next(error);
       }
   }

2. getReportById
   Fetches a financial report by ReportID.

3. updateReport
   Updates an existing report, with validation checks.

4. deleteReport
   Deletes a financial report based on ReportID.

---

3. Validation Logic

Summary

All controllers use centralized validation logic to ensure that incoming data meets schema requirements. Validation is handled within each controller, but a separate file (validationHelpers.js) may also be utilized for commonly used validation functions.

Key Validation Points

• Report Type Validation: Confirms that Type is one of the accepted values (Annual, Quarterly).
• Field Presence and Format: Ensures fields like TotalRevenue, TotalExpenses, and NetIncome are provided, correctly formatted, and non-negative.
• UUID and ID Checks: Verifies ReportID uniqueness and format.

---

4. API Endpoints

Base URL: /api/v1/financialReports

Endpoint	Method	Description	Controller
/create	POST	Create a new financial report	CRUD Controller
/:reportId	GET	Get a single financial report by ID	CRUD Controller
/:reportId	PUT	Update an existing financial report	CRUD Controller
/:reportId	DELETE	Delete a financial report	CRUD Controller
/calculate-net-income	POST	Calculate net income for a report	Business Logic
/validate-report-period	POST	Validate the reporting period against Type	Business Logic
/authorize-access	POST	Authorize access to a financial report	Authorization
/validate-api-key	POST	Validate API key before granting access	Authorization

---

5. Testing and QA Coverage

Each controller is tested with comprehensive test suites covering the following:

1. Business Logic: Validates calculations, handles edge cases, and verifies period consistency.
2. Authorization: Tests access control, API key validation, and restricted access based on user roles.
3. CRUD Operations: Covers all endpoints with tests for successful operations, error handling, and edge cases (e.g., duplicate ReportID, missing fields).

Test Suite Highlights

• financialReportLogic.test.js: Validates net income calculation, handles rounding, and verifies data consistency.
• financialReportAuth.test.js: Ensures proper authorization flow based on user roles and permissions.
• financialReportCRUD.test.js: Tests for successful CRUD operations, error handling for non-existent records, and validation checks.

---

6. Setup Instructions for Development and Testing

1. Database:

   • Ensure MongoDB is running and accessible at the URI specified in .env.
   • For tests, a test database is used and dropped after each test run.

2. Running Tests:

   • Use the following command to run tests individually or as a suite:

     MONGODB_URI='mongodb://localhost:27017/opencap_test' npx jest --runInBand __tests__/financialReportLogic.test.js

3. Environment Variables:

   • Ensure MONGODB_URI and any other required environment variables are configured properly in .env.

---

7. Future Enhancements

• Error Handling Middleware: Expand error handling middleware for more granular error reporting.
• Pagination for List Endpoints: Add pagination to endpoints that list reports to improve performance.
• Role-Based Access Control (RBAC): Further refine RBAC for additional roles and permissions.

---

This documentation will support the dev team in understanding and implementing the new features within the Financial Report API.