Skip to content

ARCHITECTURE.md

Latest commit

 

History

History
375 lines (309 loc) · 14.4 KB

ARCHITECTURE.md

File metadata and controls

375 lines (309 loc) · 14.4 KB
Raw

CreditAI - System Architecture

?? 3-Level Overview

Level 1: Application Layers

??????????????????????????????????????????????????????????????
?                    PRESENTATION                             ?
?  ????????????????????         ????????????????????        ?
?  ?  Blazor Server   ???????????    REST API      ?        ?
?  ?  (Interactive)   ?         ?  (Stateless)     ?        ?
?  ????????????????????         ????????????????????        ?
??????????????????????????????????????????????????????????????
??????????????????????????????????????????????????????????????
?                    APPLICATION                              ?
?  Business Logic ? Interfaces ? DTOs ? Validators           ?
??????????????????????????????????????????????????????????????
??????????????????????????????????????????????????????????????
?                  INFRASTRUCTURE                             ?
?  Agents ? Scoring ? Integrations ? Pipeline ? OCR ? ML     ?
??????????????????????????????????????????????????????????????
??????????????????????????????????????????????????????????????
?                     DOMAIN                                  ?
?  Entities ? Value Objects ? Enums ? Domain Rules           ?
??????????????????????????????????????????????????????????????
??????????????????????????????????????????????????????????????
?                   DATA / EXTERNAL                           ?
?  PostgreSQL ? OpenAI-compatible LLM ? Tesseract ? External APIs ?
??????????????????????????????????????????????????????????????

Level 2: Decision Pipeline (Simplified)

INPUT ? COLLECTION ? ANALYSIS ? SCORING ? DECISION ? REVIEW ? MONITOR
   ?         ?           ?          ?          ?         ?         ?
   ?         ?           ?          ?          ?         ?         ?
   ?         ?           ?          ?          ?         ?         ?
???????? ???????? ???????? ???????? ???????? ???????? ????????
?Credit? ?  CRC ? ?Agents? ?  ML  ? ?Rules ? ?Human ? ?Early ?
?Request???11 APIs???  AI  ???Score ??? F1-F5???Review???Warn  ?
???????? ???????? ???????? ???????? ???????? ???????? ????????
   ?         ?           ?          ?          ?         ?         ?
   ?????????????????????????????????????????????????????????????????
                            ?
                            ?
                    [Immutable Audit Log]

Level 3: Main Components

???????????????????????????????????????????????????????????????
?  1. INTAKE & ORCHESTRATION                                  ?
?     ? CreditRequestIntakeService                            ?
?     ? CreditDecisionPipeline                                ?
?     ? IberianMarketPolicy (PT/ES routing)                   ?
???????????????????????????????????????????????????????????????

???????????????????????????????????????????????????????????????
?  2. DATA COLLECTION (13 sources)                            ?
?     Regulatory:  CRC (PT) | CIRBE (ES)                      ?
?     Financial:   Orbis | SABI | Moody's EDF                 ?
?     Banking:     Yapily (Open Banking)                      ?
?     Risk:        World-Check | ESG                          ?
?     Judicial:    Citius (PT)                                ?
?     Other:       IES | Creditsafe                           ?
?                                                             ?
?     Pattern: IDataProvider ? Stub/Production + Manual       ?
???????????????????????????????????????????????????????????????

