# gilbertossoares/anonimizer architecture

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

- Interactive diagram: https://gitdiagram.com/gilbertossoares/anonimizer
- Repository: https://github.com/gilbertossoares/anonimizer

## Overview

##### Project Type and Purpose
- This is a full-stack Python web application (Flask) for anonymizing documents (PDF, DOCX, TXT) by detecting and removing PII via Azure AI services.
- The user interface (HTML/CSS/JS) handles file uploads and status display; the backend (app.py + utils/) orchestrates storage, AI calls, conversion, anonymization, and result retrieval.

##### File Structure Analysis
- Top-level:
- app.py – Flask entry point; defines routes for upload, search, modify.
- requirements.txt – Python dependencies (Flask, Azure SDKs).
- startup.sh – launch script.
- .env (not in tree) – holds Azure credentials.
- Templates: Jinja2 HTML pages for the UI.
- utils/: core modules:
- anonimizer.py – text anonymization logic.
- converter.py – extract/convert text from various formats.
- signature.py – apply digital signatures or watermarks.
- azure_blob.py – upload/download to Azure Blob Storage.

##### Key README Insights
- Integrates multiple Azure services: Blob Storage, Form Recognizer, Computer Vision (including Custom Vision), Cognitive Search, Text Analytics, Data Lake.
- Workflow images define how a file flows through ingestion, PII detection, replacement, and delivery.

