# getsan4u/loan-origination-system architecture

> Architecture diagram of the GitHub repository getsan4u/loan-origination-system, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-23). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/getsan4u/loan-origination-system
- Repository: https://github.com/getsan4u/loan-origination-system

## Overview

##### Project type and purpose
- This is a full‑stack, open‑source Loan Origination System (“LOS”) built on Node.js/Express and the PeriodicJS container framework.
- It exposes both web UIs (EJS and React apps) and a flexible, rules‑driven Decision Engine API, plus integrated Machine Learning, Cron scheduling and third‑party integrations (e‑sign via DocuSign, AWS SageMaker, etc.).

##### File structure
- Top level:
- index.js, content/config/startup.js → application bootstrap using PeriodicJS
- app/views → legacy EJS templates; public/extensions and static → compiled React and CSS assets
- content/container → two “containers”:
– decision‑engine‑service‑container → encapsulates the Decision Engine microservice (controllers, routers, transforms, models, crons)
– periodicjs.container.default → default CMS‑style container for core pages and admin
- content/config/databases/standard/models → same domain models in Lowkie (flat‑file), Mongoose (MongoDB) and Sequelize (SQL) variants
- Cron scripts (content/container/.../crons and utilities/mlcrons) drive scheduled tasks (emails, rules updates, ML model refreshes).
- Public/extensions/periodicjs.ext.reactapp → client‑side React application built and served via the container.

##### Key insights from README
- Modular, container‑based architecture
- Open API layer for integration (Extensive routers and controllers under decision‑engine‑service‑container)
- Integrated ML workflows and charting components under utilities and resources

##### Main components
a. Client‑side UI
- Browser → EJS views (server‑rendered)
- Browser → React SPA (served from public/extensions/periodicjs.ext.reactapp)
b. API & Application Server
- PeriodicJS container loader (index.js + startup.js)
- Core container (periodicjs.container.default)
- Decision Engine container
- Controllers & Routers → Express middleware for REST endpoints (auth, decision, ml, ocr, optimization, integration, user, etc.)
c. Data Layer
- Database(s): MongoDB via Mongoose, (Postgres/MySQL/SQLite) via Sequelize, flat‑file via Lowkie
- Filesystem storage for templates, sample data, model scripts
d. Supporting Services & Integrations
- Cron scheduler → internal jobs under crons and mlcrons
- AWS SageMaker / Digifi model scripts → utilities/mlresource & files/digifi_model_scripts
- DocuSign → utilities/docusign
- Third‑party OAuth, email services, payment gateways

##### Relationships & interactions
- HTTP(S) request flow:
Client UI → Express Router → Controller → Transform → Model → Database → Transform → Controller → HTTP Response → Client UI
- Decision Engine API calls: controllers invoke rule evaluation modules and model scoring via utilities and mlresource helpers
- Cron jobs schedule: trigger ML retraining, data refresh, batch decision runs → update database
- External integration calls: DocuSign for e‑sign workflows; SageMaker for model training & inference

##### Architectural patterns & design principles
- MVC (EJS views + controllers + models)
- Modular container pattern (PeriodicJS containers act like pluggable microservices)
- Adapter pattern in Transforms (unify various data sources / ORMs)
- Cron‑driven batch processing for asynchronous workflows
- Separation of concerns: UI, API, business logic, data, external integrations

