# novocainex/vortex-hackathon26 architecture

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

- Interactive diagram: https://gitdiagram.com/novocainex/vortex-hackathon26
- Repository: https://github.com/novocainex/vortex-hackathon26

## Overview

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: [`hackathon/backend/routes/__init__.py`](https://github.com/novocainex/vortex-hackathon26/blob/main/hackathon/backend/routes/__init__.py) (API Routes), [`hackathon/backend/services/pipeline_service.py`](https://github.com/novocainex/vortex-hackathon26/blob/main/hackathon/backend/services/pipeline_service.py) (Pipeline Orchestrator), [`hackathon/backend/services/document_store.py`](https://github.com/novocainex/vortex-hackathon26/blob/main/hackathon/backend/services/document_store.py) (Persistence), [`hackathon/frontend/js/app.js`](https://github.com/novocainex/vortex-hackathon26/blob/main/hackathon/frontend/js/app.js) (App Core)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_fe_shell["Dashboard<br/>static SPA<br/>[index.html]"]
  node_fe_app["App Core<br/>client bootstrap<br/>[app.js]"]
  node_fe_router["Router<br/>client navigation<br/>[router.js]"]
  node_fe_api["API Client<br/>HTTP client<br/>[api.js]"]
  node_fe_modules["Feature Modules<br/>ui features"]
end

subgraph group_backend["Backend"]
  node_be_main["FastAPI App<br/>service entrypoint<br/>[main.py]"]
  node_be_routes["API Routes<br/>HTTP routes<br/>[__init__.py]"]
  node_be_auth["Auth API<br/>route module<br/>[auth.py]"]
  node_be_upload["Upload API<br/>route module<br/>[upload.py]"]
  node_be_analysis["Analysis API<br/>route module<br/>[analysis.py]"]
  node_be_report["Report API<br/>route module<br/>[report.py]"]
  node_be_pipeline["Pipeline Orchestrator<br/>service coordinator"]
  node_be_upload_svc["Upload Service<br/>ingestion service<br/>[upload_service.py]"]
  node_be_report_svc["Report Service<br/>report builder<br/>[report_service.py]"]
  node_be_stages["Forensic Stages<br/>analysis modules<br/>[preprocessing.py]"]
  node_be_evidence["Evidence Layer<br/>signal tracking"]
  node_be_storage[("Persistence<br/>document/job/result stores<br/>[document_store.py]")]
  node_be_models["Domain Models<br/>data models<br/>[document.py]"]
  node_be_utils["Utilities<br/>support libs<br/>[__init__.py]"]
end

subgraph group_external["External"]
  node_firebase[("Firebase<br/>cloud backend<br/>[firebase_config.py]")]
  node_local_uploads[("Local Uploads<br/>filesystem storage")]
end

node_fe_shell -->|"bootstraps"| node_fe_app
node_fe_app -->|"navigates"| node_fe_router
node_fe_app -->|"hosts"| node_fe_modules
node_fe_modules -->|"calls"| node_fe_api
node_fe_router -->|"switches"| node_fe_modules
node_fe_api -->|"requests"| node_be_routes
node_be_main -->|"mounts"| node_be_routes
node_be_routes -->|"exposes"| node_be_auth
node_be_routes -->|"exposes"| node_be_upload
node_be_routes -->|"exposes"| node_be_analysis
node_be_routes -->|"exposes"| node_be_report
node_be_upload -->|"delegates"| node_be_upload_svc
node_be_analysis -->|"delegates"| node_be_pipeline
node_be_report -->|"delegates"| node_be_report_svc
node_be_upload_svc -->|"registers"| node_be_storage
node_be_pipeline -->|"runs"| node_be_stages
node_be_pipeline -->|"collects"| node_be_evidence
node_be_pipeline -->|"writes"| node_be_storage
node_be_storage -->|"persists"| node_be_models
node_be_evidence -->|"annotates"| node_be_models
node_be_stages -->|"uses"| node_be_utils
node_be_upload_svc -->|"stores"| node_local_uploads
node_be_auth -->|"authenticates"| node_firebase
node_be_storage -->|"syncs"| node_firebase

click node_fe_shell "https://github.com/novocainex/vortex-hackathon26/blob/main/hackathon/frontend/index.html"
click node_fe_app "https://github.com/novocainex/vortex-hackathon26/blob/main/hackathon/frontend/js/app.js"
click node_fe_router "https://github.com/novocainex/vortex-hackathon26/blob/main/hackathon/frontend/js/router.js"
click node_fe_api "https://github.com/novocainex/vortex-hackathon26/blob/main/hackathon/frontend/js/api.js"
click node_be_main "https://github.com/novocainex/vortex-hackathon26/blob/main/hackathon/backend/main.py"
click node_be_routes "https://github.com/novocainex/vortex-hackathon26/blob/main/hackathon/backend/routes/__init__.py"
click node_be_auth "https://github.com/novocainex/vortex-hackathon26/blob/main/hackathon/backend/routes/auth.py"
click node_be_upload "https://github.com/novocainex/vortex-hackathon26/blob/main/hackathon/backend/routes/upload.py"
click node_be_analysis "https://github.com/novocainex/vortex-hackathon26/blob/main/hackathon/backend/routes/analysis.py"
click node_be_report "https://github.com/novocainex/vortex-hackathon26/blob/main/hackathon/backend/routes/report.py"
click node_be_pipeline "https://github.com/novocainex/vortex-hackathon26/blob/main/hackathon/backend/services/pipeline_service.py"
click node_be_upload_svc "https://github.com/novocainex/vortex-hackathon26/blob/main/hackathon/backend/services/upload_service.py"
click node_be_report_svc "https://github.com/novocainex/vortex-hackathon26/blob/main/hackathon/backend/services/report_service.py"
click node_be_stages "https://github.com/novocainex/vortex-hackathon26/blob/main/hackathon/backend/services/preprocessing.py"
click node_be_evidence "https://github.com/novocainex/vortex-hackathon26/blob/main/hackathon/backend/services/anomaly_detection.py"
click node_be_storage "https://github.com/novocainex/vortex-hackathon26/blob/main/hackathon/backend/services/document_store.py"
click node_be_models "https://github.com/novocainex/vortex-hackathon26/blob/main/hackathon/backend/models/document.py"
click node_be_utils "https://github.com/novocainex/vortex-hackathon26/blob/main/hackathon/backend/utils/__init__.py"
click node_firebase "https://github.com/novocainex/vortex-hackathon26/blob/main/hackathon/backend/firebase_config.py"
click node_local_uploads "https://github.com/novocainex/vortex-hackathon26/tree/main/hackathon/backend/uploads/local_demo_user"

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_fe_shell,node_fe_app,node_fe_router,node_fe_api,node_fe_modules toneBlue
class node_be_main,node_be_routes,node_be_auth,node_be_upload,node_be_analysis,node_be_report,node_be_pipeline,node_be_upload_svc,node_be_report_svc,node_be_stages,node_be_evidence,node_be_storage,node_be_models,node_be_utils toneAmber
class node_firebase,node_local_uploads toneMint
```

## Components

### Frontend

Static dashboard client in plain HTML/CSS/JS

- [Dashboard](https://github.com/novocainex/vortex-hackathon26/blob/main/hackathon/frontend/index.html): static SPA · Thin browser UI for auth, upload, analysis, results, history, and reports · `hackathon/frontend/index.html`
- [App Core](https://github.com/novocainex/vortex-hackathon26/blob/main/hackathon/frontend/js/app.js): client bootstrap · Initializes the dashboard experience and shared state · `hackathon/frontend/js/app.js`
- [Router](https://github.com/novocainex/vortex-hackathon26/blob/main/hackathon/frontend/js/router.js): client navigation · Switches between dashboard views and modules · `hackathon/frontend/js/router.js`
- [API Client](https://github.com/novocainex/vortex-hackathon26/blob/main/hackathon/frontend/js/api.js): HTTP client · Browser-side integration layer for backend requests · `hackathon/frontend/js/api.js`
- **Feature Modules**: ui features · Auth, upload, batch analysis, results, history, and report screens

### Backend

FastAPI service and forensic pipeline

- [FastAPI App](https://github.com/novocainex/vortex-hackathon26/blob/main/hackathon/backend/main.py): service entrypoint · Backend application entrypoint and server wiring · `hackathon/backend/main.py`
- [API Routes](https://github.com/novocainex/vortex-hackathon26/blob/main/hackathon/backend/routes/__init__.py): HTTP routes · Request boundary split by auth, upload, analysis, and report · `hackathon/backend/routes/__init__.py`
- [Auth API](https://github.com/novocainex/vortex-hackathon26/blob/main/hackathon/backend/routes/auth.py): route module · Authentication boundary and Firebase-backed identity flow · `hackathon/backend/routes/auth.py`
- [Upload API](https://github.com/novocainex/vortex-hackathon26/blob/main/hackathon/backend/routes/upload.py): route module · Handles document intake and registration · `hackathon/backend/routes/upload.py`
- [Analysis API](https://github.com/novocainex/vortex-hackathon26/blob/main/hackathon/backend/routes/analysis.py): route module · Starts and queries forensic analysis jobs · `hackathon/backend/routes/analysis.py`
- [Report API](https://github.com/novocainex/vortex-hackathon26/blob/main/hackathon/backend/routes/report.py): route module · Serves verification and report output · `hackathon/backend/routes/report.py`
- [Pipeline Orchestrator](https://github.com/novocainex/vortex-hackathon26/blob/main/hackathon/backend/services/pipeline_service.py): service coordinator · Coordinates intake, stage execution, and result assembly · `hackathon/backend/services/pipeline_service.py`
- [Upload Service](https://github.com/novocainex/vortex-hackathon26/blob/main/hackathon/backend/services/upload_service.py): ingestion service · Registers uploads and prepares documents for processing · `hackathon/backend/services/upload_service.py`
- [Report Service](https://github.com/novocainex/vortex-hackathon26/blob/main/hackathon/backend/services/report_service.py): report builder · Turns analysis output into final verification reports · `hackathon/backend/services/report_service.py`
- [Forensic Stages](https://github.com/novocainex/vortex-hackathon26/blob/main/hackathon/backend/services/preprocessing.py): analysis modules · Preprocessing, OCR, pixel, layout, font, metadata, and risk scoring · `hackathon/backend/services/preprocessing.py`
- [Evidence Layer](https://github.com/novocainex/vortex-hackathon26/blob/main/hackathon/backend/services/anomaly_detection.py): signal tracking · Tracks anomalies, layout checks, and analysis registry for explainability · `hackathon/backend/services/anomaly_detection.py`
- [Persistence](https://github.com/novocainex/vortex-hackathon26/blob/main/hackathon/backend/services/document_store.py): document/job/result stores · Stores document metadata, jobs, and analysis results · `hackathon/backend/services/document_store.py`
- [Domain Models](https://github.com/novocainex/vortex-hackathon26/blob/main/hackathon/backend/models/document.py): data models · Primary document and analysis result objects · `hackathon/backend/models/document.py`
- [Utilities](https://github.com/novocainex/vortex-hackathon26/blob/main/hackathon/backend/utils/__init__.py): support libs · Encryption, file handling, image ops, security, and aggregation helpers · `hackathon/backend/utils/__init__.py`

### External

Cloud and runtime boundaries

- [Firebase](https://github.com/novocainex/vortex-hackathon26/blob/main/hackathon/backend/firebase_config.py): cloud backend · External auth and cloud storage boundary · `hackathon/backend/firebase_config.py`
- [Local Uploads](https://github.com/novocainex/vortex-hackathon26/tree/main/hackathon/backend/uploads/local_demo_user): filesystem storage · Encrypted per-user document storage used in local mode · `hackathon/backend/uploads/local_demo_user`

## Connections

- 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
