docs/ARCHITECTURE.md

BeyondBinary System Architecture & Technical Specifications

BeyondBinary is an Explainable Artificial Intelligence (XAI) media credibility and political bias analysis platform designed to mitigate polarization and automate forensic claim verification.

---

1. Directory Structure

BeyondBinary/
├── backend/                     # Python Backend Services & Neural Inference
│   ├── __init__.py              # Package initialization & path resolution
│   ├── main.py                  # FastAPI routers, endpoints, CORS & SPA serving
│   ├── verifier.py              # RoBERTa-large-MNLI premise entailment engine
│   ├── claim_extractor.py       # ClaimBuster DeBERTa-v2 check-worthiness extraction
│   ├── bias_detector.py         # Political Bias BERT + AllSides 101-outlet grounding
│   ├── scorer.py                # Calibrated multi-factor credibility scoring
│   ├── xai_explainer.py         # Explainable AI semantic conflict & rationale engine
│   ├── search_provider.py       # Multi-Tier search hierarchy (Brave API → Wiki → RSS)
│   ├── article_fetcher.py       # Multi-tier web article ingestion & parsing
│   ├── playwright_fetcher.py    # Playwright stealth headless browser crawler
│   ├── news_provider.py         # GNews aggregator fallback
│   └── feed_parser.py           # RSS XML feed parsing
│
├── frontend/                    # Modern React + Vite + Tailwind CSS Application
│   ├── src/
│   │   ├── components/
│   │   │   ├── Analyzer/        # ArticleReader, ClaimsList, CredibilityGauge,
│   │   │   │                    # EchoChamberArena, AnalysisProgressStepper, IngestionBar
│   │   │   ├── Trending/        # TrendingWire, ArticleCard (real-time newsfeed)
│   │   │   └── Navbar.tsx       # Broadsheet editorial masthead navigation
│   │   ├── services/api.ts      # REST API client
│   │   └── types/api.ts         # TypeScript data contracts & XAI interfaces
│   ├── dist/                    # Compiled production assets served by FastAPI
│   └── package.json
│
├── data/                        # Static indices & Knowledge Bases
│   ├── fever_index.faiss        # 384-dimensional FAISS index for semantic retrieval
│   ├── passages.pkl             # Reference knowledge passages
│   ├── allsides_ratings.json    # AllSides Media Intelligence database (101 outlets)
│
├── scripts/                     # Maintenance & Evaluation Utilities
│   └── build_index.py           # Offline FAISS index builder
│
├── docs/                        # Formal Documentation
│   └── ARCHITECTURE.md          # Technical specifications & mathematical models
│
├── main.py                      # Root entrypoint (forwards to backend.main:app)
├── requirements.txt             # Python dependencies
├── .env.example                 # Environment variables specification
└── README.md                    # Primary setup guide & walkthrough

---

2. Core Processing Pipeline

flowchart TD
    A["Raw Manuscript / URL"] --> B["Ingestion & Scraping (Playwright Stealth / Requests)"]
    B --> C["Sentence Segmentation (spaCy)"]
    C --> D["Check-Worthiness Classification (ClaimBuster DeBERTa-v2)"]
    D --> E["Multi-Tier Evidence Retrieval (FAISS + Brave Search API + Wikipedia)"]
    E --> F["Natural Language Inference (RoBERTa-large-MNLI)"]
    F --> G["Explainable AI (XAI) Diagnostics (Semantic Entity / Timeline Diff)"]
    B --> H["Political Bias & Framing Analysis (BERT + AllSides)"]
    H --> I["Loaded Language & Rhetorical Density Analysis"]
    G & F & H & I --> J["Calibrated Credibility Scoring (0 - 100)"]
    J --> K["Forensic BroadSheet Dossier & Echo-Chamber Arena"]

---

3. Mathematical Models & Formulations

3.1 Composite Credibility Score

The credibility score $S \in [0, 100]$ evaluates factual entailment weighted by model confidence and penalizes sensationalist rhetoric:

$$S=100\times \left(\frac{\sum _{i=1}^N{w}_i\cdot \mathbb{I}(v_i)}{\sum _{i=1}^N{w}_i}\right)-\lambda \cdot D_{\text{loaded}}S\; =\; 100\; \backslash times\; \backslash left(\; \backslash frac\{\backslash sum\_\{i=1\}^N\; w\_i\; \backslash cdot\; \backslash mathbb\{I\}(v\_i)\}\{\backslash sum\_\{i=1\}^N\; w\_i\}\; \backslash right)\; -\; \backslash lambda\; \backslash cdot\; D\_\{\backslash text\{loaded\}\}$$

Where:

• $v_i \in {\text{Supported}, \text{Refuted}, \text{Not Enough Info}}$ is the NLI verdict for claim $i$.
• $\mathbb{I}(\text{Supported}) = 1.0$, $\mathbb{I}(\text{Not Enough Info}) = 0.5$, $\mathbb{I}(\text{Refuted}) = 0.0$.
• $w_i = \text{confidence}_i$ from RoBERTa-large-MNLI softmax probability.
• $D_{\text{loaded}}$ is the percentage density of pejorative/sensationalist lexical markers.
• $\lambda = 0.5$ is the framing discount coefficient.

3.2 Polarization Index (Cross-Perspective Comparison)

The side-by-side Echo-Chamber Deck computes divergence between two articles reporting on the same event using Total Variation Distance (TVD) across stance distributions:

$$\text{TVD}(P_A,P_B)=\frac{1}{2}\sum _{c\in \{\text{Left},\text{Center},\text{Right}\}}\mathrm{\mid }{P}_A(c)-P_B(c)\mathrm{\mid }\backslash text\{TVD\}(P\_A,\; P\_B)\; =\; \backslash frac\{1\}\{2\}\; \backslash sum\_\{c\; \backslash in\; \backslash \{\backslash text\{Left\},\; \backslash text\{Center\},\; \backslash text\{Right\}\backslash \}\}\; |P\_A(c)\; -\; P\_B(c)|$$

$$\text{Polarization Index}=\min (100,100\times (0.70\cdot \text{TVD}+0.30\cdot \mathrm{\mid }{\text{DomainBias}}_A-{\text{DomainBias}}_B\mathrm{\mid }))\backslash text\{Polarization\; Index\}\; =\; \backslash min\backslash left(100,\; 100\; \backslash times\; \backslash left(0.70\; \backslash cdot\; \backslash text\{TVD\}\; +\; 0.30\; \backslash cdot\; |\backslash text\{DomainBias\}\_A\; -\; \backslash text\{DomainBias\}\_B|\backslash right)\backslash right)$$

---

4. Explainable AI (XAI) Diagnostics

The xai_explainer.py engine performs deterministic token-level conflict detection:

1. Temporal Consistency: Compares extracted 4-digit timeline years ($Y_{\text{claim}} \neq Y_{\text{evidence}}$).
2. Quantitative Scale: Flags order-of-magnitude discrepancies in cited numbers or percentages.
3. Polarity Inversion: Detects negation markers (denied, rejected, false) in the evidence when the claim is affirmative.
4. Attributive Framing: Identifies pejorative rhetoric introducing unsubstantiated crisis.