???????????????????????????????????????????????????????????????
?  3. AI AGENTS (6 specialized)                               ?
?     ? BehavioralCollectionAgent (CRC/CIRBE)                 ?
?     ? FinancialCollectionAgent (Orbis/SABI/Moody's)         ?
?     ? IncomeCollectionAgent (Yapily)                        ?
?     ? LegalStructureCollectionAgent (Company data)          ?
?     ? SectorMacroCollectionAgent (Economic context)         ?
?     ? SanctionsAmlCollectionAgent (WorldCheck/ESG/Citius)   ?
?                                                             ?
?     Output: 50+ normalized features                         ?
???????????????????????????????????????????????????????????????

???????????????????????????????????????????????????????????????
?  4. ML SCORING ENGINE                                       ?
?     ? Model Registry (versioning + approval)                ?
?     ? ONNX Runtime OR baseline profiles                     ?
?     ? SHAP values (explainability)                          ?
?     ? Segment-specific models (Consumer/SME/Corporate)      ?
?                                                             ?
?     Output: Score (0-1000) + PD + Rating + SHAP             ?
???????????????????????????????????????????????????????????????

???????????????????????????????????????????????????????????????
?  5. SOLVENCY ASSESSMENT (F1-F5)                             ?
?     F1: High risk blocks (PD, incidents, sanctions)         ?
?     F2: Income/capacity checks                              ?
?     F3: Structural issues                                   ?
?     F4: Market/sector risks                                 ?
?     F5: Model governance (PSI, approval)                    ?
?                                                             ?
?     Output: APPROVE | DECLINE | REFER + justification       ?
???????????????????????????????????????????????????????????????

???????????????????????????????????????????????????????????????
?  6. NARRATIVE AI (OpenAI-compatible, on-prem)               ?
?     ? POST /v1/chat/completions (vLLM/CM)            ?
?     ? Llm:* or optional ContextMemory gateway               ?
?     ? Temperature: 0.1 (deterministic)                      ?
?     ? Grounding check (anti-hallucination)                  ?
?                                                             ?
?     Output: 500-800 word report in Portuguese               ?
???????????????????????????????????????????????????????????????

???????????????????????????????????????????????????????????????
?  7. DOCUMENT PROCESSING (OCR + AI) - NEW!                   ?
?     ? TesseractOcrService (text extraction)                 ?
?     ? LlmDocumentParsingService ? INarrativeLlmClient    ?
?     ? Support: PDF, PNG, JPG, TIFF                          ?
?     ? 11 source types (CRC, Citius, etc.)                   ?
?                                                             ?
?     Upload ? OCR ? LLM Parse ? Structured fields            ?
???????????????????????????????????????????????????????????????

???????????????????????????????????????????????????????????????
?  8. MANUAL DATA ENTRY (Robust Fallback)                     ?
?     ? ManualDataEntryService                                ?
?     ? ManualDataEntryPolicy (field definitions)             ?
?     ? Triggered on: API failure | empty | incomplete        ?
?     ? UI forms + Document upload integration                ?
?                                                             ?
?     Pipeline resumes after manual entry                     ?
???????????????????????????????????????????????????????????????

???????????????????????????????????????????????????????????????
?  9. AUDIT & COMPLIANCE                                      ?
?     ? AuditLogService (immutable hash chain)                ?
?     ? SHA-256 linking                                       ?
?     ? Every action logged                                   ?
?     ? F1-F5 compliance enforcement                          ?
?     ? Human review mandatory (MinReviewDurationMs)          ?
???????????????????????????????????????????????????????????????

???????????????????????????????????????????????????????????????
?  10. MODEL RISK MANAGEMENT (MRM)                            ?
?      ? ModelRegistryService (versioning)                    ?
?      ? ModelBacktestingService (validation)                 ?
?      ? ModelDriftMonitor (PSI continuous)                   ?
?      ? ModelPromotionGate (thresholds)                      ?
?                                                             ?
?      Metrics: AUC, Gini, Brier, PSI, PD calibration         ?
???????????????????????????????????????????????????????????????

???????????????????????????????????????????????????????????????
?  11. EARLY WARNING SYSTEM                                   ?
?      ? EarlyWarningBatchHostedService (60 min)              ?
?      ? Re-consult CRC/CIRBE for approved credits            ?
?      ? Re-score with current model                          ?
?      ? Detect: incidents, PD increase, PSI drift            ?
?      ? Alert: LOW | MEDIUM | HIGH | CRITICAL                ?
?                                                             ?
?      Continuous post-approval monitoring                    ?
???????????????????????????????????????????????????????????????

?? Architectural Principles

1. Clean Architecture (DDD)

  • Domain at the center (agnostic)
  • Application defines contracts (interfaces)
  • Infrastructure implements (external dependencies)
  • Presentation consumes Application

2. Dependency Injection

  • Every component injected via DI
  • Easy substitution (Stub ? Production)
  • Maximum testability

3. Pipeline Pattern

  • Clear unidirectional flow
  • Each phase independent
  • Rollback/retry per phase
  • Audit at each transition

4. Robust Fallback

  • API fails ? Manual data entry
  • LLM fails ? Skip narrative
  • Model unavailable ? Baseline scoring
  • Never completely blocks

5. Compliance by Design

  • F1-F5 gates mandatory
  • Immutable audit log (hash chain)
  • Human review mandatory
  • SHAP explainability always

6. 100% On-Premise

  • OpenAI-compatible local LLM (vLLM/etc.); optional ContextMemory ? not cloud SaaS LLM
  • Tesseract local (not cloud OCR)
  • PostgreSQL local
  • Zero data leakage

?? Tech Stack

Layer Technology Version
Runtime .NET 9.0
Web UI Blazor Server 9.0
API ASP.NET Core 9.0
Database PostgreSQL 9.0+
ORM Entity Framework Core 9.0
ML Runtime ML.NET + ONNX 1.21
LLM OpenAI-compatible /v1 (qwen3.5:9b) Local / CM
OCR Tesseract 5.2
Image Processing ImageSharp 3.1
PDF PdfSharpCore 1.3
Charts ApexCharts + MudBlazor Latest
Auth ASP.NET Identity + Entra 9.0
Telemetry App Insights (optional) -

?? Design Patterns Used

  1. Repository Pattern - EF Core DbContext
  2. Strategy Pattern - IDataProvider implementations
  3. Factory Pattern - Agent creation
  4. Observer Pattern - Early Warning monitoring
  5. Chain of Responsibility - Solvency rules F1-F5
  6. Builder Pattern - Feature vector construction
  7. Facade Pattern - CreditDecisionPipeline
  8. Template Method - Collection agents base
  9. Singleton - Model Registry
  10. Dependency Injection - Entire system

?? Quality Attributes

Performance

  • Average latency: 8.5s (full pipeline)
  • Throughput: 50-100 requests/hour
  • DB connection pool: 100 connections
  • Memory: ~512MB per instance

Availability

  • Target uptime: 99.9%
  • Failover: Manual data entry
  • Health checks: /health endpoint
  • Graceful degradation: Stubs in dev

Scalability

  • Horizontal: Stateless API (load balancer ready)
  • Vertical: Blazor SignalR (WebSockets)
  • Database: PostgreSQL read replicas
  • Caching: In-memory (session state)

Security

  • Auth: Identity + Entra ID
  • Authorization: Claims-based policies
  • Data at rest: PostgreSQL encryption
  • Data in transit: HTTPS/TLS 1.3
  • Audit: Immutable hash chain
  • Secrets: Azure Key Vault (production)

Maintainability

  • Tests: 95 integration tests
  • Coverage: >80% (critical pipeline)
  • Documentation: Docs/ folder
  • Code standards: EditorConfig + analyzers
  • Versioning: Semantic (Major.Minor.Patch)

Observability

  • Logs: Structured (JSON)
  • Metrics: Performance counters
  • Tracing: Correlation IDs
  • Alerts: Early Warning + Drift
  • Dashboards: MudBlazor charts

?? Deployment

Development

# Web
cd src/CreditAI.Web
dotnet run
# ? http://localhost:5188

# API
cd src/CreditAI.API
dotnet run
# ? https://localhost:7257

Production (Containers)

# Multi-stage build
FROM mcr.microsoft.com/dotnet/sdk:9.0 AS build
WORKDIR /src
COPY . .
RUN dotnet publish -c Release -o /app

FROM mcr.microsoft.com/dotnet/aspnet:9.0
RUN apt-get update && apt-get install -y \
    tesseract-ocr tesseract-ocr-por

WORKDIR /app
COPY --from=build /app .

EXPOSE 80 443
ENTRYPOINT ["dotnet", "CreditAI.API.dll"]

Database Migrations

# Create migration
dotnet ef migrations add MigrationName -p src/CreditAI.Infrastructure

# Apply to database
dotnet ef database update -p src/CreditAI.Infrastructure

?? Additional Documentation

?? Key Concepts

Collection Agent

Specialized component that collects and normalizes data from a specific area (behavioral, financial, etc.). Implements ICollectionAgent.

Feature Vector

Set of 50+ normalized numerical variables that feed the ML scoring model. Built from data collected by agents.

Solvency Rules (F1-F5)

Deterministic compliance gates that evaluate specific risks. Block automatic decisions if triggered.

Manual Data Entry

Fallback system that allows manual data entry when API integrations fail. Keeps pipeline always functional.

SHAP Values

Shapley values that explain the contribution of each feature to the final score. Critical for explainability and compliance.

Model Registry

ML model versioning and governance system. Only approved models (passing quality gates) can be used in production.

Early Warning

Post-approval monitoring system that re-evaluates approved credits periodically, detecting early deterioration.

Hash Chain Audit Log

Immutable log where each entry contains the hash of the previous entry, ensuring integrity and detecting tampering.

CreditAI v1.0 - AI-Powered Credit Analysis System
Built with .NET 9, Blazor, PostgreSQL, OpenAI-compatible LLM and ML.NET