# 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

```mermaid
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}}$$

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}\}} |P_A(c) - P_B(c)|$$

$$\text{Polarization Index} = \min\left(100, 100 \times \left(0.70 \cdot \text{TVD} + 0.30 \cdot |\text{DomainBias}_A - \text{DomainBias}_B|\right)\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.