# rebeccamariamebby27/authenticheck architecture

> Architecture diagram of the GitHub repository rebeccamariamebby27/authenticheck, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/rebeccamariamebby27/authenticheck
- Repository: https://github.com/rebeccamariamebby27/authenticheck

## Overview

1. **Overall shape**
   AuthentiCheck is a two-tier demo: a **FastAPI backend** that performs modality-specific authenticity scoring, and a **static frontend** that sends one upload at a time to the backend. The primary boundary is between the browser UI and the `/analyze` HTTP API.

2. **Request entry point**
   The backend entrypoint is `Backend/app/main.py`. It likely wires FastAPI, registers routers, and exposes the single analysis surface described in the README: `POST /analyze` with one of `text`, `image`, or `audio` in `multipart/form-data`.

3. **API routing**
   `Backend/app/routers/image_router.py` shows a router-based structure for at least the image path. The repo layout suggests the same pattern is used conceptually for modality-specific handling, even if text/audio are handled directly in services or main. This keeps HTTP concerns separate from model logic.

4. **Modality service layer**
   `Backend/app/services/` is the main business-logic layer:
   - `text_service.py` handles text scoring
   - `image_service.py` handles image scoring
   - `audio_service.py` handles audio scoring
   - `predict_audio.py` appears to be a standalone audio inference helper
   These services are the key boundary between API code and ML/model code.

5. **Text authenticity pipeline**
   The text path uses `Backend/app/text_classifier.py` plus `text_features.py`. Per the README, the main signal is a Hugging Face `roberta-base-openai-detector` transformer score, while `text_features.py` computes supplemental stylometric features such as perplexity, burstiness, and entropy. `ensemble.py` is the decision layer, though the README notes the current ensemble effectively relies on the transformer score.

6. **Image authenticity pipeline**
   Image scoring is model-based and combines two views of the same input:
   - an **RGB image model**
   - an **FFT-magnitude model**
   `Backend/app/models/image_model.py` and `Backend/app/services/image_service.py` are the main code paths here. The README states the two Keras outputs are averaged, then thresholded at 0.5 to label **AI Generated** vs **Human Generated**.

7. **Audio path**
   The live API’s audio handling is intentionally minimal: `audio_service.py` returns a **fixed placeholder** result. Separately, `Backend/app/services/predict_audio.py` can load `audio_classifier.keras` / `audio_classifier.h5` for offline prediction, but this is not wired into the exposed API flow yet. That makes audio an incomplete or stubbed subsystem compared with text and image.

8. **Model artifacts and runtime dependencies**
   The image runtime depends on external `.h5` files under `Backend/saved_models/`:
   - `image_model.h5`
   - `fft_model.h5`
   These are not committed and must be trained or supplied separately. Text models are fetched from Hugging Face on first use, so the backend has an external model-download dependency at runtime.

9. **Offline training and preprocessing**
   Several top-level scripts support model/data preparation rather than serving:
   - `train_image.py` and `Backend/train_image.py`
   - `Backend/train_fft_model.py`
   - `Backend/generate_fft_images.py`
   - `clean_images.py`
   - `resize_images.py`
   These indicate a separate offline ML workflow for image and FFT dataset preparation/training.

10. **Frontend responsibilities**
   The `frontend/` folder is a plain static client:
   - `index.html`
   - `script.js`
   - `style.css`
   It does not own any inference logic. Its job is to collect user input, call `http://127.0.0.1:8000/analyze`, and present the returned modality score/result.

11. **Data flow by modality**
   - **Text:** browser form → FastAPI → text service → transformer/features/ensemble → response
   - **Image:** browser upload → FastAPI router/service → RGB model + FFT model → averaged score → response
   - **Audio:** browser upload → FastAPI → placeholder audio service → response
   The key architectural pattern is “API orchestration, ML scoring in services, result returned as a simple classification payload.”

12. **Testing and local temp data**
   The repo includes modality-specific test files (`test_audio.py`, `test_image.py`, `test_two.py`, `test_txt.py`) and a `Backend/temp/` folder with sample audio files. This suggests local, file-based testing and experimentation rather than a production deployment pipeline.

13. **Technology boundaries that matter**
   The backend is Python/FastAPI with ML libraries behind the service layer; the text path depends on Hugging Face/PyTorch, and the image path depends on Keras/TensorFlow-style `.h5` models. The frontend is dependency-free static HTML/JS/CSS. These technology splits are the main architectural boundaries to show in a diagram.

