# fightandsurvive/filenimbus architecture

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

- Interactive diagram: https://gitdiagram.com/fightandsurvive/filenimbus
- Repository: https://github.com/fightandsurvive/filenimbus

## Overview

FileNimbus is a scanned-case-file ingestion, retrieval, and audit platform. The principal workflow is workstation or network scanning (and share-based ingestion), server-side metadata and OCR processing, PostgreSQL indexing, then authenticated search and file access with audit events. Separate branches cover duplicate review, alerts/remediation, operational analytics, and admin reports. The README establishes several subsystem capabilities whose implementation was not sampled; those relationships are shown as documented rather than inferred from module names.

Main entry points: [`api/db.py`](https://github.com/fightandsurvive/filenimbus/blob/main/api/db.py) (Database access), [`api/app.py`](https://github.com/fightandsurvive/filenimbus/blob/main/api/app.py) (API application), [`ocr/backend/routes.py`](https://github.com/fightandsurvive/filenimbus/blob/main/ocr/backend/routes.py) (Scan staging), [`api/routes/search.py`](https://github.com/fightandsurvive/filenimbus/blob/main/api/routes/search.py) (Search endpoints)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Client experience"]
  node_web["Web interface<br/>[api.js]"]
  node_search_ui["Search interface<br/>[search.js]"]
end

subgraph group_ingest["Ingestion and OCR"]
  node_scan_agent["Scan agent<br/>[agent.py]"]
  node_scanner_backends["Scanner drivers<br/>[escl.py]"]
  node_scan_ingest["Scan staging<br/>[routes.py]"]
  node_page_ocr["Page analysis<br/>[analyze.py]"]
  node_share_watcher["Share ingestion<br/>[watcher.py]"]
  node_ocr_worker["OCR enrichment<br/>[ocr_worker.py]"]
end

subgraph group_core["Application core"]
  node_api_app["API application<br/>[app.py]"]
  node_auth["Authentication<br/>[auth.py]"]
  node_security["Role enforcement<br/>[security.py]"]
  node_search_api["Search endpoints<br/>[search.py]"]
  node_search_engine["Search engine<br/>[search.py]"]
  node_file_access["File access<br/>[files.py]"]
end

subgraph group_operations["Operations and review"]
  node_duplicate_review["Duplicate review<br/>[duplicates.py]"]
  node_alerts["Alerts and remediation<br/>[alerts.py]"]
  node_reports["Reports and analytics<br/>[reports.py]"]
  node_report_builder["Admin reports<br/>[reports_builder.py]"]
  node_activity["Activity and audit<br/>[activity.py]"]
end

subgraph group_data["Persistence"]
  node_db_helpers["Database access<br/>[db.py]"]
  node_postgres[("Platform database")]
end

node_staff(("Staff and scanners"))

node_staff -->|"uses"| node_web
node_staff -->|"scans with"| node_scan_agent
node_scanner_backends -->|"provides scans"| node_scan_agent
node_scan_agent -.->|"submits PDFs"| node_scan_ingest
node_scan_ingest -.->|"analyzes scans"| node_page_ocr
node_share_watcher -.->|"ingests files"| node_db_helpers
node_ocr_worker -.->|"updates OCR"| node_db_helpers
node_web -.->|"requests API"| node_api_app
node_api_app -->|"routes to"| node_auth
node_api_app -->|"routes to"| node_search_api
node_api_app -->|"routes to"| node_file_access
node_api_app -.->|"mounts routes"| node_scan_ingest
node_auth -->|"authenticates via"| node_security
node_search_ui -.->|"submits queries"| node_search_api
node_search_api -->|"searches with"| node_search_engine
node_search_api -->|"logs events"| node_db_helpers
node_search_engine -->|"queries index"| node_postgres
node_file_access -->|"uses search"| node_search_engine
node_file_access -->|"reads file records"| node_db_helpers
node_scan_ingest -->|"records scans"| node_db_helpers
node_db_helpers -->|"queries and writes"| node_postgres
node_duplicate_review -.->|"reviews duplicates"| node_postgres
node_alerts -->|"reads and updates"| node_postgres
node_reports -->|"queries metrics"| node_postgres
node_report_builder -.->|"runs reports"| node_postgres
node_activity -.->|"reads audit data"| node_postgres

click node_web "https://github.com/fightandsurvive/filenimbus/blob/main/web/api.js"
click node_search_ui "https://github.com/fightandsurvive/filenimbus/blob/main/web/search.js"
click node_scan_agent "https://github.com/fightandsurvive/filenimbus/blob/main/ocr/scan_agent/agent.py"
click node_scanner_backends "https://github.com/fightandsurvive/filenimbus/blob/main/ocr/scan_agent/escl.py"
click node_scan_ingest "https://github.com/fightandsurvive/filenimbus/blob/main/ocr/backend/routes.py"
click node_page_ocr "https://github.com/fightandsurvive/filenimbus/blob/main/ocr/backend/analyze.py"
click node_share_watcher "https://github.com/fightandsurvive/filenimbus/blob/main/scripts/watcher.py"
click node_ocr_worker "https://github.com/fightandsurvive/filenimbus/blob/main/scripts/ocr_worker.py"
click node_api_app "https://github.com/fightandsurvive/filenimbus/blob/main/api/app.py"
click node_auth "https://github.com/fightandsurvive/filenimbus/blob/main/api/routes/auth.py"
click node_security "https://github.com/fightandsurvive/filenimbus/blob/main/api/security.py"
click node_search_api "https://github.com/fightandsurvive/filenimbus/blob/main/api/routes/search.py"
click node_search_engine "https://github.com/fightandsurvive/filenimbus/blob/main/api/search/search.py"
click node_file_access "https://github.com/fightandsurvive/filenimbus/blob/main/api/routes/files.py"
click node_duplicate_review "https://github.com/fightandsurvive/filenimbus/blob/main/api/routes/duplicates.py"
click node_alerts "https://github.com/fightandsurvive/filenimbus/blob/main/api/routes/alerts.py"
click node_reports "https://github.com/fightandsurvive/filenimbus/blob/main/api/routes/reports.py"
click node_report_builder "https://github.com/fightandsurvive/filenimbus/blob/main/api/routes/reports_builder.py"
click node_activity "https://github.com/fightandsurvive/filenimbus/blob/main/api/routes/activity.py"
click node_db_helpers "https://github.com/fightandsurvive/filenimbus/blob/main/api/db.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_web,node_search_ui toneBlue
class node_scan_agent,node_scanner_backends,node_scan_ingest,node_page_ocr,node_share_watcher,node_ocr_worker toneAmber
class node_api_app,node_auth,node_security,node_search_api,node_search_engine,node_file_access toneMint
class node_duplicate_review,node_alerts,node_reports,node_report_builder,node_activity toneRose
class node_db_helpers,node_postgres,node_staff toneIndigo
```

## Components

### Client experience

- [Web interface](https://github.com/fightandsurvive/filenimbus/blob/main/web/api.js): `web/api.js`
- [Search interface](https://github.com/fightandsurvive/filenimbus/blob/main/web/search.js): `web/search.js`

### Ingestion and OCR

- [Scan agent](https://github.com/fightandsurvive/filenimbus/blob/main/ocr/scan_agent/agent.py): `ocr/scan_agent/agent.py`
- [Scanner drivers](https://github.com/fightandsurvive/filenimbus/blob/main/ocr/scan_agent/escl.py): `ocr/scan_agent/escl.py`
- [Scan staging](https://github.com/fightandsurvive/filenimbus/blob/main/ocr/backend/routes.py): `ocr/backend/routes.py`
- [Page analysis](https://github.com/fightandsurvive/filenimbus/blob/main/ocr/backend/analyze.py): `ocr/backend/analyze.py`
- [Share ingestion](https://github.com/fightandsurvive/filenimbus/blob/main/scripts/watcher.py): `scripts/watcher.py`
- [OCR enrichment](https://github.com/fightandsurvive/filenimbus/blob/main/scripts/ocr_worker.py): `scripts/ocr_worker.py`

### Application core

- [API application](https://github.com/fightandsurvive/filenimbus/blob/main/api/app.py): `api/app.py`
- [Authentication](https://github.com/fightandsurvive/filenimbus/blob/main/api/routes/auth.py): `api/routes/auth.py`
- [Role enforcement](https://github.com/fightandsurvive/filenimbus/blob/main/api/security.py): `api/security.py`
- [Search endpoints](https://github.com/fightandsurvive/filenimbus/blob/main/api/routes/search.py): `api/routes/search.py`
- [Search engine](https://github.com/fightandsurvive/filenimbus/blob/main/api/search/search.py): `api/search/search.py`
- [File access](https://github.com/fightandsurvive/filenimbus/blob/main/api/routes/files.py): `api/routes/files.py`

### Operations and review

- [Duplicate review](https://github.com/fightandsurvive/filenimbus/blob/main/api/routes/duplicates.py): `api/routes/duplicates.py`
- [Alerts and remediation](https://github.com/fightandsurvive/filenimbus/blob/main/api/routes/alerts.py): `api/routes/alerts.py`
- [Reports and analytics](https://github.com/fightandsurvive/filenimbus/blob/main/api/routes/reports.py): `api/routes/reports.py`
- [Admin reports](https://github.com/fightandsurvive/filenimbus/blob/main/api/routes/reports_builder.py): `api/routes/reports_builder.py`
- [Activity and audit](https://github.com/fightandsurvive/filenimbus/blob/main/api/routes/activity.py): `api/routes/activity.py`

### Persistence

- [Database access](https://github.com/fightandsurvive/filenimbus/blob/main/api/db.py): `api/db.py`
- **Platform database**

### Other components

- **Staff and scanners**

## Connections

- Staff and scanners → Web interface: uses
- Staff and scanners → Scan agent: scans with
- Scanner drivers → Scan agent: provides scans (evidence: `ocr/scan_agent/agent.py`)
- Scan agent → Scan staging: submits PDFs
- Scan staging → Page analysis: analyzes scans
- Share ingestion → Database access: ingests files
- OCR enrichment → Database access: updates OCR (evidence: `scripts/ocr_worker.py`)
- Web interface → API application: requests API
- API application → Authentication: routes to (evidence: `api/app.py`)
- API application → Search endpoints: routes to (evidence: `api/app.py`)
- API application → File access: routes to (evidence: `api/app.py`)
- API application → Scan staging: mounts routes (evidence: `api/app.py`)
- Authentication → Role enforcement: authenticates via (evidence: `api/routes/auth.py`)
- Search interface → Search endpoints: submits queries
- Search endpoints → Search engine: searches with (evidence: `api/routes/search.py`)
- Search endpoints → Database access: logs events (evidence: `api/routes/search.py`)
- Search engine → Platform database: queries index (evidence: `api/search/search.py`)
- File access → Search engine: uses search (evidence: `api/routes/files.py`)
- File access → Database access: reads file records (evidence: `api/routes/files.py`)
- Scan staging → Database access: records scans (evidence: `ocr/backend/routes.py`)
- Database access → Platform database: queries and writes (evidence: `api/db.py`)
- Duplicate review → Platform database: reviews duplicates
- Alerts and remediation → Platform database: reads and updates (evidence: `api/routes/alerts.py`)
- Reports and analytics → Platform database: queries metrics (evidence: `api/routes/reports.py`)
- Admin reports → Platform database: runs reports
- Activity and audit → Platform database: reads audit data
