GB Schemas (@dynamatix/gb-schemas)

A comprehensive TypeScript/Mongoose schema library for Gatehouse Bank backend systems, providing data models for mortgage applications, applicants, properties, and related financial services.

🏗️ Project Overview

This package contains all the schemas and data models used in Gatehouse Bank's backend systems. It provides a robust foundation for managing mortgage applications, applicant data, property information, and various financial commitments through well-defined Mongoose schemas with TypeScript support.

📦 Package Information

• Name: @dynamatix/gb-schemas
• Version: 1.3.305
• Description: All the schemas for Gatehouse Bank back-end
• Type: ES Module
• Main: dist/index.js
• Types: dist/index.d.ts

🚀 Features

• TypeScript Support: Full TypeScript definitions and type safety
• Mongoose Integration: Built on Mongoose ODM for MongoDB
• Audit Middleware: Built-in audit trail support via @dynamatix/cat-shared
• Workflow Middleware: Automatic workflow triggering based on database events
• Custom Value Objects: Specialized types for financial data (Pound, Account Number, Sort Code)
• Modular Architecture: Organized into logical domains (applications, applicants, properties, etc.)
• Migration Scripts: Comprehensive data migration and maintenance tools

📁 Project Structure

gb-schemas-node/
├── applicants/           # Applicant-related schemas and models
├── applications/         # Application management schemas
├── properties/          # Property and security schemas
├── product-catalogues/  # Product definition schemas
├── shared/              # Common/shared schemas and utilities
├── users/               # User management schemas
├── underwriter/         # Underwriting-related schemas
├── value-objects/       # Custom Mongoose types
├── api-models/          # API-specific model definitions
├── entities/            # Entity layer schemas
├── examples/            # Usage examples
├── scripts/             # Migration and utility scripts
└── schema-docs/         # Schema documentation generation

🔧 Installation

npm install @dynamatix/gb-schemas

📚 Usage

Basic Import

import { 
  ApplicantModel, 
  ApplicationModel, 
  PropertyModel 
} from '@dynamatix/gb-schemas';

Modular Imports

// Import specific modules
import { ApplicantModel } from '@dynamatix/gb-schemas/applicants';
import { ApplicationModel } from '@dynamatix/gb-schemas/applications';
import { PropertyModel } from '@dynamatix/gb-schemas/properties';

Example: Adding Applicant Income

import mongoose from 'mongoose';
import ApplicantIncomeModel from '@dynamatix/gb-schemas/applicants/applicant-income.model';

// Connect to MongoDB
await mongoose.connect(MONGODB_URI);

// Create new applicant income record
const newIncome = new ApplicantIncomeModel({
  applicantId: 'your-applicant-id',
  selfEmployedIncomeRationale: 'Based on last 2 years of accounts'
});

const savedIncome = await newIncome.save();

Workflow Middleware

The library includes a powerful workflow middleware system that automatically triggers workflows based on database events.

import { initializeWorkflowMiddlewareWithCheck } from '@dynamatix/gb-schemas';

// Initialize workflow middleware for ALL schemas with one call
initializeWorkflowMiddlewareWithCheck();

Environment Variables:

