How novocainex/vortex-hackathon26 works
1. What this repo is
- Forensica AI is a two-tier forensic document analysis system: a static JavaScript frontend and a FastAPI backend that runs a modular tamper-detection pipeline.
- The backend is the core of the system; the frontend is a thin dashboard for authentication, upload, analysis status, results, history, and reports.
2. User-facing boundary
- The frontend lives in hackathon/frontend/ and is built from plain HTML/CSS/JS, not a framework.
- js/router.js, app.js, and state.js suggest a single-page dashboard experience with feature modules for auth, upload, batch analysis, results, report viewing, and history.
3. API and backend entrypoint
- The backend is a Python/FastAPI application under hackathon/backend/, started from main.py.
- Routes are split by concern: auth, upload, analysis, and report, which keeps request handling separated from the forensic pipeline itself.
4. Core orchestration layer
- services/pipeline_service.py appears to be the central orchestrator that coordinates file intake, analysis stages, and result assembly.
- upload_service.py likely handles document ingestion and registration, while report_service.py turns analyzed data into the final verification output.
5. Forensic analysis pipeline
- The pipeline is modular and stage-based: preprocessing, OCR, pixel/anomaly detection, layout analysis, font detection, metadata forensics, and risk scoring.
- These stages are implemented in dedicated services such as file_preprocessor.py, ocr_service.py, pixel_analyzer.py, layout_analysis.py, font_detector.py, metadata_forensics.py, and risk_scoring.py.
6. Explainability and evidence generation
- anomaly_detection.py, layout_checker.py, and analysis_registry.py indicate the system does not just return a score; it also tracks which signals contributed to suspicion.
- result_store.py and models/analysis_result.py likely persist the structured evidence needed for explainable outputs and reports.
7. Document lifecycle and persistence
- The presence of document_registry.py, document_store.py, job_store.py, and result_store.py shows a separation between document metadata, async/job state, and final analysis outputs.
- The uploads/ tree under backend/ shows local storage mode, with per-user folders and per-document encrypted files, matching the README’s local/cloud split.
8. Authentication and external services
- Firebase integration is explicit: firebase_config.py and the auth route point to Firebase Authentication, Firestore, and Storage in cloud mode.
- This makes Firebase the main external boundary for user identity and persistent storage, while local mode uses filesystem-backed storage for development/demo.
9. Data model boundary
- models/document.py and models/analysis_result.py define the primary domain objects moving through the system: uploaded documents and their forensic outcomes.
- These models likely bridge the API layer, analysis pipeline, and persistence stores.
10. Utility and preprocessing support
- utils/ contains lower-level helpers for encryption, file handling, image operations, security, and result aggregation.
- These utilities support the services layer rather than exposing business logic directly, which keeps the analysis stages focused and reusable.
11. Operational packaging
- The backend includes a Dockerfile, requirements.txt, and Render config, so it is intended to run as a containerized Python service.
- Startup scripts such as start.bat, install_startup.bat, and run_hidden.vbs suggest the project was packaged for hackathon/demo deployment on Windows as well as cloud hosting.
12. Testing and demo material
- tests/smoke_test.py and tests/test_suite.py provide validation around basic backend behavior.
- The demo/ and docs/ directories contain presentation artifacts rather than runtime components, so they are not part of the operational architecture.
13. Mental model for an architecture diagram
- Draw the frontend as a static client that calls the FastAPI backend.
- Draw the backend as three layers: API routes on top, orchestration/persistence services in the middle, and the forensic analysis modules at the bottom.
- Show Firebase as the external cloud boundary for auth/storage, with local encrypted uploads as the fallback storage path in development mode.
Main entry points: __init__.py API Routes · pipeline_service.py Pipeline Orchestrator · document_store.py Persistence · app.js App Core
Components 21
Frontend
Static dashboard client in plain HTML/CSS/JS
- Dashboard · Thin browser UI for auth, upload, analysis, results, history, and reports
hackathon/frontend/index.html - App Core · Initializes the dashboard experience and shared state
hackathon/frontend/js/app.js - Router · Switches between dashboard views and modules
hackathon/frontend/js/router.js - API Client · Browser-side integration layer for backend requests
hackathon/frontend/js/api.js - Feature Modules · Auth, upload, batch analysis, results, history, and report screens
Backend
FastAPI service and forensic pipeline
- FastAPI App · Backend application entrypoint and server wiring
hackathon/backend/main.py - API Routes · Request boundary split by auth, upload, analysis, and report
hackathon/backend/routes/__init__.py - Auth API · Authentication boundary and Firebase-backed identity flow
hackathon/backend/routes/auth.py - Upload API · Handles document intake and registration
hackathon/backend/routes/upload.py - Analysis API · Starts and queries forensic analysis jobs
hackathon/backend/routes/analysis.py - Report API · Serves verification and report output
hackathon/backend/routes/report.py - Pipeline Orchestrator · Coordinates intake, stage execution, and result assembly
hackathon/backend/services/pipeline_service.py - Upload Service · Registers uploads and prepares documents for processing
hackathon/backend/services/upload_service.py - Report Service · Turns analysis output into final verification reports
hackathon/backend/services/report_service.py - Forensic Stages · Preprocessing, OCR, pixel, layout, font, metadata, and risk scoring
hackathon/backend/services/preprocessing.py - Evidence Layer · Tracks anomalies, layout checks, and analysis registry for explainability
hackathon/backend/services/anomaly_detection.py - Persistence · Stores document metadata, jobs, and analysis results
hackathon/backend/services/document_store.py - Domain Models · Primary document and analysis result objects
hackathon/backend/models/document.py - Utilities · Encryption, file handling, image ops, security, and aggregation helpers
hackathon/backend/utils/__init__.py
External
Cloud and runtime boundaries
- Firebase · External auth and cloud storage boundary
hackathon/backend/firebase_config.py - Local Uploads · Encrypted per-user document storage used in local mode
hackathon/backend/uploads/local_demo_user
Connections 24
- Dashboard → App Core: bootstraps · Dashboard loads the app runtime
- App Core → Router: navigates · App delegates screen changes to the router
- App Core → Feature Modules: hosts · App wires feature modules into the shell
- Feature Modules → API Client: calls · UI features invoke backend requests through the API client
- Router → Feature Modules: switches · Router selects active dashboard module
- API Client → API Routes: requests · Client API talks to backend HTTP routes
- FastAPI App → API Routes: mounts · FastAPI app registers route modules
- API Routes → Auth API: exposes · Authentication endpoints
- API Routes → Upload API: exposes · Upload endpoints
- API Routes → Analysis API: exposes · Analysis endpoints
- API Routes → Report API: exposes · Report endpoints
- Upload API → Upload Service: delegates · Upload route hands work to ingestion service
- Analysis API → Pipeline Orchestrator: delegates · Analysis route triggers the orchestrator
- Report API → Report Service: delegates · Report route builds final output through service layer
- Upload Service → Persistence: registers · Uploaded documents are persisted in metadata and storage layers
- Pipeline Orchestrator → Forensic Stages: runs · Orchestrator executes forensic stages
- Pipeline Orchestrator → Evidence Layer: collects · Pipeline records signals and anomalies for explainability
- Pipeline Orchestrator → Persistence: writes · Pipeline updates job, document, and result stores
- Persistence → Domain Models: persists · Stores structured domain records
- Evidence Layer → Domain Models: annotates · Evidence is attached to analysis result objects
- Forensic Stages → Utilities: uses · Stages rely on shared preprocessing and helper utilities
- Upload Service → Local Uploads: stores · Local mode writes encrypted files to filesystem storage
- Auth API → Firebase: authenticates · Cloud mode uses Firebase identity and storage services
- Persistence → Firebase: syncs · Cloud persistence can be backed by Firebase services