How rebeccamariamebby27/authenticheck works
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: main.py App entry · text_service.py Text service · image_service.py Image service · image_model.py Image model
Components 18
Frontend
Static browser client
API
FastAPI entry and routing
- App entry · Creates the API and exposes analysis endpoints
Backend/app/main.py - Image router · HTTP boundary for image upload handling
Backend/app/routers/image_router.py
Services
Modality scoring and orchestration
- Text service · Coordinates text authenticity scoring
Backend/app/services/text_service.py - Image service · Coordinates RGB and FFT image scoring
Backend/app/services/image_service.py - Audio service · Live API placeholder for audio requests
Backend/app/services/audio_service.py - Audio predict · Standalone audio classifier helper
Backend/app/services/predict_audio.py
Models
Text and image inference components
- Text model · Hugging Face detector used for text authenticity
Backend/app/text_classifier.py - Text feats · Perplexity, burstiness, entropy and related signals
Backend/app/text_features.py - Ensemble · Combines text signals into a final label
Backend/app/ensemble.py - Image model · RGB and FFT image inference helpers
Backend/app/models/image_model.py
Offline Prep
Training and data preparation scripts
- Train image · Image model training workflow
train_image.py - Train FFT · FFT model training workflow
Backend/train_fft_model.py - FFT prep · Generates FFT magnitude images
Backend/generate_fft_images.py - Clean images · Image dataset cleanup utility
clean_images.py - Resize images · Image resizing utility
resize_images.py
Connections 20
- 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