FCA Service Core

Overview

This document provides a comprehensive introduction to the Maikuro framework, its architecture, and primary components. Maikuro is a modular framework designed to provide a unified approach to building applications with business rules processing, database abstraction, role-based authentication, and functional programming utilities.

Table of Contents

1. Functional Programming Library 1.1. Currying Function
2. Rules Engine 2.1. XBook
3. Database System
4. Authentication & Authorization
5. Multi-Tenancy
6. Storage System
7. Shared Memory

Framework Architecture

Maikuro is structured around several core systems that work together to provide a cohesive development experience. The diagram below illustrates the high-level architecture and dependencies between these systems.

Key Components

Functional Programming Library

The functional programming library serves as the foundation of the framework, providing a rich set of utilities for function composition, data manipulation, and type handling. Functions are designed following functional programming principles, with support for currying, piping, and working with collections.

The library is designed to be composable, allowing developers to build complex operations from simple building blocks. Functions are implemented with currying support, enabling partial application and function composition. For example, the inc function is simply implemented as a partially applied add function:

module.exports = { inc: add(_, 1) };

Rules Engine

The Rules Engine allows business rules to be defined in Excel files and executed dynamically. This is a core feature of Maikuro, enabling business logic to be defined separately from application code.

The XBook class is the central component of the Rules Engine, responsible for:

1. Reading Excel files and parsing various table types
2. Building executable functions from rule definitions
3. Providing a unified interface for rule execution
4. Supporting testing and validation of rules

Each table type serves a specific purpose:

| Table Type | Purpose | |:----------------:|:---------------------------------------------------:| | RulesTable | Defines decision tables with conditions and actions | | DatatypeTable | Defines data types used in rules | | SpreadsheetTable | Implements spreadsheet-like calculations | | MethodTable | Contains JavaScript method implementations | | TestTable | Defines test cases for rules | | CheckTable | Validates rule consistency | | TransformTable | Transforms data between formats |

Database System

The Database System provides a unified interface for working with different database engines, abstracting the underlying implementation details.

The database system is built around several key abstractions:

1. DatabaseManager - Manages multiple database instances
2. Database - Represents a database for a specific tenant
3. Collection - Represents a collection of documents within a database
4. Database Engines - Implementations for different database backends (Memory, MongoDB, etc.)

This design allows applications to use a consistent API regardless of the underlying database technology. The system supports:

• CRUD operations (create, read, update, delete)
• Querying with filters, sorting, and pagination
• Collection management (indexes, dropping)
• Multi-tenancy through tenant-specific databases

Authentication & Authorization

The Authentication and Authorization system implements role-based access control through middleware functions.

The system defines several middleware functions for checking user authentication and authorization:

| Middleware | Purpose | |:-------------------:|:-----------------------------------------------------:| | ensureAuthenticated | Verifies user identity via JWT | | ensureRoles | Checks if user has required roles | | ensureAdmin | Ensures user has admin role | | ensureApp | Ensures user has app role | | ensureUser | Ensures user has user role | | ensureSuperadmin | Ensures user has superadmin role | | ensureGlobalAdmin | Ensures user has admin role with global tenant access | | ensureAdminOrApp | Ensures user has either admin or app role |

The system also supports multi-tenancy with tenant validation, allowing users to access only the tenants they are authorized for.

Storage System

The Storage System provides an abstraction over file storage operations, similar to the database abstraction but for files.

The storage system follows the same pattern as the database system, with a manager that handles multiple storage instances and engines that implement different storage backends.

Data Transformation

Maikuro includes powerful data transformation capabilities, particularly through the template and Transformers, that internally uses the Evaluator, and the TransformTable component of the Rules Engine, that allows to define Transformers inside the rules.

The transformation system allows:

1. Template processing with variable substitution
2. Expression evaluation in a context
3. Applying transformation templates to data structures
4. Piping data through transformation functions

Design Principles

Maikuro is built on several key design principles:

1. Functional Core, Imperative Shell - The framework uses functional programming principles internally while exposing more traditional imperative interfaces.

2. Abstraction Layers - Both database and storage systems use the same pattern of providing a unified interface over different backend implementations.

3. Multi-tenancy - The system is designed for multi-tenant operations at multiple levels, from authentication to database access.

4. Business Rules as Data - Rather than hardcoding business logic, the Rules Engine allows business rules to be defined in Excel and executed dynamically.

5. Shared Memory Architecture - The system implements a shared memory mechanism to coordinate between primary and worker processes.

These principles enable Maikuro to provide a flexible and extensible framework that can adapt to different application requirements while maintaining a consistent programming model.