How faysal1000/fake-news-annotation-tool works
1. Repository split
- The repo contains two deployable systems: the main desktop annotator in annotator/ and a separate Telegram bot service in bot-server/.
- The desktop app is the primary product; the bot is an auxiliary distribution/input pipeline for routing news items to annotators.
2. Desktop app boundary
- annotator/main.py is the launch entry point; it adds src/ to the path and starts the GUI.
- annotator/build.py packages the app into standalone binaries with PyInstaller for Windows, macOS, and Linux.
- This makes the desktop client self-contained and usable without Python knowledge.
3. Core runtime architecture
- The app is organized as a local, stateful GUI application with a UI layer, mode layer, data layer, media layer, and analysis utilities.
- ui/main_window.py acts as the orchestrator and wires the other modules together.
- bootstrap.py, app_paths.py, and constants.py provide startup checks, filesystem resolution, and shared configuration.
4. Primary user workflows
- The app centers on three modes: Annotate, Review, and Re-label.
- modes/mode_controller.py switches between these views.
- annotate_mode.py handles record creation and validation, review_mode.py handles browsing/edit/delete of saved records, and relabel_mode.py supports blind relabeling for agreement testing.
5. Local data persistence
- All annotation data is stored locally, not in a central database.
- data/csv_manager.py manages the dataset CSV schema, reads/writes records, and handles migrations.
- data/config_manager.py stores per-user local settings.
- data/stats_engine.py computes local counts and summary metrics used by the UI and dashboard.
6. Media handling
- Media is stored alongside the dataset, typically in local images/ and videos/ folders next to the executable.
- media/media_manager.py is responsible for attaching, previewing, saving, and scaling media assets.
- Dataset rows keep relative media paths so the CSV remains portable when folders are moved together.
7. Duplicate detection and auditing
- Duplicate checking is a distinct subsystem under duplicates/duplicate_engine.py.
- It appears to run background auditing and supports an inline duplicate badge plus a dedicated comparison popup in ui/duplicate_popup.py.
- The app also maintains a persistent non_duplicates.json list so manually reviewed pairs are not repeatedly flagged.
8. Analysis and dataset operations
- analysis/aggregator.py combines datasets from multiple annotators and generates derived samples, especially for inter-rater reliability workflows.
- analysis/kappa.py implements Cohen/Fleiss Kappa calculations for agreement testing.
- analysis/text_similarity.py provides text normalization and similarity checks used by duplicate or overlap analysis.
- These utilities are surfaced through the UI’s scripts and stats dialogs rather than through a separate backend.
9. Statistics and dashboards
- ui/stats_popup.py provides an interactive statistics dashboard driven by the data layer.
- The dashboard is not just read-only reporting; it can dynamically recompute category distributions and multi-modal counts from the local dataset.
- This creates a tight flow from CSV data → stats engine → interactive modal.
10. Cross-cutting UI support
- ui/build_ui.py, ui/dialogs.py, ui/widgets.py, ui/filter_panel.py, and ui/scripts_popup.py provide layout, reusable controls, confirmation dialogs, filtering, and action launchers.
- shortcuts/keyboard.py binds hotkeys for fast annotation work.
- These modules support the main mode screens rather than acting as standalone features.
11. Sync and update boundaries
- sync/global_sync.py uploads lightweight team metrics to a GitHub Gist for shared progress visibility.
- updater/update_manager.py checks for releases and can trigger updates asynchronously.
- Both are optional cloud-facing concerns layered on top of an otherwise offline-first desktop app.
12. Telegram bot service
- bot-server/telegram_bot.py is a separate runtime for receiving or polling Telegram messages and routing news links to annotators.
- bot-server/api/index.py and vercel.json indicate a serverless webhook deployment option on Vercel, while setup_webhook.py configures Telegram webhook registration.
- This service feeds assignment/input into the annotation workflow but does not share the desktop app’s local storage directly.
13. Build and release pipeline
- .github/workflows/build.yml automates multi-platform builds and release creation from version tags.
- The repo also uses a pre-push git hook to prevent mismatched version tags.
- The overall delivery model is: source repo → CI build → standalone desktop release binaries + optional bot deployment.
Main entry points: main_window.py Main window · mode_controller.py Mode switch · duplicate_engine.py Duplicate engine · scripts_popup.py Scripts panel
Components 25
Desktop annotator
Local GUI application and its supporting subsystems.
- Launcher · Starts the desktop app and adds the source tree to the path.
annotator/main.py - Bootstrap · Performs startup checks and runtime initialization for the app.
annotator/src/bootstrap.py - Main window · Coordinates the GUI and wires the major modules together.
annotator/src/ui/main_window.py - Mode switch · Switches between annotate, review, and relabel views.
annotator/src/modes/mode_controller.py - Annotate · Creates and validates new annotation records.
annotator/src/modes/annotate_mode.py - Review · Browses, edits, and deletes saved records.
annotator/src/modes/review_mode.py - Re-label · Performs blind relabeling for agreement testing.
annotator/src/modes/relabel_mode.py - CSV store · Reads, writes, and migrates the annotation dataset schema.
annotator/src/data/csv_manager.py - Config store · Persists per-user application settings locally.
annotator/src/data/config_manager.py - Stats engine · Computes local counts and summary metrics for the UI.
annotator/src/data/stats_engine.py - Media manager · Attaches, previews, saves, and scales local media assets.
annotator/src/media/media_manager.py - Duplicate engine · Detects potential duplicates and supports manual review flows.
annotator/src/duplicates/duplicate_engine.py - Similarity · Normalizes text and computes similarity signals for overlap checks.
annotator/src/analysis/text_similarity.py - Aggregator · Combines datasets and derives samples for reliability workflows.
annotator/src/analysis/aggregator.py - Kappa · Implements Cohen and Fleiss kappa calculations.
annotator/src/analysis/kappa.py - Stats dashboard · Interactive statistics dashboard driven by local dataset metrics.
annotator/src/ui/stats_popup.py - Scripts panel · Launches analysis and dataset operations from the GUI.
annotator/src/ui/scripts_popup.py - Hotkeys · Keyboard bindings for fast annotation work.
annotator/src/shortcuts/keyboard.py - Global sync · Uploads lightweight team progress metrics to a shared gist.
annotator/src/sync/global_sync.py - Updater · Checks for releases and can trigger asynchronous updates.
annotator/src/updater/update_manager.py
Telegram bot
Separate service for receiving or routing news items into the annotation workflow.
- Telegram bot · Receives or polls Telegram messages and routes news links.
bot-server/telegram_bot.py - Webhook API · Webhook entrypoint for the bot deployment.
bot-server/api/index.py - Webhook setup · Registers Telegram webhook configuration for the bot.
bot-server/setup_webhook.py
Connections 26
- Launcher → Bootstrap: initializes · Launcher hands off to startup checks and runtime setup.
- Launcher → Main window: starts · Launches the primary GUI shell.
- Packager → Launcher: packages · Bundles the desktop entrypoint into standalone binaries.
- Main window → Mode switch: routes · Main window delegates view switching to the mode controller.
- Mode switch → Annotate: opens · Activates annotation workflow.
- Mode switch → Review: opens · Activates review workflow.
- Mode switch → Re-label: opens · Activates blind relabel workflow.
- Annotate → CSV store: writes · Saves new records into the local dataset CSV.
- Review → CSV store: reads/writes · Loads and updates persisted records.
- Re-label → CSV store: reads · Uses saved records as the source for blind relabeling.
- Main window → Media manager: uses · Coordinates media attachment and preview flows.
- Main window → Stats engine: queries · Requests counts and summary metrics for the dashboard.
- Stats engine → Stats dashboard: feeds · Provides computed metrics to the interactive statistics UI.
- Main window → Duplicate engine: checks · Surfaces duplicate auditing in the main workflow.
- Duplicate engine → Similarity: uses · Relies on normalization and similarity scoring.
- Duplicate engine → Main window: flags · Pushes duplicate status back into the UI.
- Main window → Scripts panel: launches · Exposes analysis and dataset operations through action dialogs.
- Scripts panel → Aggregator: runs · Invokes dataset aggregation and derived sample generation.
- Scripts panel → Kappa: runs · Invokes agreement calculations for reliability workflows.
- Main window → Hotkeys: binds · Registers hotkeys for fast annotation actions.
- Main window → Global sync: reports · Sends lightweight progress metrics when enabled.
- Main window → Updater: checks · Integrates optional release checking and update flow.
- Telegram bot → Webhook API: deploys · Supports webhook-based serverless deployment.
- Webhook setup → Telegram bot: configures · Registers Telegram webhook settings for the bot service.
- CI build → Packager: builds · CI drives desktop packaging and release artifact creation.
- CI build → Telegram bot: deploys · Supports the bot service release/deployment path.