# averylor/biasbreaker architecture

> Architecture diagram of the GitHub repository averylor/biasbreaker, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/averylor/biasbreaker
- Repository: https://github.com/averylor/biasbreaker

## Overview

##### Main Components
- Frontend: Represent the Next.js application that includes various sub-pages (dashboard, login, register, compare, results, and a three.js demo) along with its rich UI components.
- FastAPI Backend Server: Show the central backend service that handles RESTful endpoints, processing queries, and acting as a gateway to the database.
- API Modules: Although these modules (e.g., natural_language_understanding.py, dei_focus.py, neutrality_check.py) reside in separate directories, in the new design, they are conceptual clients that make HTTP calls to the FastAPI backend. You may choose to cluster them together under an “API Modules” label.
- Database: The Supabase database which contains the “news” table and handles the news article data storage and search functionalities.
- Supporting & Test Components: Optionally, illustrate the testing frameworks (for both API modules and backend endpoints) and web scraping tools if needed. They can be shown as auxiliary components used during development and integration testing.

##### Relationships and Interactions
- Optional flows for error handling: Indicate fallback mechanisms where mock data might be used when the database is unavailable.

##### Architectural Patterns and Design Principles
- Clean Separation of Concerns: Emphasize that the API modules are decoupled from direct database access, ensuring the single source of truth is the FastAPI backend.
- RESTful Architecture: Annotate connections with HTTP-based communication to underline adherence to REST principles.
- Scalability: Optionally, note that the FastAPI backend can be scaled independently, as it acts as the central gateway for all external communications.
- Modular Testing: Highlight that testing components (located in separate directories for both the backend and API modules) validate functionality at every level from individual unit tests to integration tests.

##### Relevant Technologies & Frameworks
- Frontend: Next.js, TypeScript, React components, TailwindCSS, and supporting libraries.
- Backend: Python FastAPI, with scripts for running tests and initializing the database connection.
- Database: Supabase (PostgreSQL-based).
- Other: Additional modules using NLP and DEI functionalities (powered perhaps by external APIs or built-in logic).

##### Specific Elements
- Clear labels for every component:
- “Next.js Frontend” with its sub-pages and UI components.
- “FastAPI Backend” including endpoints for authentication, search, news synthesis, etc.
- “API Modules” as clients (optional cluster) that now use HTTP to connect to the backend.
- “Supabase Database” with an annotation for the “news” table and its key columns.
- Any additional tools (like webScrapingTools) if relevant.
- Presentation layer (e.g., blue/rounded rectangles for frontend components).

This structured, detailed approach will not only help in visualizing current module interactions but will also be useful for communicating changes (like the shift from direct database access to a centralized API backend) and for future scalability or debugging tasks.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Presentation Layer
    subgraph "Presentation Layer"
        FE["Next.js Frontend"]:::frontend
    end

    %% Application Layer
    subgraph "Application Layer"
        BE["FastAPI Backend"]:::backend
        subgraph "API Modules"
            NLP["Natural_Language_Understanding Module"]:::backend
            DEI["DEI_Focus Module"]:::backend
            NAG["Neutral_Article_Generator Module"]:::backend
            NC["Neutrality_Check Module"]:::backend
            UC["User_Customization Module"]:::backend
        end
    end

    %% Data Layer
    subgraph "Data Layer"
        DB["Supabase Database (news table)"]:::data
    end

    %% Testing Components
    subgraph "Testing Components"
        TestAPI["API Modules Testing"]:::test
        TestBE["Backend Testing"]:::test
    end

    %% Connections - Presentation to Application
    FE -->|"HTTP_REST_API"| BE

    %% Connections - API Modules to Backend
    NLP -->|"HTTP_Call"| BE
    DEI -->|"HTTP_Call"| BE
    NAG -->|"HTTP_Call"| BE
    NC -->|"HTTP_Call"| BE
    UC -->|"HTTP_Call"| BE

    %% Connection - Backend to Data Layer
    BE -->|"Database_Query"| DB

    %% Connections - Testing Components
    TestAPI -->|"Tests"| NLP
    TestAPI -->|"Tests"| DEI
    TestAPI -->|"Tests"| NAG
    TestAPI -->|"Tests"| NC
    TestAPI -->|"Tests"| UC
    TestBE -->|"Tests"| BE

    %% Click Events
    click FE "https://github.com/averylor/biasbreaker/tree/main/frontend/"
    click BE "https://github.com/averylor/biasbreaker/blob/main/backend/main.py"
    click NLP "https://github.com/averylor/biasbreaker/blob/main/backend/api/natural_language_understanding.py"
    click DEI "https://github.com/averylor/biasbreaker/blob/main/backend/api/dei_focus.py"
    click NAG "https://github.com/averylor/biasbreaker/blob/main/backend/api/neutral_article_generator.py"
    click NC "https://github.com/averylor/biasbreaker/blob/main/backend/api/neutrality_check.py"
    click UC "https://github.com/averylor/biasbreaker/blob/main/backend/api/user_customization.py"
    click DB "https://github.com/averylor/biasbreaker/blob/main/backend/api/database.py"
    click TestAPI "https://github.com/averylor/biasbreaker/tree/main/backend/api/testing/"
    click TestBE "https://github.com/averylor/biasbreaker/tree/main/backend/test/"

    %% Styles
    classDef frontend fill:#ADD8E6,stroke:#333,stroke-width:2px;
    classDef backend fill:#90EE90,stroke:#333,stroke-width:2px;
    classDef data fill:#D3D3D3,stroke:#333,stroke-width:2px;
    classDef test fill:#FFD700,stroke:#333,stroke-width:2px;
```