##### Final recommendations
- Every major directory as a component (app/views, content/container/decision‑engine, content/config, public/extensions)
- Do not over‑aggregate: break out Controllers, Routers, Transforms, Utilities

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client-side UI
    subgraph "Client-side UI"
        EJS["EJS Views"]:::ui
        React["React SPA"]:::ui
    end

    %% Application Server
    subgraph "Application Server"
        Boot["Bootstrap\n(index.js, startup.js)"]:::server
        subgraph "Core Container"
            CoreCt["periodicjs.container.default"]:::server
        end
        subgraph "Decision Engine Container"
            DECt["decision-engine-service-container"]:::server
            Routers["Routers"]:::server
            Controllers["Controllers"]:::server
            Transforms["Transforms"]:::server
            DECrons["Decision Engine Cron Jobs"]:::cron
            MLCrons["ML Cron Utilities"]:::cron
            MLRes["ML Resource Helpers"]:::cron
            Docusign["DocuSign Integration"]:::external
        end
    end

    %% Data Layer
    subgraph "Data Layer"
        Models["Standard Models\n(flat-file, MongoDB, SQL)"]:::data
        DEModels["DE Mongoose Models"]:::data
        FS["Filesystem Storage"]:::data
    end

    %% External Services
    subgraph "External Services"
        SageMaker["AWS SageMaker"]:::external
        Digifi["Digifi Model Scripts"]:::external
        OAuth["OAuth/Email/Payment"]:::external
    end

    %% Request/Response Flow
    EJS -->|"HTTP Request"| Boot
    React -->|"HTTP Request"| Boot
    Boot --> CoreCt
    Boot --> DECt

    CoreCt -->|"/api/*"| Routers
    Routers --> Controllers
    Controllers --> Transforms
    Transforms --> Models
    Models --> Transforms
    Transforms --> Controllers
    Controllers --> Routers
    Routers --> CoreCt
    CoreCt --> EJS
    CoreCt --> React

    %% Cron and ML Workflows
    DECrons --> MLRes
    MLCrons --> MLRes
    MLRes --> DEModels
    MLRes --> Models
    DEModels --> Models
    DECrons --> Controllers
    MLCrons --> Controllers

    %% External Integrations
    Controllers --> Docusign
    MLRes --> SageMaker
    MLRes --> Digifi
    Controllers --> OAuth

    %% Click Events
    click EJS "https://github.com/getsan4u/loan-origination-system/tree/master/app/views"
    click React "https://github.com/getsan4u/loan-origination-system/blob/master/public/extensions/periodicjs.ext.reactapp"
    click Boot "https://github.com/getsan4u/loan-origination-system/blob/master/index.js"
    click Boot "https://github.com/getsan4u/loan-origination-system/blob/master/content/config/startup.js"
    click CoreCt "https://github.com/getsan4u/loan-origination-system/blob/master/content/container/periodicjs.container.default"
    click DECt "https://github.com/getsan4u/loan-origination-system/tree/master/content/container/decision-engine-service-container"
    click Controllers "https://github.com/getsan4u/loan-origination-system/tree/master/content/container/decision-engine-service-container/controllers"
    click Routers "https://github.com/getsan4u/loan-origination-system/tree/master/content/container/decision-engine-service-container/routers"
    click Transforms "https://github.com/getsan4u/loan-origination-system/tree/master/content/container/decision-engine-service-container/transforms"
    click DECrons "https://github.com/getsan4u/loan-origination-system/tree/master/content/container/decision-engine-service-container/crons"
    click MLCrons "https://github.com/getsan4u/loan-origination-system/tree/master/content/container/decision-engine-service-container/utilities/mlcrons"
    click MLRes "https://github.com/getsan4u/loan-origination-system/tree/master/content/container/decision-engine-service-container/utilities/mlresource"
    click SageMaker "https://github.com/getsan4u/loan-origination-system/tree/master/content/container/decision-engine-service-container/utilities/mlcrons/sagemaker"
    click SageMaker "https://github.com/getsan4u/loan-origination-system/blob/master/content/container/decision-engine-service-container/utilities/mlresource/model/sagemaker_*.js"
    click Digifi "https://github.com/getsan4u/loan-origination-system/tree/master/content/files/digifi_model_scripts"
    click Docusign "https://github.com/getsan4u/loan-origination-system/tree/master/content/container/decision-engine-service-container/utilities/docusign"
    click Models "https://github.com/getsan4u/loan-origination-system/tree/master/content/config/databases/standard/models"
    click DEModels "https://github.com/getsan4u/loan-origination-system/tree/master/content/container/decision-engine-service-container/config/databases/standard/models"

    %% Styles
    classDef ui fill:#D0E8FF,stroke:#0066CC,color:#003366;
    classDef server fill:#D2F8D2,stroke:#228B22,color:#006400;
    classDef data fill:#FFE4B5,stroke:#DAA520,color:#8B4513;
    classDef external fill:#E6E6FA,stroke:#9370DB,color:#4B0082;
    classDef cron fill:#F5E1FF,stroke:#9932CC,color:#4B0082;
```
