System Architecture

Overview

The credit evaluation system relies on several external services and interdependent modules.

Full Dependency Map

Legend

:blue_square: Internal business function · :orange_square: External service (blackbox)

graph LR
    CheckBlacklist(["CheckBlacklist"]):::service
    CheckPEP(["CheckPEP"]):::service
    CheckClientBalance(["CoreBanking / CheckClientBalance"]):::service
    CheckCreditHistory(["CoreBanking / CheckCreditHistory"]):::service
    check_compliance["check_compliance"]:::func
    full_evaluation["full_evaluation"]:::func
    evaluate_credit["evaluate_credit"]:::func
    evaluate_credit_advanced["evaluate_credit_advanced"]:::func
    evaluate_credit_typed["evaluate_credit_typed"]:::func
    check_compliance -->|.call| CheckBlacklist
    check_compliance -->|.call| CheckPEP
    full_evaluation --> evaluate_credit
    full_evaluation --> check_compliance
    evaluate_credit -->|.call| CheckClientBalance
    evaluate_credit_advanced -->|.call| CheckClientBalance
    evaluate_credit_advanced -->|.call| CheckCreditHistory
    evaluate_credit_typed -->|.call| CheckCreditHistory
    evaluate_credit_typed -->|.call| CheckClientBalance

    classDef service fill:#fff3e0,stroke:#e65100,stroke-width:2px,color:#e65100
    classDef func fill:#e3f2fd,stroke:#1565c0,stroke-width:2px,color:#1565c0

Focus: Full Evaluation

The diagram below shows the call chain triggered by full_evaluation — the function that orchestrates credit and compliance:

Legend

:green_square: full_evaluation — entry point · :blue_square: Internal business function · :orange_square: External service (blackbox)

graph LR
    full_evaluation["full_evaluation"]:::entry
    CheckBlacklist(["CheckBlacklist"]):::service
    CheckClientBalance(["CoreBanking / CheckClientBalance"]):::service
    CheckPEP(["CheckPEP"]):::service
    check_compliance["check_compliance"]:::func
    evaluate_credit["evaluate_credit"]:::func
    check_compliance -->|.call| CheckBlacklist
    check_compliance -->|.call| CheckPEP
    full_evaluation --> evaluate_credit
    full_evaluation --> check_compliance
    evaluate_credit -->|.call| CheckClientBalance

    classDef service fill:#fff3e0,stroke:#e65100,stroke-width:2px,color:#e65100
    classDef func fill:#e3f2fd,stroke:#1565c0,stroke-width:2px,color:#1565c0
    classDef entry fill:#e8f5e9,stroke:#2e7d32,stroke-width:3px,color:#2e7d32

Focus: Advanced Credit Evaluation

Legend

:green_square: evaluate_credit_advanced — entry point · :blue_square: Internal business function · :orange_square: External service (blackbox)

graph LR
    evaluate_credit_advanced["evaluate_credit_advanced"]:::entry
    CheckClientBalance(["CoreBanking / CheckClientBalance"]):::service
    CheckCreditHistory(["CoreBanking / CheckCreditHistory"]):::service
    evaluate_credit_advanced -->|.call| CheckClientBalance
    evaluate_credit_advanced -->|.call| CheckCreditHistory

    classDef service fill:#fff3e0,stroke:#e65100,stroke-width:2px,color:#e65100
    classDef func fill:#e3f2fd,stroke:#1565c0,stroke-width:2px,color:#1565c0
    classDef entry fill:#e8f5e9,stroke:#2e7d32,stroke-width:3px,color:#2e7d32

Decision Tree

flowchart TD
    A[Client Request] --> B{Balance Check}
    B -->|Balance > Amount| C{Credit Score Check}
    B -->|Balance <= Amount| D[DENIED: Insufficient balance]
    C -->|Score >= Threshold| E{Incident Check}
    C -->|Score < Threshold| F[DENIED: Score too low]
    E -->|No incidents| G[APPROVED]
    E -->|Has incidents| H[DENIED: Incidents detected]

    style G fill:#c8e6c9,stroke:#2e7d32,color:#1b5e20
    style D fill:#ffcdd2,stroke:#c62828,color:#b71c1c
    style F fill:#ffcdd2,stroke:#c62828,color:#b71c1c
    style H fill:#ffcdd2,stroke:#c62828,color:#b71c1c

Sequence Diagram

@startuml
actor Client
participant "System" as sys
participant "Core Banking" as bank
participant "Credit Bureau" as credit

Client -> sys : evaluate_credit_advanced(client_id, amount)
sys -> bank : CheckClientBalance(client_id)
bank --> sys : balance = 1500.0

alt balance > amount
    sys -> credit : CheckCreditHistory(client_id)
    credit --> sys : {score: 720, incidents: 0}
    sys -> sys : evaluate score & incidents
    sys --> Client : {approved: true, ...}
else balance <= amount
    sys --> Client : {approved: false, reason: "Insufficient balance"}
end
@enduml

PlantUML Source

@startuml
actor Client
participant "System" as sys
participant "Core Banking" as bank
participant "Credit Bureau" as credit

Client -> sys : evaluate_credit_advanced(client_id, amount)
sys -> bank : CheckClientBalance(client_id)
bank --> sys : balance = 1500.0

alt balance > amount
    sys -> credit : CheckCreditHistory(client_id)
    credit --> sys : {score: 720, incidents: 0}
    sys -> sys : evaluate score & incidents
    sys --> Client : {approved: true, ...}
else balance <= amount
    sys --> Client : {approved: false, reason: "Insufficient balance"}
end
@enduml

External Services

Credit

class CheckClientBalance(ExternalService):
    """Call to the Core Banking API (Blackbox)."""

    component_name = "CoreBanking"

    def execute(self, client_id: str) -> ClientBalance:
        pass  # type: ignore[return-value]

    def mock(self, client_id: str) -> MockResponse:
        return MockResponse(data=ClientBalance(
            balance=1500.0,
            currency="USD",
            account_status="active",
        ))

    def mock_error(self, client_id: str) -> MockErrorResponse:
        return MockErrorResponse(
            error_code="CLIENT_NOT_FOUND",
            error_message="The specified client was not found.",
            http_code=404,
        )

class CheckCreditHistory(ExternalService):
    """Call to the credit history service (Blackbox)."""

    component_name = "CoreBanking"

    def execute(self, client_id: str) -> CreditHistory:
        pass  # type: ignore[return-value]

    def mock(self, client_id: str) -> MockResponse:
        return MockResponse(data=CreditHistory(score=720, incidents=0))

    def mock_error(self, client_id: str) -> MockErrorResponse:
        return MockErrorResponse(
            error_code="CREDIT_HISTORY_UNAVAILABLE",
            error_message="Credit history service is unavailable.",
            http_code=503,
        )

Compliance

class CheckBlacklist(ExternalService):
    """Call to the sanctions registry (Blackbox)."""

    def execute(self, client_id: str) -> bool:
        pass  # type: ignore[return-value]

    def mock(self, client_id: str) -> MockResponse:
        return MockResponse(data=False)  # False = not on blacklist

class CheckPEP(ExternalService):
    """Call to the Politically Exposed Persons registry (Blackbox)."""

    def execute(self, client_id: str) -> PEPStatus:
        pass  # type: ignore[return-value]

    def mock(self, client_id: str) -> MockResponse:
        return MockResponse(data=PEPStatus(is_pep=False, level=None))