Technical Architecture

Deep dive into the multi-provider AI orchestration, zero hallucination design patterns, and human-in-the-loop architecture.

System Architecture

A multi-provider AI orchestration system designed for zero hallucination and human oversight at every critical decision point.

View Detailed ASCII Diagram

┌─────────────────────────────────────────────────────────────────────────────────┐
│                           FINANCIAL COUNSELLING SYSTEM                           │
├─────────────────────────────────────────────────────────────────────────────────┤
│                                                                                  │
│  ┌──────────────┐     ┌──────────────────────────────────────────────────────┐  │
│  │   INTAKE     │     │                   FlowMason Engine                    │  │
│  │              │     │  ┌─────────────────────────────────────────────────┐ │  │
│  │  Email       │────▶│  │  Pipeline: fc-crisis-to-action                  │ │  │
│  │  Form        │     │  │                                                 │ │  │
│  │  Phone notes │     │  │  ┌─────────┐   ┌─────────┐   ┌─────────────┐   │ │  │
│  │  CMS webhook │     │  │  │ Claude  │   │  GPT-4  │   │  Perplexity │   │ │  │
│  └──────────────┘     │  │  │ Sonnet  │   │         │   │  sonar-pro  │   │ │  │
│                       │  │  │         │   │ Cross-  │   │             │   │ │  │
│  ┌──────────────┐     │  │  │ Empathy │   │ Valid   │   │  Research   │   │ │  │
│  │   CRISIS     │◀────│  │  │ Intake  │   │ Risk    │   │  +Citation  │   │ │  │
│  │  ESCALATION  │     │  │  │ Docs    │   │ Score   │   │  Validation │   │ │  │
│  │              │     │  │  └─────────┘   └─────────┘   └─────────────┘   │ │  │
│  │  Immediate   │     │  │                      │                         │ │  │
│  │  human       │     │  │                      ▼                         │ │  │
│  │  intervention│     │  │            ┌────────────────┐                  │ │  │
│  └──────────────┘     │  │            │   Routers &    │                  │ │  │
│                       │  │            │   Validators   │                  │ │  │
│                       │  │            └────────────────┘                  │ │  │
│                       │  │                      │                         │ │  │
│                       │  └──────────────────────│─────────────────────────┘ │  │
│                       └─────────────────────────│────────────────────────────┘  │
│                                                 │                                │
│                                                 ▼                                │
│  ┌────────────────────────────────────────────────────────────────────────────┐ │
│  │                            OUTPUT DOCUMENTS                                 │ │
│  │  ┌──────────────────┐  ┌──────────────────┐  ┌────────────────────────┐   │ │
│  │  │ Counsellor       │  │ Client Materials │  │ Case Management        │   │ │
│  │  │ Briefing         │  │ (Plain Language) │  │ System Update          │   │ │
│  │  └──────────────────┘  └──────────────────┘  └────────────────────────┘   │ │
│  └────────────────────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────────────────┘

Multi-Provider Strategy

Each AI provider is selected for its specific strengths. This isn't about redundancy—it's about using the best tool for each task.

Claude Sonnet

Anthropic

Used For

• Empathetic intake parsing
• Crisis detection
• Counsellor briefings
• Client materials (plain language)
• Action plan synthesis

Why Claude

Best-in-class for nuanced, empathetic communication. Excels at following complex guidelines (trauma-informed language, person-first framing).

Configuration

temperature: 0.3 (intake) | 0.4 (docs)

GPT-4o

OpenAI

Used For

• Risk score calculation
• Cross-validation

Why GPT-4

Cross-validation with a different model architecture reduces single-model bias. Strong at structured scoring against defined criteria.

Configuration

temperature: 0.2 (deterministic scoring)

Sonar Pro

Perplexity

Used For

• Hardship program research
• Local service discovery
• Legal protection lookup
• Creditor policy research

Why Perplexity

Real-time web search with built-in citation extraction. Essential for zero-hallucination architecture—every fact has a verifiable source.

Configuration

