# viniciusgm25/score-engine architecture

> Architecture diagram of the GitHub repository viniciusgm25/score-engine, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/viniciusgm25/score-engine
- Repository: https://github.com/viniciusgm25/score-engine

## Overview

Score Engine accepts PF/PJ profiles, validates and calculates risk scores, and exposes results through REST; its evaluation endpoint can consult persisted history before recalculation. Documented Kafka consumption, model validation metrics, audit/history persistence, and the separate Decision service are also shown. Source excerpts establish the direct-score flow and, in the Score-Engine copy, the Decision dispatch; wiring details for unsampled Kafka and persistence implementations are limited to documented capabilities.

Main entry points: [`src/main/java/br/com/scoreengine/application/service/ScoreService.java`](https://github.com/viniciusgm25/score-engine/blob/master/src/main/java/br/com/scoreengine/application/service/ScoreService.java) (Score service), [`src/main/java/br/com/scoreengine/application/usecase/EvaluateUnifiedScoreUseCase.java`](https://github.com/viniciusgm25/score-engine/blob/master/src/main/java/br/com/scoreengine/application/usecase/EvaluateUnifiedScoreUseCase.java) (Unified evaluation), [`Score-Engine/src/main/java/br/com/scoreengine/interfaces/rest/controller/ScorePipelineController.java`](https://github.com/viniciusgm25/score-engine/blob/master/Score-Engine/src/main/java/br/com/scoreengine/interfaces/rest/controller/ScorePipelineController.java) (Decision dispatch), [`src/main/java/br/com/scoreengine/infrastructure/web/ScoreController.java`](https://github.com/viniciusgm25/score-engine/blob/master/src/main/java/br/com/scoreengine/infrastructure/web/ScoreController.java) (Direct score REST)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Interfaces"]
  node_score_api["Direct score REST"]
  node_pipeline_api["Evaluation REST"]
  node_validation_api["Metrics REST"]
  node_decision_controller["Decision dispatch"]
end

subgraph group_app["Application"]
  node_score_service["Score service<br/>[ScoreService.java]"]
  node_evaluate["Unified evaluation"]
  node_validation["Model metrics"]
  node_audit_port["Audit port"]
  node_decision_port["Decision port"]
end

subgraph group_domain["Scoring domain"]
  node_validator["Profile validator"]
  node_calculators["PF/PJ strategies"]
  node_profiles["Customer profiles"]
  node_score_result["Score result<br/>[ScoreResult.java]"]
end

subgraph group_infra["Infrastructure"]
  node_kafka["Score Kafka consumer"]
  node_audit_store[("Audit persistence")]
  node_evaluation_store[("Evaluation history")]
  node_decision_client["Decision HTTP client"]
end

subgraph group_decision["Decision service"]
  node_decision_service["Decision HTTP service<br/>[server.js]"]
  node_decision_rules["Decision audit rules<br/>[auditoria.js]"]
end

node_client(("API caller"))
node_decision_user(("Decision API user"))
node_metrics_user(("Model evaluator"))

node_client -->|"submits profile"| node_score_api
node_score_api -->|"calls scoring"| node_score_service
node_score_service -->|"validates profile"| node_validator
node_score_service -->|"selects strategy"| node_calculators
node_score_service -->|"saves audit"| node_audit_port
node_score_service -->|"returns score"| node_score_result
node_pipeline_api -->|"calls evaluation"| node_evaluate
node_evaluate -->|"checks history"| node_evaluation_store
node_evaluate -->|"recalculates"| node_score_service
node_evaluate -->|"returns output"| node_score_result
node_audit_port -->|"writes audit"| node_audit_store
node_metrics_user -->|"submits metrics"| node_validation_api
node_validation_api -->|"calculates metrics"| node_validation
node_kafka -.->|"dispatches requests"| node_evaluate
node_decision_user -->|"submits profile"| node_decision_controller
node_decision_controller -->|"calls evaluation"| node_evaluate
node_decision_controller -->|"dispatches score"| node_decision_port
node_decision_port -->|"sends result"| node_decision_client
node_decision_client -->|"posts score"| node_decision_service
node_decision_service -->|"processes result"| node_decision_rules

click node_score_api "https://github.com/viniciusgm25/score-engine/blob/master/src/main/java/br/com/scoreengine/infrastructure/web/ScoreController.java"
click node_pipeline_api "https://github.com/viniciusgm25/score-engine/blob/master/src/main/java/br/com/scoreengine/interfaces/rest/controller/ScorePipelineController.java"
click node_validation_api "https://github.com/viniciusgm25/score-engine/blob/master/src/main/java/br/com/scoreengine/infrastructure/web/ScoreValidationController.java"
click node_kafka "https://github.com/viniciusgm25/score-engine/blob/master/src/main/java/br/com/scoreengine/infrastructure/messaging/ScoreKafkaConsumer.java"
click node_score_service "https://github.com/viniciusgm25/score-engine/blob/master/src/main/java/br/com/scoreengine/application/service/ScoreService.java"
click node_evaluate "https://github.com/viniciusgm25/score-engine/blob/master/src/main/java/br/com/scoreengine/application/usecase/EvaluateUnifiedScoreUseCase.java"
click node_validation "https://github.com/viniciusgm25/score-engine/blob/master/src/main/java/br/com/scoreengine/application/service/ScoreValidationService.java"
click node_validator "https://github.com/viniciusgm25/score-engine/blob/master/src/main/java/br/com/scoreengine/domain/validator/PerfilValidator.java"
click node_calculators "https://github.com/viniciusgm25/score-engine/blob/master/src/main/java/br/com/scoreengine/domain/calculator/ScoreCalculatorStrategy.java"
click node_profiles "https://github.com/viniciusgm25/score-engine/tree/master/src/main/java/br/com/scoreengine/domain/model"
click node_score_result "https://github.com/viniciusgm25/score-engine/blob/master/src/main/java/br/com/scoreengine/domain/model/common/ScoreResult.java"
click node_audit_port "https://github.com/viniciusgm25/score-engine/blob/master/src/main/java/br/com/scoreengine/application/port/out/ScoreAuditPort.java"
click node_audit_store "https://github.com/viniciusgm25/score-engine/blob/master/src/main/java/br/com/scoreengine/infrastructure/persistence/adapter/ScoreAuditRepositoryAdapter.java"
click node_evaluation_store "https://github.com/viniciusgm25/score-engine/blob/master/src/main/java/br/com/scoreengine/infrastructure/persistence/adapter/ScoreEvaluationRepositoryAdapter.java"
click node_decision_controller "https://github.com/viniciusgm25/score-engine/blob/master/Score-Engine/src/main/java/br/com/scoreengine/interfaces/rest/controller/ScorePipelineController.java"
click node_decision_port "https://github.com/viniciusgm25/score-engine/blob/master/Score-Engine/src/main/java/br/com/scoreengine/application/port/out/ScoreToDecisionPort.java"
click node_decision_client "https://github.com/viniciusgm25/score-engine/blob/master/Score-Engine/src/main/java/br/com/scoreengine/infrastructure/integration/DecisionHttpClient.java"
click node_decision_service "https://github.com/viniciusgm25/score-engine/blob/master/Decisao/server.js"
click node_decision_rules "https://github.com/viniciusgm25/score-engine/blob/master/Decisao/src/auditoria.js"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_score_api,node_pipeline_api,node_validation_api,node_decision_controller,node_decision_user toneBlue
class node_score_service,node_evaluate,node_validation,node_audit_port,node_decision_port toneAmber
class node_validator,node_calculators,node_profiles,node_score_result,node_client toneMint
class node_kafka,node_audit_store,node_evaluation_store,node_decision_client toneRose
class node_decision_service,node_decision_rules,node_metrics_user toneIndigo
```

## Components

### Interfaces

- [Direct score REST](https://github.com/viniciusgm25/score-engine/blob/master/src/main/java/br/com/scoreengine/infrastructure/web/ScoreController.java): `src/main/java/br/com/scoreengine/infrastructure/web/ScoreController.java`
- [Evaluation REST](https://github.com/viniciusgm25/score-engine/blob/master/src/main/java/br/com/scoreengine/interfaces/rest/controller/ScorePipelineController.java): `src/main/java/br/com/scoreengine/interfaces/rest/controller/ScorePipelineController.java`
- [Metrics REST](https://github.com/viniciusgm25/score-engine/blob/master/src/main/java/br/com/scoreengine/infrastructure/web/ScoreValidationController.java): `src/main/java/br/com/scoreengine/infrastructure/web/ScoreValidationController.java`
- [Decision dispatch](https://github.com/viniciusgm25/score-engine/blob/master/Score-Engine/src/main/java/br/com/scoreengine/interfaces/rest/controller/ScorePipelineController.java): `Score-Engine/src/main/java/br/com/scoreengine/interfaces/rest/controller/ScorePipelineController.java`

### Application

- [Score service](https://github.com/viniciusgm25/score-engine/blob/master/src/main/java/br/com/scoreengine/application/service/ScoreService.java): `src/main/java/br/com/scoreengine/application/service/ScoreService.java`
- [Unified evaluation](https://github.com/viniciusgm25/score-engine/blob/master/src/main/java/br/com/scoreengine/application/usecase/EvaluateUnifiedScoreUseCase.java): `src/main/java/br/com/scoreengine/application/usecase/EvaluateUnifiedScoreUseCase.java`
- [Model metrics](https://github.com/viniciusgm25/score-engine/blob/master/src/main/java/br/com/scoreengine/application/service/ScoreValidationService.java): `src/main/java/br/com/scoreengine/application/service/ScoreValidationService.java`
- [Audit port](https://github.com/viniciusgm25/score-engine/blob/master/src/main/java/br/com/scoreengine/application/port/out/ScoreAuditPort.java): `src/main/java/br/com/scoreengine/application/port/out/ScoreAuditPort.java`
- [Decision port](https://github.com/viniciusgm25/score-engine/blob/master/Score-Engine/src/main/java/br/com/scoreengine/application/port/out/ScoreToDecisionPort.java): `Score-Engine/src/main/java/br/com/scoreengine/application/port/out/ScoreToDecisionPort.java`

### Scoring domain

- [Profile validator](https://github.com/viniciusgm25/score-engine/blob/master/src/main/java/br/com/scoreengine/domain/validator/PerfilValidator.java): `src/main/java/br/com/scoreengine/domain/validator/PerfilValidator.java`
- [PF/PJ strategies](https://github.com/viniciusgm25/score-engine/blob/master/src/main/java/br/com/scoreengine/domain/calculator/ScoreCalculatorStrategy.java): `src/main/java/br/com/scoreengine/domain/calculator/ScoreCalculatorStrategy.java`
- [Customer profiles](https://github.com/viniciusgm25/score-engine/tree/master/src/main/java/br/com/scoreengine/domain/model): `src/main/java/br/com/scoreengine/domain/model`
- [Score result](https://github.com/viniciusgm25/score-engine/blob/master/src/main/java/br/com/scoreengine/domain/model/common/ScoreResult.java): `src/main/java/br/com/scoreengine/domain/model/common/ScoreResult.java`

### Infrastructure

- [Score Kafka consumer](https://github.com/viniciusgm25/score-engine/blob/master/src/main/java/br/com/scoreengine/infrastructure/messaging/ScoreKafkaConsumer.java): `src/main/java/br/com/scoreengine/infrastructure/messaging/ScoreKafkaConsumer.java`
- [Audit persistence](https://github.com/viniciusgm25/score-engine/blob/master/src/main/java/br/com/scoreengine/infrastructure/persistence/adapter/ScoreAuditRepositoryAdapter.java): `src/main/java/br/com/scoreengine/infrastructure/persistence/adapter/ScoreAuditRepositoryAdapter.java`
- [Evaluation history](https://github.com/viniciusgm25/score-engine/blob/master/src/main/java/br/com/scoreengine/infrastructure/persistence/adapter/ScoreEvaluationRepositoryAdapter.java): `src/main/java/br/com/scoreengine/infrastructure/persistence/adapter/ScoreEvaluationRepositoryAdapter.java`
- [Decision HTTP client](https://github.com/viniciusgm25/score-engine/blob/master/Score-Engine/src/main/java/br/com/scoreengine/infrastructure/integration/DecisionHttpClient.java): `Score-Engine/src/main/java/br/com/scoreengine/infrastructure/integration/DecisionHttpClient.java`

### Decision service

- [Decision HTTP service](https://github.com/viniciusgm25/score-engine/blob/master/Decisao/server.js): `Decisao/server.js`
- [Decision audit rules](https://github.com/viniciusgm25/score-engine/blob/master/Decisao/src/auditoria.js): `Decisao/src/auditoria.js`

### Other components

- **API caller**
- **Decision API user**
- **Model evaluator**

## Connections

- API caller → Direct score REST: submits profile
- Direct score REST → Score service: calls scoring
- Score service → Profile validator: validates profile
- Score service → PF/PJ strategies: selects strategy
- Score service → Audit port: saves audit
- Score service → Score result: returns score
- Evaluation REST → Unified evaluation: calls evaluation
- Unified evaluation → Evaluation history: checks history
- Unified evaluation → Score service: recalculates
- Unified evaluation → Score result: returns output
- Audit port → Audit persistence: writes audit
- Model evaluator → Metrics REST: submits metrics
- Metrics REST → Model metrics: calculates metrics
- Score Kafka consumer → Unified evaluation: dispatches requests
- Decision API user → Decision dispatch: submits profile
- Decision dispatch → Unified evaluation: calls evaluation
- Decision dispatch → Decision port: dispatches score
- Decision port → Decision HTTP client: sends result
- Decision HTTP client → Decision HTTP service: posts score
- Decision HTTP service → Decision audit rules: processes result