# meetox80/captcha-onnx-ocr architecture

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

- Interactive diagram: https://gitdiagram.com/meetox80/captcha-onnx-ocr
- Repository: https://github.com/meetox80/captcha-onnx-ocr

## Overview

##### Main Components
- API Server: The heart of the system is the Node.js API server (see src/app.js) which is built on Fastify. This component handles incoming HTTP requests.
- Routes and Controllers: In the src/routes and src/controllers directories, the endpoints are defined (e.g., CaptchaController in src/controllers/CaptchaController.js) that receive POST requests with image data.
- Model & ML Engine: The models directory holds the ONNX model file (captcha.onnx). The ONNX runtime (via onnxruntime-node) is responsible for running the model inference.
- Image Processing Tools: Libraries like Canvas and Sharp are used to preprocess image data before passing it into the ONNX model.
- Tokenization: The src/tokenizer directory shows additional processing steps (possibly for post-processing the output) with components like tokenizer_base.js.
- Environment Configuration: A .env.example file is provided, and dotenv is used to inject environment variables, ensuring that configuration parameters (e.g., port numbers, file paths for the model) are easily managed.
- Testing Infrastructure: The tests directory contains scripts to validate API and configuration aspects (with Mocha and other libraries for testing).

##### Relationships & Interactions
- External Clients (or automated test clients) send POST requests with the base64 image data to the API endpoint.
- The Fastify-based API server (src/app.js) routes incoming requests to MainRoutes (src/routes/MainRoutes.js), which then directs the request to the appropriate controller.
- The CaptchaController (src/controllers/CaptchaController.js) handles the business logic: it likely calls image preprocessing routines (using Canvas and Sharp) and then interacts with the ONNX runtime to load and run inference on the captcha.onnx model.
- After processing, the output could be tokenized or post-processed by the code in src/tokenizer.
- Finally, a response is sent back to the client containing the recognized CAPTCHA text.
- Testing tools verify the functionality by running tests that call these endpoints and verify expected outputs.

##### Architectural Patterns & Design Principles
- Separation of Concerns: Routes, controllers, and tokenization are handled separately to keep the code modular.
- API-First Design: The REST API is central, ensuring that all external interactions pass through a defined endpoint.
- ML Integration: A distinct component in the system is the ONNX-powered model that processes the image; this is kept modular to allow model updates without affecting the API.
- Environment-Based Configuration: For easy adaptability across environments, configuration is externalized using dotenv.

##### Additional Elements
- Notes on environment settings and testing aspects to underscore the infrastructure for deployment and validation.
- Highlighting error handling or logging (e.g., Pino-Pretty) as an additional supporting component.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Core Application Components
    Client["External Client (POST Request)"]:::client
    APIServer["Fastify API Server"]:::api
    Routes["API Routes"]:::api
    CaptchaCtrl["Captcha Controller"]:::api
    subgraph "Captcha Processing Pipeline"
        IP["Image Preprocessing (Canvas,Sharp)"]:::ml
        ONNX["ONNX Inference Engine"]:::ml
        Tokenizer["Tokenization Component"]:::ml
    end
    Response["Response to Client"]:::client

    %% Supporting Components
    EnvConfig["Environment Configuration (.env)"]:::support
    Testing["Testing Infrastructure"]:::support

    %% Data Flow
    Client -->|"POST"| APIServer
    APIServer -->|"routes"| Routes
    Routes -->|"calls"| CaptchaCtrl
    CaptchaCtrl -->|"preprocess"| IP
    IP -->|"run inference"| ONNX
    ONNX -->|"post-process"| Tokenizer
    Tokenizer -->|"result"| CaptchaCtrl
    CaptchaCtrl -->|"response"| Response

    %% Supporting Connections
    EnvConfig ---|support| APIServer
    Testing ---|support| APIServer

    %% Click Events
    click APIServer "https://github.com/meetox80/captcha-onnx-ocr/blob/main/src/app.js"
    click Routes "https://github.com/meetox80/captcha-onnx-ocr/blob/main/src/routes/MainRoutes.js"
    click CaptchaCtrl "https://github.com/meetox80/captcha-onnx-ocr/blob/main/src/controllers/CaptchaController.js"
    click ONNX "https://github.com/meetox80/captcha-onnx-ocr/blob/main/models/captcha.onnx"
    click Tokenizer "https://github.com/meetox80/captcha-onnx-ocr/blob/main/src/tokenizer/tokenizer_base.js"
    click EnvConfig "https://github.com/meetox80/captcha-onnx-ocr/blob/main/.env.example"
    click Testing "https://github.com/meetox80/captcha-onnx-ocr/tree/main/tests"

    %% Styles
    classDef client fill:#f9e79f,stroke:#d68910,stroke-width:2px;
    classDef api fill:#aed6f1,stroke:#2980b9,stroke-width:2px;
    classDef ml fill:#a9dfbf,stroke:#27ae60,stroke-width:2px;
    classDef support fill:#d5dbdb,stroke:#616a6b,stroke-width:2px;
```
