# shoebsd31/ocr-form-tools architecture

> Architecture diagram of the GitHub repository shoebsd31/ocr-form-tools, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/shoebsd31/ocr-form-tools
- Repository: https://github.com/shoebsd31/ocr-form-tools

## Overview

##### Project type and purpose
- This is a full-stack hybrid application: a React+Redux web app (bootstrapped with Create React App) that can also run as a desktop app via Electron.
- Purpose: an open-source Form OCR Testing Tool (FOTT) for Azure Form Recognizer. Core workflows are: upload forms, label text/tables, train models, predict/analyze forms, and compose models. A separate Python CLI handles batch redaction.

##### File structure
- Top-level:
- config/webpack.* – front-end build pipelines (dev/prod)
- Dockerfile + nginx.conf – containerized web deployment
- electron-builder.yml – desktop packaging settings
- scripts/redact_cli_py/ – standalone Python redaction tool
- src/:
- src/react/components & pages – UI views and layouts
- src/redux/ – actions, reducers, middleware, store setup
- src/services/ – business logic (assetService, projectService, ocrService, predictService, telemetryService)
- src/providers/storage – provider pattern for Azure Blob & local file system
- src/electron/ – Electron “main” process, IPC proxies, desktop-only providers
- public/: static Python helpers and HTML entrypoints

##### README
- Confirms React+Redux architecture, Electron desktop support, Docker instructions, and the tool’s feature set (Label → Train → Analyze → Compose).
- Mentions provider model (extensible source/target), Form Recognizer REST API integration, and Azure Blob Storage.

##### Main components
A. Frontend (Renderer)
- React components (common, pages, shell, toolbar)
- Redux store (unidirectional data flow)
B. Electron Main (desktop only)
- App bootstrap (main.ts, start.js)
- IPC channel to renderer
- Local file system provider
C. Services Layer
- Business services calling REST APIs (Form Recognizer)
- Asset/project/predict/telemetry services
D. Storage Providers
- Azure Blob Storage (HTTP via SAS URL)
- Local FS (desktop path via IPC)
E. External Dependencies
- Azure Form Recognizer REST endpoint
- Azure Blob Storage account
F. CLI Redaction Tool
- Separate Python process reading/writing blobs or files

##### Relationships and interactions
- Renderer dispatches Redux actions → Store updates → UI re-renders.
- UI invokes services (via serviceHelper) → storageProviderFactory picks Azure or local provider.
- Services → Azure Blob Storage (list/download/upload) and → Form Recognizer (train/predict).
- In desktop mode: UI ↔ IPC ↔ Electron Main ↔ Local FS.
- CLI tool runs independently for batch redaction of images/documents.

