@jadermme/orus-core
Version:
ORUS Core Framework - Universal framework for 6 Pillars assessment, domain-agnostic
332 lines (256 loc) • 9.15 kB
Markdown
# @orus/core
> Universal framework for 6 Pillars assessment methodology - 100% domain-agnostic
[](https://www.npmjs.com/package/@orus/core)
[](https://www.typescriptlang.org/)
[](https://opensource.org/licenses/MIT)
[](./coverage)
## Overview
**ORUS Core** is a universal framework that powers the 6 Pillars assessment methodology. It provides a stable, extensible foundation that can be used across multiple verticals (Finance, Marketing, Career, Health, Creators) without modification.
### Why ORUS Core?
- 🎯 **Single source of truth** - One framework for all assessment domains
- 🔧 **Configuration-driven** - Customize via config, not code modification
- 📊 **Data-driven decisions** - Scoring, prioritization, and validation built-in
- 🧪 **Battle-tested** - 97% test coverage, pure functions, type-safe
- 🚀 **Production-ready** - Built for 5-10 year stability
## Key Principles
- ✅ **100% domain-agnostic** - Zero references to specific domains
- ✅ **Zero framework dependencies** - Works in any JavaScript environment
- ✅ **Pure functions** - Deterministic, testable, side-effect free
- ✅ **Extensible via configuration** - Override defaults without forking
- ✅ **Type-safe** - Full TypeScript support with strict mode
- ✅ **Stable API** - Built to last 5-10 years
## Installation
```bash
npm install @orus/core
# or
pnpm add @orus/core
# or
yarn add @orus/core
```
## Quick Start
```typescript
import {
PillarId,
createOrusCore,
prioritizePillars
} from '@orus/core';
// Create configured instance
const orus = createOrusCore({
pillarLabels: {
[PillarId.PILLAR_1]: "Financial Organization",
[PillarId.PILLAR_2]: "Protection & Emergency",
// ... other labels
},
vertical: {
name: "ORUS Finance",
version: "1.0.0"
}
});
// Use the framework
const prioritization = prioritizePillars({ assessment });
console.log('Top priority:', prioritization.ranking[0]);
```
## Core Modules
### 📊 Scoring Engine
Pure functions for score manipulation and inference:
```typescript
import {
clampScore,
inferStatusFromScore,
normalizeScoreFromStatus,
adjustScoreByConfidence,
calculateScoreDelta
} from '@orus/core';
// Ensure score is in valid range (0-10)
const safe = clampScore(15); // => 10
// Infer status from numeric score
const status = inferStatusFromScore(3.5); // => "critical"
// Convert status to representative score
const score = normalizeScoreFromStatus("healthy"); // => 8.5
// Adjust for confidence level
const adjusted = adjustScoreByConfidence(7.0, "low");
// => { adjustedScore: 6.1, confidenceFactor: 0.7 }
```
### 🎯 Prioritization Engine
Intelligent pillar ranking based on multiple factors:
```typescript
import { prioritizePillars, getTopPriorities } from '@orus/core';
// Rank pillars by urgency
const result = prioritizePillars({
assessment,
strategy: 'worst_first', // or 'best_first', 'impact_first'
weights: {
status: 0.40, // Current health state
score: 0.30, // Numeric score
trend: 0.20, // Direction of change
confidence: 0.10 // Data reliability
}
});
// Get top 3 priorities
const top3 = getTopPriorities(result, 3);
```
### 🔄 Mode Logic
Handles assessment mode transitions and hybrid calculations:
```typescript
import {
resolveHybridScore,
canTransitionMode,
suggestOptimalMode
} from '@orus/core';
// Combine subjective and objective scores
const hybrid = resolveHybridScore({
subjectiveScore: 5.0,
objectiveScore: 7.5,
strategy: 'objective_priority' // 70% objective, 30% subjective
});
// Validate mode transition
const validation = canTransitionMode(
{ from: 'subjective', to: 'objective' },
0.75 // data completeness
);
// Get recommended mode based on data
const suggestion = suggestOptimalMode(0.6);
// => { mode: 'hybrid', reason: '...', confidence: 'medium' }
```
### ✅ Validation & Completeness
Data integrity and completeness tracking:
```typescript
import {
validatePillarAssessment,
validateSixPillarsAssessment,
calculatePillarCompleteness,
calculateAssessmentCompleteness,
isReadyForMode
} from '@orus/core';
// Validate pillar data
const validation = validatePillarAssessment(pillar, true); // strict mode
if (!validation.isValid) {
console.error('Errors:', validation.errors);
}
// Calculate data completeness
const completeness = calculateAssessmentCompleteness(assessment);
console.log(`Overall: ${completeness.overall * 100}%`);
console.log(`Suggestions:`, completeness.suggestions);
// Check mode readiness
if (isReadyForMode(assessment, 'objective')) {
// Sufficient data for objective mode
}
```
### ⚙️ Configuration System
Centralized, type-safe configuration:
```typescript
import { createOrusCore } from '@orus/core';
const orus = createOrusCore({
pillarLabels: {
[PillarId.PILLAR_1]: "Your Label",
// ... 6 labels required
},
statusThresholds: {
critical: [0, 4],
attention: [4.1, 7],
healthy: [7.1, 10]
},
prioritizationWeights: {
status: 0.5,
score: 0.3,
trend: 0.15,
confidence: 0.05
},
verticalSchema: {
pillars: { /* field schemas */ },
minCompletenessForObjective: 0.8,
minCompletenessForHybrid: 0.5
},
debug: false
});
// Use instance methods
const label = orus.getPillarLabel(PillarId.PILLAR_1);
const thresholds = orus.getStatusThresholds();
```
## Core Concepts
### The 6 Universal Pillars
ORUS Core defines 6 universal pillars with fixed IDs:
- `PILLAR_1` through `PILLAR_6`
**Important:** Core uses neutral labels ("Pillar 1", etc.) for debugging. Each vertical/shell **MUST** override with domain-specific labels.
### Assessment Modes
| Mode | Description | Confidence | Use Case |
|------|-------------|-----------|----------|
| `subjective` | User perception | Low | Quick assessment, no data |
| `objective` | Data-driven | High | Full data collection |
| `hybrid` | Combined approach | Medium | Partial data + user input |
### Status Classification
| Status | Score Range | Meaning |
|--------|-------------|---------|
| `critical` | 0 - 3.9 | Immediate attention required |
| `attention` | 4.0 - 6.9 | Needs improvement |
| `healthy` | 7.0 - 10.0 | Maintain and optimize |
## What's NOT in the Core
ORUS Core is intentionally minimal. It does NOT include:
- ❌ Domain-specific logic (financial calculations, marketing metrics, etc.)
- ❌ Assessment questions or questionnaires
- ❌ UI components or React hooks
- ❌ Persistence layer (databases, localStorage, APIs)
- ❌ Authentication or authorization
- ❌ Routing or navigation
- ❌ Branding, texts, or microcopy
These belong in:
- **Verticals** (e.g., `@orus/finance`) - Domain-specific logic
- **Shells** (e.g., Convexa360) - Branding and UX implementation
## Architecture
```
┌─────────────────────────┐
│ @orus/core │ Universal Framework
│ (domain-agnostic) │ • Types & Interfaces
└───────────┬─────────────┘ • Scoring & Prioritization
│ • Validation & Completeness
↓ implements • Configuration System
┌─────────────────────────┐
│ Vertical Package │ Domain Logic
│ (e.g., @orus/finance) │ • Pillar labels
└───────────┬─────────────┘ • Domain engines
│ • Field schemas
↓ customizes
┌─────────────────────────┐
│ Shell Application │ Branding & UX
│ (e.g., Convexa360) │ • UI components
└─────────────────────────┘ • User flows
• Persistence
```
## TypeScript Support
ORUS Core is written in TypeScript with strict mode enabled. All exports are fully typed:
```typescript
import type {
PillarId,
PillarStatus,
PillarMode,
PillarAssessment,
SixPillarsAssessment,
PrioritizationResult,
ValidationResult,
OrusCoreConfig
} from '@orus/core';
```
## Testing
```bash
# Run tests
pnpm test
# Run with coverage
pnpm test:coverage
# Watch mode
pnpm test:watch
```
Current coverage: **97% lines, 100% functions, 92% branches**
## Contributing
ORUS Core is designed for long-term stability. Breaking changes are avoided. Contributions should:
1. Maintain 100% domain-agnosticism
2. Use pure functions (no side effects)
3. Include comprehensive tests (≥95% coverage)
4. Follow TypeScript strict mode
5. Update documentation
## License
MIT © Jader Mendonça
---
**Status:** v1.0.0 - Production Ready
**Schema Version:** 1
**Node:** >=18.0.0
Built with ❤️ for sustainable, scalable assessment frameworks.