• WORKFLOW_API_KEY: Required API key for workflow service authentication
• WORKFLOW_API_URL: Optional workflow API URL (default: https://your-workflow-api.com/api/v1/workflows/execute)
• WORKFLOW_TIMEOUT: Optional timeout in milliseconds (default: 30000)
• WORKFLOW_RETRY_ATTEMPTS: Optional retry attempts (default: 3)
• WORKFLOW_RETRY_DELAY: Optional retry delay in milliseconds (default: 1000)

For detailed documentation, see Workflow Middleware Guide.

🏛️ Core Schemas

Applicants

• Applicant: Core applicant information (personal details, addresses, employment status)
• Applicant Income: Various income types (employment, self-employed, pension, property)
• Applicant Commitments: Financial commitments (mortgages, loans, credit cards)
• Applicant Credit Data: Credit profile and credit report information
• Applicant Expenditure: Spending patterns and financial outgoings

Applications

• Application: Main application record with workflow and status tracking
• Application Mortgage: Mortgage-specific application details
• Application Credit Profile: Credit assessment information
• Application Legal: Legal documentation and compliance data
• Application Notes: Application-related notes and comments

Properties

• Property: Property details and characteristics
• Security: Security and collateral information

Product Catalogues

• Product Catalogue: Product definitions and variants
• Product Definitions: Detailed product specifications
• Product Variants: Product customization options

Shared Models

• Lookup: Reference data and lookup values
• System Parameters: Configuration and system settings
• Tasks: Workflow task management
• Alerts: System notification system
• Workflow Triggers: Configuration for automatic workflow execution

💰 Custom Value Objects

Pound Type

Custom Mongoose type for handling UK currency values with automatic formatting and validation.

import { Pound, formatPound } from '@dynamatix/gb-schemas/value-objects/pound';

// Automatically handles currency formatting and validation
const amount = new Pound('1,234.56'); // Returns 1234.56
const formatted = formatPound(1234.56); // Returns "£1,234.56"

Account Number & Sort Code

Specialized types for UK banking information with validation.

🔄 Migration Scripts

The project includes comprehensive migration and maintenance scripts:

Available Scripts

# Income migration
npm run migrate:applicant-income

# Self-employed ID migration
npm run migrate:self-employed-id

# Employment verification
npm run check:applicants-employment

# Application cleanup
npm run delete:applications-by-type

# API config updates
npm run update:apiconfigs-paths

Key Migration Scripts

• migrate-applicant-income.js: Migrates from old income model to new separated models
• migrate-self-employed-id.js: Updates self-employed applicant references
• check-applicants-without-employment.js: Validates employment data integrity
• update-apiconfigs-paths.js: Updates API configuration paths

🛠️ Development

Prerequisites

• Node.js (v18+)
• TypeScript 5.3+
• MongoDB 6.14+

Setup

# Install dependencies
npm install

# Build the project
npm run build

# Generate documentation
npm run generate-docs

# Run examples
npm run example:income

Build Configuration

The project uses TypeScript with ES2020 modules and generates declaration files:

{
  "target": "ES2020",
  "module": "ES2020",
  "outDir": "./dist",
  "declaration": true,
  "declarationMap": true
}

📖 API Reference

Main Exports

// Core models
export * from './applications';
export * from './applicants';
export * from './properties';
export * from './shared';
export * from './users';
export * from './product-catalogues';
export * from './underwriter';

Model Relationships

• Applications → Applicants (one-to-many)
• Applications → Properties (one-to-many)
• Applications → Product (many-to-one)
• Applicants → Income Models (one-to-many)
• Applicants → Commitment Models (one-to-many)

🔒 Security & Compliance

• GDPR Support: Built-in GDPR consent tracking
• Audit Trail: Comprehensive audit logging via middleware
• Data Validation: Strict schema validation and type checking
• Access Control: User permission and role-based access models

🧪 Testing & Examples

Example Scripts

• add-applicant-income.ts: Demonstrates creating applicant income records
• Migration Scripts: Show real-world data migration patterns

Running Examples

# Run income example
npm run example:income

# Generate documentation
npm run generate-docs

📝 Documentation

• Schema Documentation: Auto-generated via npm run generate-docs
• Migration Guides: Detailed README files in the scripts/ directory
• API Models: Type-safe API model definitions

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Ensure TypeScript compilation passes
5. Submit a pull request

📄 License

ISC License - see package.json for details

🆘 Support

• Issues: GitHub Issues
• Repository: GitHub Repository
• Author: Dynamatix

🔄 Version History

• Current: 1.3.305
• Dependencies:
  • @dynamatix/cat-shared: ^0.0.119
  • mongoose: ^8.9.5
  • mongodb: ^6.14.2

This package provides the foundational data layer for Gatehouse Bank's mortgage and financial services backend systems.