# belashov641618/tradeshield architecture

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

- Interactive diagram: https://gitdiagram.com/belashov641618/tradeshield
- Repository: https://github.com/belashov641618/tradeshield

## Overview

##### Project type and purpose
- TradeShield is a containerized full-stack web application for automated analysis of customs-tariff regulation measures (TTR).
- Users enter a product name or HS code; the system fetches trade and statistical data, applies rule‐based measures (from the measures library), and produces recommendations and PDF reports.

##### File structure
- Top-level directories:
- frontend/ – web UI (Flask app.py, index.html, startup script)
- backend/ – API server (main.py, requirements.txt, docker-compose.yml)
- measures/ – domain logic: per-measure Python clauses and JSON descriptions
- postgres/ – database schema (tables.py), initialization script, docker-compose.yml
- redis/ – message broker container definition
- workers/ – background services:
– data_extractor/ (pull external data)
– report_creator/ (generate PDF reports)
- utilities/ – helper scripts (gitpull for updating code, load_clauses for loading measure definitions)
- Each service has its own Docker Compose file, indicating a microservice‐style deployment.

##### README insights
- System gathers: customs stats, Rosstat data, WTO obligations.
- Applies algorithms and rule sets to recommend measures (tariffs, certification, anti-dumping).
- Outputs both explanation and PDF reports.

##### Main components and interactions
a. Components:
- User Web Browser
- Frontend Flask App
- Backend API Server
- Redis (queue/cache)
- PostgreSQL database
- Data Extractor Worker
- Report Creator Worker
- Measures Library (measures/*)
- Utilities (load_clauses, gitpull)
- External Data Sources (Customs API, Rosstat API, WTO API)
b. Relationships & data flow:
1. User → Frontend (HTTP request)
2. Frontend → Backend API (HTTP)
3. Backend checks Redis cache; if miss, enqueues tasks in Redis for data extraction
4. Data Extractor reads queue → fetches external data → writes to Postgres → notifies via Redis
5. Backend loads measure definitions via utilities/load_clauses → applies rules to data in Postgres
6. Backend enqueues report creation task → Report Creator reads from Redis → generates PDF → stores result (DB or file store)
7. Backend responds to Frontend with recommendations and report link
c. Architectural patterns:
- Separation of concerns: UI layer, API layer, worker layer, data layer
- Event‐driven via Redis message queues
- Pluggable rule engine: measures directory loaded at runtime
- Containerized microservices with Docker Compose
d. Key technologies:
- Python + Flask (frontend & backend)
- Redis (broker/cache)
- PostgreSQL (persistent storage)
- Docker & Docker Compose (container orchestration)
- PDF generation libraries (in report_creator)
- External HTTP APIs for data ingestion

- Clear, descriptive labels on every component
- Containers by Docker network or Compose project
- Notes on dynamic loading of rules from measures/*.json and *.py

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Services and Components
    UI["User Web Browser"]:::external
    subgraph "Frontend Service"
        FE_App["Frontend Flask App"]:::compute
        FE_Static["Static UI (index.html)"]:::compute
        FE_Start["Startup Script"]:::compute
    end
    subgraph "Backend Service"
        BE["Backend API Server"]:::compute
    end
    subgraph "Redis Broker/Cache"
        DS_R["Redis"]:::db
    end
    subgraph "PostgreSQL Database"
        DS_P["PostgreSQL"]:::db
    end
    subgraph "Workers"
        subgraph "Data Extractor"
            DE["Data Extractor Worker"]:::compute
        end
        subgraph "Report Creator"
            RC["Report Creator Worker"]:::compute
        end
    end
    subgraph "Measures Library"
        ML["Measures Library"]:::folder
    end
    subgraph "Utilities"
        U1["gitpull.py"]:::utility
        U2["load_clauses.py"]:::utility
    end
    subgraph "External Data Sources"
        EX1["Customs API"]:::external
        EX2["Rosstat API"]:::external
        EX3["WTO API"]:::external
    end

    %% Data Flows
    UI -->|HTTP| FE_App
    FE_App -->|HTTP| BE
    BE -->|Redis RQ| DS_R
    BE -->|SQL| DS_P
    BE -->|Load Rules| ML
    BE -->|Enqueue Report| DS_R
    DS_R -->|RQ| DE
    DE -->|REST| EX1
    DE -->|REST| EX2
    DE -->|REST| EX3
    DE -->|SQL| DS_P
    DE -->|Notify via Redis| DS_R
    BE -->|Apply Rules| DS_P
    BE -->|HTTP Response| FE_App
    DS_R -->|RQ| RC
    RC -->|Generate PDF| DS_P
    RC -->|Store Report| DS_P
    U1 --> ML
    U2 --> ML

    %% Click Events
    click FE_App "https://github.com/belashov641618/tradeshield/blob/main/frontend/app.py"
    click FE_Static "https://github.com/belashov641618/tradeshield/blob/main/frontend/index.html"
    click FE_Start "https://github.com/belashov641618/tradeshield/blob/main/frontend/start_all.sh"
    click BE "https://github.com/belashov641618/tradeshield/blob/main/backend/main.py"
    click DS_R "https://github.com/belashov641618/tradeshield/blob/main/redis/docker-compose.yml"
    click DS_P "https://github.com/belashov641618/tradeshield/blob/main/postgres/docker-compose.yml"
    click DS_P "https://github.com/belashov641618/tradeshield/blob/main/postgres/declarations/tables.py"
    click DS_P "https://github.com/belashov641618/tradeshield/blob/main/postgres/initialize.py"
    click ML "https://github.com/belashov641618/tradeshield/tree/main/measures/"
    click U1 "https://github.com/belashov641618/tradeshield/blob/main/utilities/gitpull.py"
    click U2 "https://github.com/belashov641618/tradeshield/blob/main/utilities/load_clauses.py"
    click DE "https://github.com/belashov641618/tradeshield/blob/main/workers/data_extractor/data_extractor.py"
    click DE "https://github.com/belashov641618/tradeshield/blob/main/workers/data_extractor/docker-compose.yml"
    click RC "https://github.com/belashov641618/tradeshield/blob/main/workers/report_creator/report_creator.py"
    click RC "https://github.com/belashov641618/tradeshield/blob/main/workers/report_creator/default.pdf"
    click RC "https://github.com/belashov641618/tradeshield/blob/main/workers/report_creator/docker-compose.yml"
    click BE "https://github.com/belashov641618/tradeshield/blob/main/backend/requirements.txt"
    click BE "https://github.com/belashov641618/tradeshield/blob/main/backend/docker-compose.yml"

    %% Styles
    classDef compute fill:#D0E8FF,stroke:#0366d6,color:#0366d6;
    classDef db fill:#DFFFE0,stroke:#28a745,color:#28a745;
    classDef external fill:#FFF0D0,stroke:#e36209,color:#e36209;
    classDef folder fill:#F0D0FF,stroke:#6f42c1,color:#6f42c1;
    classDef utility fill:#E8E8E8,stroke:#6a737d,color:#6a737d;
```
