Technical Architecture

System design, data pipeline, and implementation details.

System Overview

┌──────────────────────────────────────────────────────────────┐
│                     TellDear Architecture                       │
├──────────────────────────────────────────────────────────────┤
│                                                              │
│  ┌─────────┐    ┌──────────────┐    ┌───────────────────┐   │
│  │ Browser │───▶│  PHP Router  │───▶│  Page Controllers │   │
│  │  (UI)   │◀───│  (Clean URL) │◀───│  (index, aspect,  │   │
│  └─────────┘    └──────────────┘    │   analyze, graph) │   │
│       │                              └────────┬──────────┘   │
│       │                                       │              │
│       │         ┌─────────────────────────────┤              │
│       │         │                             │              │
│       ▼         ▼                             ▼              │
│  ┌─────────┐  ┌──────────────┐  ┌───────────────────────┐  │
│  │ JSON    │  │  Taxonomy    │  │     Graph Renderer    │  │
│  │  API    │  │   Parser     │  │  (D3.js compatible)   │  │
│  └────┬────┘  └──────┬───────┘  └───────────────────────┘  │
│       │              │                                      │
│       │              ▼                                      │
│       │  ┌───────────────────────┐                          │
│       │  │    Data Layer         │                          │
│       │  │  ┌─────────────────┐  │                          │
│       │  │  │taxonomy_init.json│ │ Nodes, Edges, Classes   │
│       │  │  ├─────────────────┤  │                          │
│       │  │  │  aid_lf.json    │  │ Verification Steps      │
│       │  │  ├─────────────────┤  │                          │
│       │  │  │  ontology.pro   │  │ Prolog Knowledge Base   │
│       │  │  └─────────────────┘  │                          │
│       │  └───────────────────────┘                          │
│       │                                                      │
│       ▼                                                      │
│  ┌──────────────────────────────────────┐                   │
│  │         Analyzer Engine              │                   │
│  │  ┌──────────┐   ┌────────────────┐   │                   │
│  │  │ Heuristic│   │ Claude API     │   │                   │
│  │  │ (client) │   │ (server-side)  │   │                   │
│  │  └──────────┘   └────────────────┘   │                   │
│  └──────────────────────────────────────┘                   │
│                                                              │
└──────────────────────────────────────────────────────────────┘

Data Model

taxonomy_init.json

The primary data store containing all graph vertices and edges. Each node has:

{
  "id": "confirmation_bias",        // unique identifier (snake_case)
  "label": "Confirmation Bias",     // human-readable name
  "class": "bias",                  // node type (determines dimension)
  "description": "The tendency...", // definition
  "fol_pattern": "..."              // optional first-order logic formula
}

aid_lf.json

The Atomic Instruction Dataset with binary verification steps for each aspect:

{
  "id": "ad_hominem",
  "name": "Ad Hominem",
  "dimension": "d1_logical_fallacies",
  "category": "informal_fallacies",
  "verification_steps": [
    {"step": 1, "question": "Does the argument attack a person...?", "type": "binary"},
    {"step": 2, "question": "Is the personal attribute relevant...?", "type": "binary"},
    {"step": 3, "question": "Does it conclude the claim is false...?", "type": "binary"}
  ],
  "fol_pattern": "∀x(Person(x) ∧ HasFlaw(x) ⇒ Invalid(Claim(x)))",
  "smt_expected": "standoff"
}

ontology.pro

A parallel representation in Prolog for symbolic reasoning. Contains the same taxonomic relationships as the JSON data but in a form suitable for logic programming queries. Can be loaded with SWI-Prolog for inference and consistency checking.

PHP Backend

`TaxonomyParser.php`

Core graph engine. Loads taxonomy_init.json + aid_lf.json into an in-memory adjacency list.

Key methods: getNode(), search(), fuzzySearch(), getChildren(), getBreadcrumb(), getRelated(), getAspectsByDimension(), getAidData()

`GraphRenderer.php`

Transforms the graph into D3.js-compatible JSON ({nodes, links}). Handles color mapping by node class and label generation.

`Analyzer.php`

Server-side text analyzer. Sends each aspect's verification steps to the LLM API as a batch, parses responses, and aggregates confidence scores. Falls back to heuristic mode when no API key is configured.

`Layout.php`

Shared UI components: HTML head with Tailwind CSS, navigation, footer, class-colored badges, and relation-type badges.

Analysis Pipeline

The 5-stage analysis pipeline processes text through increasingly deep analysis:

Dissector

Segments input text into Elementary Discourse Units (EDUs). Each sentence is classified as claim, premise, rebuttal, or statement using keyword indicators and LLM classification.

Structural Mapping

Maps rhetorical relations between EDUs: which premises support which claims, which statements rebut which arguments. Builds an argument graph.

FOL Verification

Translates natural language arguments into First-Order Logic formulas. Optionally uses Z3 SMT solver to verify formal validity. Detects structural pattern violations.

AID Scanner

Iterates all aspects against the text. For each aspect, evaluates binary verification steps. Early termination: if step 1 = "no", skip remaining steps. Confidence = proportion of "yes" answers.

X-Ray Formatter

Deduplicates overlapping detections, sorts by confidence, groups by dimension, and assigns severity rating. Produces the final analysis report.

JSON API

All data is accessible via a REST-like JSON API:

Endpoint	Method	Description
/api?action=graph	GET	D3.js graph (nodes + links)
/api?action=node&id=X	GET	Single node with relations, children, AID data
/api?action=search&q=X	GET	Fuzzy search across all aspects
/api?action=dimensions	GET	All aspects grouped by dimension
/api?action=tree	GET	Full hierarchical tree
/api?action=analyze	POST	Deep text analysis (auth required)

Technology Stack

Backend

PHP 8.x (no framework dependencies)
JSON file-based data storage
Prolog knowledge base (SWI-Prolog compatible)
cURL for LLM API integration

Frontend

Tailwind CSS (CDN)
D3.js force-directed graph
Vanilla JavaScript (no framework)
Inter font (Google Fonts)

Analysis

Multi-provider LLM API for deep analysis
Client-side heuristic fallback
Python pipeline (async, Pydantic models)
Z3 SMT solver integration point

Deployment

Apache with mod_rewrite (.htaccess)
PHP built-in server for development
No database required
Zero external PHP dependencies