temperature: 0.1 (factual accuracy)

Data Flow & Schema

IN Input Schema

{
  "contact_content": "string",
  "contact_method": "email|form|phone|notes",
  "state": "VIC|NSW|QLD|SA|WA|TAS|NT|ACT",
  "suburb": "string",
  "creditors": ["string"],
  "specific_needs": ["string"]
}

OUT Output Schema

{
  "structured_intake": { "client_situation": {...}, "financial_snapshot": {...} },
  "crisis_assessment": { "crisis_detected": false, "severity": "..." },
  "risk_score": { "score": "0-10", "level": "...", "primary_concerns": [...] },
  "research": { "hardship_programs": [...], "local_services": [...] },
  "action_plan": { "immediate_actions": [...], "urgent_actions": [...] },
  "counsellor_briefing": {...},
  "client_materials": {...},
  "all_citations": [...]
}

Stage-by-Stage Data Flow

Intake Parsing

Raw text → Structured client data

input.contact_content → structured_intake

Crisis Detection

Structured intake → Crisis assessment (GATE)

If crisis_detected → STOP → Human escalation

Risk Scoring

Structured intake → Numeric risk score (0-10)

Cross-validated with different model (GPT-4)

Research (Parallel)

Client context → 4 parallel Perplexity searches

Each result MUST include citation_url

Synthesis

All inputs → Prioritized action plan + documents

Citations propagated to all outputs

Human-in-the-Loop Architecture

Human-in-the-loop design showing AI processing zone and human decision zone

Design Philosophy

AI prepares, humans deliver. Every client interaction is through a trained financial counsellor. The system never sends automated communications to clients—it prepares materials for the counsellor to review, personalize, and deliver.

Mandatory Human Intervention

!
Crisis Detection
Pipeline halts immediately. Trained staff contacted for safety assessment.
!
High Risk Score (8+)
Flagged for urgent appointment scheduling and supervisor review.
!
Unverified Citations
Items without verifiable sources flagged for manual research.

Counsellor Review Points

1
Intake Summary
Review extracted data before proceeding. Correct any misunderstandings.
2
Action Plan
Review priorities, add personal knowledge, adjust for client preferences.
3
Client Materials
Personalize before sharing. Add appointment details, personal notes.

Zero Hallucination Architecture

The Problem

Traditional LLMs can fabricate service names, phone numbers, and program details. In financial counselling, a hallucinated referral can waste client time, erode trust, or worse—lead to missed opportunities for real help.

The Solution

1. Perplexity for all factual claims - Built-in web search ensures current, verifiable information.
2. Mandatory citation URLs - Every service, program, and protection must include a source URL.
3. Validation stage - Items without citations are flagged, not silently included.
4. Explicit uncertainty - "Unable to verify" instead of fabricated details.

Citation Flow

Perplexity Search
    |
    v
Research Result (with citation_url)
    |
    v
Citation Validation Stage
    |
    +- Has URL? -> Include
    +- No URL? -> Flag for manual verification
    |
    v
All Outputs Include Citations

Security & Compliance

Data Security

• Client data processed, not stored permanently by AI providers
• API keys managed via environment variables
• No PII in logs (configurable logging levels)
• Supports self-hosted LLM deployment for sensitive environments

Audit Trail

• Complete execution trace with timestamps
• All AI reasoning captured for review
• Citation sources documented
• Human intervention points logged

Compliance Considerations

• Designed for human oversight (not autonomous advice)
• No financial advice provided directly to clients
• All recommendations reviewed by qualified counsellors
• Supports organization's existing compliance framework

Data Retention

• Configurable retention policies
• Integration with existing CMS for record keeping
• Session data can be purged after case closure
• Export capabilities for reporting requirements

Integration Points

Input Sources

Email intake (via webhook)
Web forms
Phone transcripts
CMS API

Output Destinations

Case management systems
Email (counsellor briefing)
Document generation (PDF)
Webhook notifications

Trigger Options

REST API
FlowMason Studio
CLI (batch processing)
Scheduled runs