##### Main Components
a. User Interface Layer
- Web Browser – HTML/JS for file upload & result view.
- Static CDN (optional) – serves CSS/JS.
b. Application Server
- Flask App (app.py)
- Template Engine (Jinja2)
- Business Logic (utils/*.py)
c. Storage Layer
- Azure Blob Storage
– Input Container (raw uploads)
– Output Container (anonymized docs)
- (Optional) Azure Data Lake for long-term archival
d. AI Services Layer
- Azure Form Recognizer – OCR & field extraction
- Azure Text Analytics – PII detection
- Azure Computer Vision – image-based PII detection
- Azure Custom Vision – domain-specific PII models
- Azure Cognitive Search – index & search redacted content
e. Conversion & Post-processing
- converter.py (text extraction/format conversion)
- anonimizer.py (PII replacement)
- signature.py (digital signature, watermarking)
f. External Clients
- Admin tools (if any) calling REST endpoints
- Automated pipelines via Azure SDK/CLI

##### Relationships and Data Flow
1. User uploads a document via browser → Flask upload endpoint.
2. Flask streams file to Azure Blob (Input Container).
3. Flask triggers Form Recognizer/OCR → raw text.
4. Text passed to Text Analytics & Custom Vision for PII detection.
5. converter.py normalizes format (e.g., DOCX → text).
6. anonimizer.py replaces/redacts PII tokens.
7. signature.py applies signatures/watermarks.
8. Anonymized file saved back to Azure Blob (Output Container).
9. Flask returns download link to user (via templates/search.html).
10. (Optional) Index into Cognitive Search for metadata lookup.

##### Architectural Patterns & Design Principles
- Layered Architecture: clear separation UI → App Logic → AI Services → Storage.
- Single-process monolith (Flask) but logically modular via utils/.
- Environment-driven configuration (.env).
- Externalize state to Azure Storage—stateless app server.
- Asynchronous or synchronous service calls over HTTPS (Azure SDK).

- Frontend (blue): browser, static assets, templates.
- Backend (green): Flask app, utils modules.
- Storage (orange): Azure Blob/Data Lake.
- AI Services (purple): Form Recognizer, Text Analytics, Computer Vision, Search.
- SDK/API calls: Flask → Azure Services.
- Data flow: Blob storage ↔ Flask.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Client Layer" 
        direction TB
        Browser["Web Browser"]:::frontend
        subgraph "Static Assets"
            CSS["search.css"]:::frontend
            JS["search.js"]:::frontend
        end
        subgraph "HTML Templates"
            Upload["upload.html"]:::frontend
            SearchPage["search.html"]:::frontend
            Modify["modify.html"]:::frontend
            Home["index.html"]:::frontend
        end
    end

    %% Backend Layer
    subgraph "Server Layer"
        direction TB
        FlaskApp["Flask App<br/>(app.py)"]:::backend
        subgraph "Business Logic Modules"
            Converter["converter.py"]:::backend
            Anon["anonimizer.py"]:::backend
            Signature["signature.py"]:::backend
            BlobUtil["azure_blob.py"]:::backend
        end
        Script["startup.sh"]:::backend
        Req["requirements.txt"]:::backend
        Env[".env"]:::backend
    end

    %% Storage Layer
    subgraph "Storage Layer"
        direction TB
        BlobInput["Azure Blob<br/>Input Container"]:::storage
        BlobOutput["Azure Blob<br/>Output Container"]:::storage
        DataLake["Azure Data Lake"]:::storage
    end

    %% AI Services Layer
    subgraph "AI Services"
        direction TB
        FormRec["Form Recognizer"]:::ai
        TextAI["Text Analytics"]:::ai
        CompVis["Computer Vision"]:::ai
        CustVis["Custom Vision"]:::ai
        CogSearch["Cognitive Search"]:::ai
    end

    %% Documentation
    subgraph "Docs & Metadata"
        Readme["readme.md"]:::docs
        License["LICENSE"]:::docs
    end

    %% Relationships
    Browser -->|HTTP POST Upload| FlaskApp
    CSS -->|served by| Browser
    JS -->|served by| Browser
    FlaskApp -->|renders| Upload
    FlaskApp -->|renders| SearchPage
    FlaskApp -->|renders| Modify
    FlaskApp -->|renders| Home

    FlaskApp -->|SDK Upload| BlobInput
    FlaskApp -->|SDK Download| BlobOutput

    FlaskApp -->|REST OCR| FormRec
    FlaskApp -->|REST PII Analysis| TextAI
    FlaskApp -->|REST Image PII| CompVis
    FlaskApp -->|REST Domain Model| CustVis

    BlobInput -->|text extraction| Converter
    Converter -->|raw text| Anon
    Anon -->|redacted text| Signature
    Signature -->|final document| BlobOutput

    FlaskApp -->|Index metadata| CogSearch

    FlaskApp --> Script
    FlaskApp --> Req
    FlaskApp --> Env

    FlaskApp --> Converter
    FlaskApp --> Anon
    FlaskApp --> Signature
    FlaskApp --> BlobUtil

    %% Click Events
    click CSS "https://github.com/gilbertossoares/anonimizer/blob/main/static/css/search.css"
    click JS "https://github.com/gilbertossoares/anonimizer/blob/main/static/js/search.js"
    click Upload "https://github.com/gilbertossoares/anonimizer/blob/main/templates/upload.html"
    click SearchPage "https://github.com/gilbertossoares/anonimizer/blob/main/templates/search.html"
    click Modify "https://github.com/gilbertossoares/anonimizer/blob/main/templates/modify.html"
    click Home "https://github.com/gilbertossoares/anonimizer/blob/main/templates/index.html"
    click FlaskApp "https://github.com/gilbertossoares/anonimizer/blob/main/app.py"
    click Script "https://github.com/gilbertossoares/anonimizer/blob/main/startup.sh"
    click Req "https://github.com/gilbertossoares/anonimizer/blob/main/requirements.txt"
    click Converter "https://github.com/gilbertossoares/anonimizer/blob/main/utils/converter.py"
    click Anon "https://github.com/gilbertossoares/anonimizer/blob/main/utils/anonimizer.py"
    click Signature "https://github.com/gilbertossoares/anonimizer/blob/main/utils/signature.py"
    click BlobUtil "https://github.com/gilbertossoares/anonimizer/blob/main/utils/azure_blob.py"
    click Readme "https://github.com/gilbertossoares/anonimizer/blob/main/readme.md"
    click License "https://github.com/gilbertossoares/anonimizer/tree/main/LICENSE"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#0366D6,color:#0366D6;
    classDef backend fill:#DFFFE0,stroke:#22863A,color:#22863A;
    classDef storage fill:#FFECD1,stroke:#B31D28,color:#B31D28;
    classDef ai fill:#F0E6FF,stroke:#6F42C1,color:#6F42C1;
    classDef docs fill:#F5F5F5,stroke:#666,color:#666;
```
