# bertughas123/normvision architecture

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

- Interactive diagram: https://gitdiagram.com/bertughas123/normvision
- Repository: https://github.com/bertughas123/normvision

## Overview

##### Project type and purpose
- NormVision is a data-processing pipeline rather than a traditional full-stack web app. It ingests unstructured PDF visit reports, applies NLP/ML/AI to extract and normalize fields, computes KPIs, then outputs structured reports and synchronizes with a CRM.

##### File structure
- Top-level “extractor/” modules handle all stages of raw PDF → text → normalized data:
- pdf_reader.py → notlar_parser.py → sections.py → normalize.py → schema.py → llm_fill.py → campaigns.py
- “analyzer/” modules compute financial and sales KPIs.
- “bridge/” layer pushes results into a CRM (sales_visit_bridge.py).
- Orchestrator scripts (runner_step1.py, runner_batch.py, runner_weekly.py, runner_monthly.py) coordinate flows for single, bulk, weekly, and monthly runs.
- Outputs land in Reports/ as CSV/Markdown.
- External dependencies: Google Gemini AI (via llm_fill), PyMuPDF/pdfplumber/pytesseract for PDF/OCR.

##### Extract insights from the README
- Key feature areas map cleanly to modules: extraction, AI-powered completion, KPI analysis, campaign tracking, report export, CRM sync.
- The README emphasizes a modular pipeline that can be run in different modes (step1, batch, weekly, monthly).

##### Main components
a. Input Layer
- PDF Source (single or directory)
b. Extraction Layer
- PDF Reader
- Parser & Section Splitter
- Normalizer & Schema Builder
- AI Completion (Gemini LLM)
- Campaign Extractor
c. Analysis Layer
- Financial Analysis Module
- Sales Performance Module
d. Integration Layer
- CRM Bridge (SalesVisitBridge)
e. Orchestration Layer
- Runners (step1, batch, weekly, monthly)
f. Output Layer
- Report Generator (CSV, Markdown)
- Reports/ Directory
g. External Services
- Google Gemini AI
- CRM API

##### Relationships and data flow
- Runners invoke the Extraction Layer in the correct order.
- Extracted & normalized data flows into Analysis Layer.
- Analysis results either feed into the Report Generator or into the CRM Bridge.
- Reports are written to disk; CRM Bridge calls external CRM API.

##### Architectural patterns and principles
- Layered pipeline: clear separation of concerns (extract → analyze → publish).
- Modular design: each module does one job and can be tested independently.
- Orchestration vs. step-function: runners encapsulate scheduling logic.

##### Relevant technologies to annotate
- Python 3.9+ (core language)
- PyMuPDF/pdfplumber/pytesseract (PDF & OCR)
- Google Generative AI (Gemini API)
- pandas / CSV / Markdown for outputs
- CRM SDK (used in bridge)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Orchestration Layer
    subgraph "Orchestration Layer"
        direction TB
        r1["Single-step Runner"]:::orchestration
        r2["Bulk Runner"]:::orchestration
        r3["Weekly Runner"]:::orchestration
        r4["Monthly Runner"]:::orchestration
    end

    %% Extraction Layer
    subgraph "Extraction Layer"
        direction TB
        pr["PDF Reader"]:::extraction
        np["Parser"]:::extraction
        ss["Section Splitter"]:::extraction
        no["Normalizer"]:::extraction
        sb["Schema Builder"]:::extraction
        ai["LLM Completion"]:::extraction
        cp["Campaign Extractor"]:::extraction
    end

    %% Analysis Layer
    subgraph "Analysis Layer"
        direction TB
        fa["Financial Analysis"]:::analysis
        sp["Sales Performance"]:::analysis
    end

    %% Integration Layer
    subgraph "Integration Layer"
        direction TB
        crm["CRM Bridge"]:::integration
    end

    %% Output Layer
    subgraph "Output Layer"
        direction TB
        rg["Report Generator"]:::output
        ds["Reports/ Directory"]:::output
    end

    %% Resources
    subgraph "Resources"
        direction TB
        cfg[".env.example"]:::resource
        doc["README.md"]:::resource
    end

    %% External Services
    subgraph "External Services"
        direction TB
        ext1["Google Gemini AI"]:::external
        ext2["CRM API"]:::external
    end

    %% Connections
    r1 --> pr
    r2 --> pr
    r3 --> pr
    r4 --> pr
    pr --> np --> ss --> no --> sb --> ai --> cp
    cp --> fa
    cp --> sp
    fa --> rg
    sp --> rg
    sp --> crm
    rg --> ds
    crm --> ext2
    ai --> ext1

    %% Click Events
    click pr "https://github.com/bertughas123/normvision/blob/main/extractor/pdf_reader.py"
    click np "https://github.com/bertughas123/normvision/blob/main/extractor/notlar_parser.py"
    click ss "https://github.com/bertughas123/normvision/blob/main/extractor/sections.py"
    click no "https://github.com/bertughas123/normvision/blob/main/extractor/normalize.py"
    click sb "https://github.com/bertughas123/normvision/blob/main/extractor/schema.py"
    click ai "https://github.com/bertughas123/normvision/blob/main/extractor/llm_fill.py"
    click cp "https://github.com/bertughas123/normvision/blob/main/extractor/campaigns.py"
    click fa "https://github.com/bertughas123/normvision/blob/main/analyzer/financial_analysis.py"
    click sp "https://github.com/bertughas123/normvision/blob/main/analyzer/sales_performance.py"
    click crm "https://github.com/bertughas123/normvision/blob/main/bridge/sales_visit_bridge.py"
    click r1 "https://github.com/bertughas123/normvision/blob/main/runner_step1.py"
    click r2 "https://github.com/bertughas123/normvision/blob/main/runner_batch.py"
    click r3 "https://github.com/bertughas123/normvision/blob/main/runner_weekly.py"
    click r4 "https://github.com/bertughas123/normvision/blob/main/runner_monthly.py"
    click cfg "https://github.com/bertughas123/normvision/blob/main/.env.example"
    click doc "https://github.com/bertughas123/normvision/blob/main/README.md"

    %% Styles
    classDef orchestration fill:#f39c12,stroke:#333,stroke-width:1px
    classDef extraction fill:#3498db,stroke:#333,stroke-width:1px
    classDef analysis fill:#2ecc71,stroke:#333,stroke-width:1px
    classDef integration fill:#9b59b6,stroke:#333,stroke-width:1px
    classDef output fill:#f1c40f,stroke:#333,stroke-width:1px
    classDef external fill:#e74c3c,stroke:#333,stroke-width:1px
    classDef resource fill:#95a5a6,stroke:#333,stroke-width:1px
```