##### Architectural patterns
- Flux/Redux unidirectional data flow
- Provider pattern for pluggable storage/telemetry
- IPC gateway between Renderer and Main for desktop features
- Modular React component hierarchy (common vs pages)
- Build pipelines (webpack for web, electron-builder for desktop)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Subgraphs for layers
    subgraph "Renderer (Browser/Electron Renderer)"
        direction TB
        ReactUI["React UI"]:::ui
        ReduxStore["Redux Store"]:::store
    end

    subgraph "Electron Main (Desktop Only)"
        direction TB
        ElectronMain["Electron Main Process"]:::electron
        LocalFSProvider["Local File System Provider"]:::provider
    end

    subgraph "Core (Services & Providers)"
        direction TB
        subgraph "Business Services" 
            direction TB
            AssetService["Asset Service"]:::services
            ProjectService["Project Service"]:::services
            OCRService["OCR Service"]:::services
            PredictService["Predict Service"]:::services
            TelemetryService["Telemetry Service"]:::services
            ServiceHelper["Service Helper"]:::services
        end
        ProviderFactory["Storage Provider Factory"]:::provider
        AzureBlobProvider["Azure Blob Storage Provider"]:::provider
        LocalFSProxyProvider["Local FS Proxy Provider"]:::provider
        AssetProviderFactory["Asset Provider Factory"]:::provider
    end

    subgraph "External Dependencies"
        direction TB
        FormRecognizer["Azure Form Recognizer API"]:::external
        AzureBlobStorage["Azure Blob Storage"]:::external
        CLI["Python Redaction CLI"]:::cli
    end

    %% Connections
    ReactUI -->|"dispatch actions"| ReduxStore
    ReduxStore -->|"calls services via Service Helper"| ServiceHelper
    ServiceHelper -->|"routes to services"| AssetService
    ServiceHelper --> ProjectService
    ServiceHelper --> OCRService
    ServiceHelper --> PredictService
    ServiceHelper --> TelemetryService

    AssetService -->|"uses"| ProviderFactory
    ProjectService --> ProviderFactory
    OCRService --> ProviderFactory
    PredictService --> ProviderFactory

    ProviderFactory -->|"provides"| AzureBlobProvider
    ProviderFactory --> localFSContext
    AzureBlobProvider -->|"HTTP(S) SAS"| AzureBlobStorage
    AzureBlobProvider -->|"calls train/predict"| FormRecognizer

    subgraph "Local FS via IPC"
        direction TB
        localFSContext["Local File System (IPC)"]:::provider
    end

    ElectronMain -->|"IPC channel"| localFSContext
    LocalFSProvider --> localFSContext
    localFSContext -->|"file read/write"| LocalFSProvider

    CLI -->|"reads/writes"| AzureBlobStorage
    CLI --> localFSContext

    %% Click Events
    click ReactUI "https://github.com/shoebsd31/ocr-form-tools/tree/master/src/react/components"
    click ReduxStore "https://github.com/shoebsd31/ocr-form-tools/tree/master/src/redux/store"
    click ElectronMain "https://github.com/shoebsd31/ocr-form-tools/blob/master/src/electron/main.ts"
    click ElectronMain "https://github.com/shoebsd31/ocr-form-tools/blob/master/src/electron/start.js"
    click ElectronMain "https://github.com/shoebsd31/ocr-form-tools/blob/master/src/electron/common/ipcMainProxy.ts"
    click LocalFSProvider "https://github.com/shoebsd31/ocr-form-tools/blob/master/src/electron/providers/storage/localFileSystem.ts"
    click AssetService "https://github.com/shoebsd31/ocr-form-tools/blob/master/src/services/assetService.ts"
    click ProjectService "https://github.com/shoebsd31/ocr-form-tools/blob/master/src/services/projectService.ts"
    click OCRService "https://github.com/shoebsd31/ocr-form-tools/blob/master/src/services/ocrService.ts"
    click PredictService "https://github.com/shoebsd31/ocr-form-tools/blob/master/src/services/predictService.ts"
    click TelemetryService "https://github.com/shoebsd31/ocr-form-tools/blob/master/src/services/telemetryService.ts"
    click ServiceHelper "https://github.com/shoebsd31/ocr-form-tools/blob/master/src/services/serviceHelper.ts"
    click AzureBlobProvider "https://github.com/shoebsd31/ocr-form-tools/blob/master/src/providers/storage/azureBlobStorage.ts"
    click LocalFSProxyProvider "https://github.com/shoebsd31/ocr-form-tools/blob/master/src/providers/storage/localFileSystemProxy.ts"
    click AssetProviderFactory "https://github.com/shoebsd31/ocr-form-tools/blob/master/src/providers/storage/assetProviderFactory.ts"
    click ProviderFactory "https://github.com/shoebsd31/ocr-form-tools/blob/master/src/providers/storage/storageProviderFactory.ts"
    click CLI "https://github.com/shoebsd31/ocr-form-tools/blob/master/scripts/redact_cli_py/batch_redact.py"
    click CLI "https://github.com/shoebsd31/ocr-form-tools/tree/master/scripts/redact_cli_py/redact_cli_py"
    click ReactUI "https://github.com/shoebsd31/ocr-form-tools/tree/master/src/react/components/pages"
    click ReduxStore "https://github.com/shoebsd31/ocr-form-tools/tree/master/src/redux/actions"
    click ReduxStore "https://github.com/shoebsd31/ocr-form-tools/tree/master/src/redux/reducers"
    click ProviderFactory "https://github.com/shoebsd31/ocr-form-tools/blob/master/src/providers/storage/storageProviderFactory.ts"
    click AssetProviderFactory "https://github.com/shoebsd31/ocr-form-tools/blob/master/src/providers/storage/assetProviderFactory.ts"
    click ReactUI "https://github.com/shoebsd31/ocr-form-tools/tree/master/src/react/components"
    click ReactUI "https://github.com/shoebsd31/ocr-form-tools/tree/master/src/react/components/pages"

    %% Styling
    classDef ui fill:#cce5ff,stroke:#004085,color:#004085;
    classDef store fill:#e2e3e5,stroke:#6c757d,color:#6c757d;
    classDef services fill:#d4edda,stroke:#155724,color:#155724;
    classDef provider fill:#fff3cd,stroke:#856404,color:#856404;
    classDef external fill:#f8d7da,stroke:#721c24,color:#721c24;
    classDef electron fill:#d1ecf1,stroke:#0c5460,color:#0c5460;
    classDef cli fill:#f5c6cb,stroke:#721c24,color:#721c24;
```
