# cassio-tieres/validacrp architecture

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

- Interactive diagram: https://gitdiagram.com/cassio-tieres/validacrp
- Repository: https://github.com/cassio-tieres/validacrp

## Overview

##### Project Type and Purpose
- ValidaCRP is a Python-based Telegram bot (an AI agent) that lets Secretariat users or psychologists validate a CRP number via a chat interface.
- It uses OCR (Pytesseract), audio processing, LangChain for AI orchestration, and MongoDB to store or cache request data.

##### File Structure
- Top-level scripts & configs:
- main.py → bot entrypoint
- .env-exemplo / requirements.txt → environment & deps
- readme.md → project overview
- Directories:
- functions/ → business logic modules (genAI setup, OCR, audio processing, Telegram config)
- database/ → db.py (MongoDB connection and data access)
- prompt/ → Markdown instructions passed to the LLM
- No heavy front-end; it’s a single service (microservice) that integrates APIs and external scraping.

##### README for Additional Insights
- Tech stack: Python, LangChain, MongoDB, Pytesseract, Telegram API
- Use cases: Text and audio validation requests (audio support is planned/backlog)
- External dependency: scrapes https://cadastro.crp.org.br for CRP data.

a. Main Components to Represent
1. Telegram Client (User)
2. Telegram Bot API (external service)
3. Bot Application (your code):
- Entrypoint (main.py)
- Telegram Config Module
- Request Router / Controller
- Business Logic Modules (OCR, audio processor, text handler)
- LangChain Orchestrator (genai_config + prompt templates)
- Database Layer (MongoDB via database/db.py)
4. External CRP Website (HTTP scraper)
5. Data Store: MongoDB
6. Auxiliary: Tesseract Engine
b. Relationships & Data Flows
- User → Telegram API → Bot Application (Webhook or Polling)
- Bot App:
– Routes incoming message to either text handler, OCR pipeline, or audio pipeline
– OCR Pipeline calls Tesseract engine → extracts text → passes to LangChain
– Audio Pipeline calls speech-to-text → passes to LangChain
– LangChain orchestrates prompt (from prompt/*.md) + extracted text → generates validation request
– Bot App scrapes CRP site (HTTP client) → receives raw CRP data
– Bot App stores/fetches previous lookups in MongoDB
– Bot App aggregates results → Telegram API → returns message to User
c. Architectural Patterns & Principles
- Single Responsibility: each module in functions/ handles one concern
- Pipeline/Chain of Responsibility: text, OCR, audio pipelines feed into a common AI orchestrator
- External Integration Layer: clear boundary between your code and external services (Telegram, CRP Website, Tesseract, MongoDB)
d. Relevant Technologies & Libraries
- Python runtime
- python-telegram-bot (or equivalent wrapper)
- LangChain for prompt management
- Pytesseract + Tesseract engine for OCR
- Speech-to-text library (for future audio)
- Requests or HTTPX for web scraping
- pymongo for MongoDB access

##### Final Advice
- Be as granular as your audience needs—showing each function module is fine if they care about low-level plumbing. Otherwise, group them into “OCR Service,” “Audio Service,” etc.
- Flow from user input to final Telegram message is unbroken and clearly annotated.

## Diagram (Mermaid)

```mermaid
graph TB
    %% External Entities
    User["User"]:::external
    TelegramAPI["Telegram Bot API"]:::external

    %% Bot Application Entry
    User -->|sends message| TelegramAPI
    TelegramAPI -->|"webhook/poll"| Main["Entrypoint\nmain.py"]:::core
    click Main "https://github.com/cassio-tieres/validacrp/blob/main/main.py"

    subgraph "Bot Application"
        Main
        TelConf["Telegram Config\nfunctions/telegram_config.py"]:::core
        Router["Request Router\n(message handlers)"]:::core
        OCR["OCR Pipeline\nfunctions/ocr.py"]:::pipeline
        Audio["Audio Pipeline\nfunctions/processa_audios.py"]:::pipeline
        LangChain["LangChain Orchestrator\nfunctions/genai_config.py"]:::core
        Prompt1["Prompt Templates:\ninstrucoes.md"]:::docs
        Prompt2["Prompt Templates:\ninterprete_dados_da_imagem.md"]:::docs
        DB["Database Layer\n(database/db.py)"]:::datastore
    end

    TelegramAPI -->|"routes to"| TelConf
    TelConf -->|initializes| Router

    Router -->|"text message"| LangChain
    Router -->|"image message"| OCR
    Router -->|"audio message"| Audio

    OCR -->|"extracted text"| LangChain
    Audio -->|"STT text"| LangChain

    LangChain -->|"uses prompts"| Prompt1
    LangChain -->|"uses prompts"| Prompt2

    LangChain -->|"scrape CRP site"| CRP
    CRP["CRP HTTP Endpoint"]:::external
    click OCR "https://github.com/cassio-tieres/validacrp/blob/main/functions/ocr.py"
    click Audio "https://github.com/cassio-tieres/validacrp/blob/main/functions/processa_audios.py"
    click LangChain "https://github.com/cassio-tieres/validacrp/blob/main/functions/genai_config.py"
    click Prompt1 "https://github.com/cassio-tieres/validacrp/blob/main/prompt/instrucoes.md"
    click Prompt2 "https://github.com/cassio-tieres/validacrp/blob/main/prompt/interprete_dados_da_imagem.md"

    LangChain -->|"store/fetch cache"| DB
    DB -->|"data"| LangChain
    click DB "https://github.com/cassio-tieres/validacrp/blob/main/database/db.py"

    LangChain -->|"response text"| Router
    Router -->|"send response"| TelegramAPI
    TelegramAPI -->|"delivers"| User

    %% External Services & Engines
    Tesseract["Tesseract Engine"]:::datastore
    click .env "https://github.com/cassio-tieres/validacrp/blob/main/.env-exemplo"
    click req "https://github.com/cassio-tieres/validacrp/blob/main/requirements.txt"
    click doc "https://github.com/cassio-tieres/validacrp/blob/main/readme.md"

    %% Project Files
    subgraph "Project Files"
        Env[".env-exemplo"]:::docs
        Req["requirements.txt"]:::docs
        Doc["readme.md"]:::docs
    end

    %% Class Definitions
    classDef external fill:#f9f,stroke:#333,stroke-width:1px
    classDef core fill:#bbf,stroke:#333,stroke-width:1px
    classDef pipeline fill:#bfb,stroke:#333,stroke-width:1px
    classDef datastore fill:#fbf,stroke:#333,stroke-width:1px
    classDef docs fill:#ffd,stroke:#333,stroke-width:1px
```