Main entry points: [`Backend/app/main.py`](https://github.com/rebeccamariamebby27/authenticheck/blob/main/Backend/app/main.py) (App entry), [`Backend/app/services/text_service.py`](https://github.com/rebeccamariamebby27/authenticheck/blob/main/Backend/app/services/text_service.py) (Text service), [`Backend/app/services/image_service.py`](https://github.com/rebeccamariamebby27/authenticheck/blob/main/Backend/app/services/image_service.py) (Image service), [`Backend/app/models/image_model.py`](https://github.com/rebeccamariamebby27/authenticheck/blob/main/Backend/app/models/image_model.py) (Image model)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_frontend_index["UI<br/>static html<br/>[index.html]"]
  node_frontend_script["Client JS<br/>browser client<br/>[script.js]"]
  node_frontend_style["Styles<br/>css<br/>[style.css]"]
end

subgraph group_api["API"]
  node_backend_main["App entry<br/>fastapi app<br/>[main.py]"]
  node_image_router["Image router<br/>api router<br/>[image_router.py]"]
end

subgraph group_services["Services"]
  node_text_service["Text service<br/>[text_service.py]"]
  node_image_service["Image service<br/>[image_service.py]"]
  node_audio_service["Audio service<br/>[audio_service.py]"]
  node_predict_audio["Audio predict<br/>offline inference<br/>[predict_audio.py]"]
end

subgraph group_models["Models"]
  node_text_classifier["Text model<br/>transformer scorer<br/>[text_classifier.py]"]
  node_text_features["Text feats<br/>feature extractors<br/>[text_features.py]"]
  node_ensemble["Ensemble<br/>decision layer<br/>[ensemble.py]"]
  node_image_model["Image model<br/>keras model<br/>[image_model.py]"]
end

subgraph group_prep["Offline Prep"]
  node_train_image["Train image<br/>training script<br/>[train_image.py]"]
  node_train_fft["Train FFT<br/>training script<br/>[train_fft_model.py]"]
  node_fft_images["FFT prep<br/>data prep"]
  node_clean_images["Clean images<br/>preprocessing<br/>[clean_images.py]"]
  node_resize_images["Resize images<br/>preprocessing<br/>[resize_images.py]"]
end

node_frontend_index -->|"loads"| node_frontend_script
node_frontend_index -->|"styles"| node_frontend_style
node_frontend_script -->|"POST /analyze"| node_backend_main
node_backend_main -->|"routes"| node_image_router
node_backend_main -->|"delegates"| node_text_service
node_backend_main -->|"delegates"| node_image_service
node_backend_main -->|"delegates"| node_audio_service
node_image_router -->|"uses"| node_image_service
node_text_service -->|"scores"| node_text_classifier
node_text_service -->|"extracts"| node_text_features
node_text_service -->|"combines"| node_ensemble
node_ensemble -.->|"weights"| node_text_classifier
node_image_service -->|"infers"| node_image_model
node_image_service -.->|"averages"| node_image_model
node_audio_service -.->|"offline path"| node_predict_audio
node_fft_images -->|"feeds"| node_train_fft
node_clean_images -->|"prepares"| node_train_image
node_resize_images -->|"prepares"| node_train_image
node_train_image -->|"produces"| node_image_model
node_train_fft -->|"produces"| node_image_model

click node_frontend_index "https://github.com/rebeccamariamebby27/authenticheck/blob/main/frontend/index.html"
click node_frontend_script "https://github.com/rebeccamariamebby27/authenticheck/blob/main/frontend/script.js"
click node_frontend_style "https://github.com/rebeccamariamebby27/authenticheck/blob/main/frontend/style.css"
click node_backend_main "https://github.com/rebeccamariamebby27/authenticheck/blob/main/Backend/app/main.py"
click node_image_router "https://github.com/rebeccamariamebby27/authenticheck/blob/main/Backend/app/routers/image_router.py"
click node_text_service "https://github.com/rebeccamariamebby27/authenticheck/blob/main/Backend/app/services/text_service.py"
click node_image_service "https://github.com/rebeccamariamebby27/authenticheck/blob/main/Backend/app/services/image_service.py"
click node_audio_service "https://github.com/rebeccamariamebby27/authenticheck/blob/main/Backend/app/services/audio_service.py"
click node_predict_audio "https://github.com/rebeccamariamebby27/authenticheck/blob/main/Backend/app/services/predict_audio.py"
click node_text_classifier "https://github.com/rebeccamariamebby27/authenticheck/blob/main/Backend/app/text_classifier.py"
click node_text_features "https://github.com/rebeccamariamebby27/authenticheck/blob/main/Backend/app/text_features.py"
click node_ensemble "https://github.com/rebeccamariamebby27/authenticheck/blob/main/Backend/app/ensemble.py"
click node_image_model "https://github.com/rebeccamariamebby27/authenticheck/blob/main/Backend/app/models/image_model.py"
click node_train_image "https://github.com/rebeccamariamebby27/authenticheck/blob/main/train_image.py"
click node_train_fft "https://github.com/rebeccamariamebby27/authenticheck/blob/main/Backend/train_fft_model.py"
click node_fft_images "https://github.com/rebeccamariamebby27/authenticheck/blob/main/Backend/generate_fft_images.py"
click node_clean_images "https://github.com/rebeccamariamebby27/authenticheck/blob/main/clean_images.py"
click node_resize_images "https://github.com/rebeccamariamebby27/authenticheck/blob/main/resize_images.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_frontend_index,node_frontend_script,node_frontend_style toneBlue
class node_backend_main,node_image_router toneAmber
class node_text_service,node_image_service,node_audio_service,node_predict_audio toneMint
class node_text_classifier,node_text_features,node_ensemble,node_image_model toneRose
class node_train_image,node_train_fft,node_fft_images,node_clean_images,node_resize_images toneIndigo
```

## Components

### Frontend

Static browser client

- [UI](https://github.com/rebeccamariamebby27/authenticheck/blob/main/frontend/index.html): static html · Upload form and results view · `frontend/index.html`
- [Client JS](https://github.com/rebeccamariamebby27/authenticheck/blob/main/frontend/script.js): browser client · Sends one upload to the analysis API · `frontend/script.js`
- [Styles](https://github.com/rebeccamariamebby27/authenticheck/blob/main/frontend/style.css): css · Presentation only · `frontend/style.css`

### API

FastAPI entry and routing

- [App entry](https://github.com/rebeccamariamebby27/authenticheck/blob/main/Backend/app/main.py): fastapi app · Creates the API and exposes analysis endpoints · `Backend/app/main.py`
- [Image router](https://github.com/rebeccamariamebby27/authenticheck/blob/main/Backend/app/routers/image_router.py): api router · HTTP boundary for image upload handling · `Backend/app/routers/image_router.py`

### Services

Modality scoring and orchestration

- [Text service](https://github.com/rebeccamariamebby27/authenticheck/blob/main/Backend/app/services/text_service.py): service · Coordinates text authenticity scoring · `Backend/app/services/text_service.py`
- [Image service](https://github.com/rebeccamariamebby27/authenticheck/blob/main/Backend/app/services/image_service.py): service · Coordinates RGB and FFT image scoring · `Backend/app/services/image_service.py`
- [Audio service](https://github.com/rebeccamariamebby27/authenticheck/blob/main/Backend/app/services/audio_service.py): service · Live API placeholder for audio requests · `Backend/app/services/audio_service.py`
- [Audio predict](https://github.com/rebeccamariamebby27/authenticheck/blob/main/Backend/app/services/predict_audio.py): offline inference · Standalone audio classifier helper · `Backend/app/services/predict_audio.py`

### Models

Text and image inference components

- [Text model](https://github.com/rebeccamariamebby27/authenticheck/blob/main/Backend/app/text_classifier.py): transformer scorer · Hugging Face detector used for text authenticity · `Backend/app/text_classifier.py`
- [Text feats](https://github.com/rebeccamariamebby27/authenticheck/blob/main/Backend/app/text_features.py): feature extractors · Perplexity, burstiness, entropy and related signals · `Backend/app/text_features.py`
- [Ensemble](https://github.com/rebeccamariamebby27/authenticheck/blob/main/Backend/app/ensemble.py): decision layer · Combines text signals into a final label · `Backend/app/ensemble.py`
- [Image model](https://github.com/rebeccamariamebby27/authenticheck/blob/main/Backend/app/models/image_model.py): keras model · RGB and FFT image inference helpers · `Backend/app/models/image_model.py`

### Offline Prep

Training and data preparation scripts

- [Train image](https://github.com/rebeccamariamebby27/authenticheck/blob/main/train_image.py): training script · Image model training workflow · `train_image.py`
- [Train FFT](https://github.com/rebeccamariamebby27/authenticheck/blob/main/Backend/train_fft_model.py): training script · FFT model training workflow · `Backend/train_fft_model.py`
- [FFT prep](https://github.com/rebeccamariamebby27/authenticheck/blob/main/Backend/generate_fft_images.py): data prep · Generates FFT magnitude images · `Backend/generate_fft_images.py`
- [Clean images](https://github.com/rebeccamariamebby27/authenticheck/blob/main/clean_images.py): preprocessing · Image dataset cleanup utility · `clean_images.py`
- [Resize images](https://github.com/rebeccamariamebby27/authenticheck/blob/main/resize_images.py): preprocessing · Image resizing utility · `resize_images.py`

## Connections

- UI → Client JS: loads · UI is driven by client-side script
- UI → Styles: styles · Presentation layer only
- Client JS → App entry: POST /analyze · Browser sends one uploaded modality at a time
- App entry → Image router: routes · Registers modality-specific HTTP handling
- App entry → Text service: delegates · Text requests flow into service logic
- App entry → Image service: delegates · Image requests flow into service logic
- App entry → Audio service: delegates · Audio requests flow into service logic
- Image router → Image service: uses · Router passes image payloads to scoring
- Text service → Text model: scores · Transformer-based text authenticity signal
- Text service → Text feats: extracts · Supplemental stylometric features
- Text service → Ensemble: combines · Produces final text decision
- Ensemble → Text model: weights · Current decisioning relies mostly on transformer output
- Image service → Image model: infers · Runs RGB and FFT model paths
- Image service → Image model: averages · Combines model outputs into one score
- Audio service → Audio predict: offline path · Standalone audio model helper not wired to live API
- FFT prep → Train FFT: feeds · FFT image generation supports model training
- Clean images → Train image: prepares · Dataset cleanup before training
- Resize images → Train image: prepares · Resized images are used for training
- Train image → Image model: produces · Trains the RGB image artifact
- Train FFT → Image model: produces · Trains the FFT image artifact
