# promanczak-hub/anonimizator-v3 architecture

> Architecture diagram of the GitHub repository promanczak-hub/anonimizator-v3, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-02-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/promanczak-hub/anonimizator-v3
- Repository: https://github.com/promanczak-hub/anonimizator-v3

## Overview

##### Project type and purpose
- This is a full-stack web application (“Anonimizator v3”) for PDF anonymization and schema extraction (Digital Twin JSON).
- Users upload or drop PDFs; the system processes them in two modes (“Unify” vs “Layout”), using AI (Vertex AI) and returns redacted PDFs or JSON.

##### File structure
- Top-level services orchestrated by docker-compose:
- frontend/ (React + Vite)
- backend/ (FastAPI + Celery)
- Redis (queue)
- PostgreSQL (database)
- watch folder for incoming PDFs
- backend/app/api: HTTP endpoints (documents, jobs, health)
- backend/app/services & workers:
- watcher.py monitors watch folder
- pdf_processor.py handles parsing/redaction
- vertex_ai.py invokes external AI
- Celery tasks (workers/tasks.py) for async processing
- frontend/src: React components and pages, API client module (api/client.js)

##### README insights
- Confirms tech stack: React 19 + Vite, FastAPI + Celery, PostgreSQL, Redis, Vertex AI
- Highlights two processing modes and “watch” folder concept

##### Main components
a. User & Browser (client)
b. Frontend Service (React/Vite)
c. Backend API Service (FastAPI + Uvicorn)
d. Message Broker (Redis queue)
e. Celery Worker Pool (async tasks)
f. Watch Folder (file drop area)
g. PDF Processor & AI Service (Vertex AI)
h. Database (PostgreSQL)
i. Storage (for original & processed PDFs, JSON)
j. External Services (Vertex AI)

##### Relationships & data flow
1. User → (HTTP) Frontend → uploads PDF or triggers processing
2. Frontend → (HTTP POST) → Backend API (/documents or /jobs)
3. Backend API
- writes metadata to PostgreSQL (models/document, job)
- publishes a Celery task to Redis
4. Celery Worker picks up task → watcher or tasks.py
- invokes pdf_processor.py to parse/redact
- calls vertex_ai.py for AI inference
- writes results (redacted PDF or Digital Twin JSON) to storage
- updates job status in PostgreSQL
5. Frontend polls or fetches job/document status via API
6. Frontend displays redacted PDF or JSON viewer

##### Architectural patterns & principles
- Separation of concerns: UI vs API vs background processing
- Event-driven / asynchronous: Celery + Redis for decoupling
- Microservice-style isolation: each component in its own Docker container
- Watcher pattern: auto-ingest of PDFs from file system

##### Additional touches
- Directories or modules next to each component
- Optional: show Docker Compose as an orchestration layer around all containers

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Frontend" 
        direction TB
        UserBrowser["User & Browser"]:::frontend
        FrontendService["React + Vite"]:::frontend
        ApiClient["API Client Module"]:::frontend
    end

    subgraph "Backend API Service"
        direction TB
        Main["FastAPI (uvicorn)"]:::service
        ApiModule["API Endpoints"]:::service
    end

    subgraph "Backend Worker Pool"
        direction TB
        CeleryWorker["Celery Worker"]:::service
        Watcher["Watcher Service"]:::service
        PdfProcessor["PDF Processor"]:::service
        VertexAiService["AI Service"]:::service
    end

    subgraph "Infrastructure"
        direction TB
        Redis["Redis Queue"]:::queue
        PostgreSQL["PostgreSQL DB"]:::datastore
        Storage["File Storage"]:::datastore
    end

    subgraph "External Services"
        direction TB
        VertexAIExternal["Vertex AI"]:::external
    end

    %% Connections
    UserBrowser -->|"loads app"| FrontendService
    FrontendService -->|"uses client"| ApiClient
    ApiClient -->|"HTTP POST /documents or /jobs"| Main
    Main -->|"writes metadata"| PostgreSQL
    Main -->|"enqueue task"| Redis

    Watcher -->|"enqueue task"| Redis

    CeleryWorker -->|"consume task"| Redis
    CeleryWorker -->|"invoke"| PdfProcessor
    PdfProcessor -->|"call AI"| VertexAiService
    VertexAiService -->|"AI inference"| VertexAIExternal
    PdfProcessor -->|"store results"| Storage
    CeleryWorker -->|"update status"| PostgreSQL

    FrontendService -->|"polls status"| Main
    FrontendService -->|"fetches output"| Storage

    %% Docker Compose orchestration
    DockerCompose["Docker Compose"]:::orchestrator
    DockerCompose --> FrontendService
    DockerCompose --> Main
    DockerCompose --> CeleryWorker
    DockerCompose --> Redis
    DockerCompose --> PostgreSQL

    %% Click Events
    click UserBrowser "https://github.com/promanczak-hub/anonimizator-v3/blob/main/frontend/index.html"
    click FrontendService "https://github.com/promanczak-hub/anonimizator-v3/tree/main/frontend/"
    click ApiClient "https://github.com/promanczak-hub/anonimizator-v3/blob/main/frontend/src/api/client.js"
    click Main "https://github.com/promanczak-hub/anonimizator-v3/blob/main/backend/app/main.py"
    click ApiModule "https://github.com/promanczak-hub/anonimizator-v3/tree/main/backend/app/api/"
    click Redis "https://github.com/promanczak-hub/anonimizator-v3/blob/main/docker-compose.yml"
    click CeleryWorker "https://github.com/promanczak-hub/anonimizator-v3/blob/main/backend/app/workers/tasks.py"
    click Watcher "https://github.com/promanczak-hub/anonimizator-v3/blob/main/backend/app/services/watcher.py"
    click PdfProcessor "https://github.com/promanczak-hub/anonimizator-v3/blob/main/backend/app/services/pdf_processor.py"
    click VertexAiService "https://github.com/promanczak-hub/anonimizator-v3/blob/main/backend/app/services/vertex_ai.py"
    click PostgreSQL "https://github.com/promanczak-hub/anonimizator-v3/blob/main/backend/app/database.py"
    click Storage "https://github.com/promanczak-hub/anonimizator-v3/blob/main/test-data/sample.pdf"
    click DockerCompose "https://github.com/promanczak-hub/anonimizator-v3/blob/main/docker-compose.yml"

    %% Styles
    classDef frontend fill:#a2f5a2,stroke:#333,stroke-width:1px
    classDef service fill:#a2d1f5,stroke:#333,stroke-width:1px
    classDef datastore fill:#f5d1a2,stroke:#333,stroke-width:1px
    classDef queue fill:#f5f1a2,stroke:#333,stroke-width:1px
    classDef external fill:#cccccc,stroke:#333,stroke-width:1px
    classDef orchestrator fill:#e1e1e1,stroke:#333,stroke-width:1px
```
