# aniketc068/ocspmonitorbot architecture

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

- Interactive diagram: https://gitdiagram.com/aniketc068/ocspmonitorbot
- Repository: https://github.com/aniketc068/ocspmonitorbot

## Overview

##### Project type and purpose
- This is a Python monolithic service exposing two main interfaces:
– A Telegram Bot using python-telegram-bot (async)
– A Flask REST API (`/api/certchecker` and `/cert-count`)
- It processes user uploads or API requests, parses certificates, checks OCSP/CRL status, blocks spam, and sends alerts.

##### Main architectural components
a. Client Interfaces
– Telegram Users & Groups
– HTTP Clients (curl, Postman, other services)
b. Bot Server
– main.py: application entry point
– imports.py: selects web server backend (Waitress or Gunicorn)
– handlers.py: Telegram update handlers (commands, file uploads)
– Flask app: route definitions for `/api/certchecker` and `/cert-count`
c. Business Logic Modules
– parse.py: certificate format detection & parsing
– cert_utils.py: OCSP/CRL checking routines, cryptography interactions
– block_utils.py: spam/user-warning/block logic
– config.py: environment variable management (bot token, chat IDs)
d. Data Storage
– JSON files in `data/`: blocked_users.json, spam_messages.json, user_warnings.json, counter.json, blocked_notices.json
e. Templates
– templates/index.html: optional web UI (if used)
f. External Dependencies
– Telegram Bot API
– OCSP responders (for real-time monitoring)
– CRL distribution points
– Python packages: Flask, python-telegram-bot, cryptography, lxml

##### Relationships and data flows
User → Telegram Bot API → handlers.py → parse.py / cert_utils.py → OCSP/CRL endpoints → handlers.py → Telegram Bot API → User
– block_utils.py invoked after invalid attempts
– Data read/write to JSON store for counters and blocks
Client → Flask `/api/certchecker` → parse.py / cert_utils.py → external OCSP/CRL → Flask → Client
Scheduled or long-polling in main.py for Capricorn .pem → cert_utils.py → on-failure alert via handlers.py → Telegram group
- Metrics endpoint:
Flask `/cert-count` → reads counter.json → returns JSON

##### Architectural patterns & design principles
- Modular layering: separation of interface (handlers/routes), domain logic (parse/cert_utils/block_utils), and data persistence (JSON files)
- Single process monolith: both Bot and API share the same codebase and runtime
- Externalization of configuration via ENV (config.py)
- Simple file-based storage, replaceable by a database if scaled

– Component boundaries (containers)
– Clear labels (module names, API endpoints, data files)
– Callouts for important Env vars (TELEGRAM_BOT_TOKEN, TELEGRAM_CHAT_ID, MONITOR_USER_ID)
– Annotations for scheduled monitoring vs on-demand requests

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Clients
    C_user["Telegram Users/Groups"]:::client
    C_http["HTTP Clients"]:::client

    %% Application Server
    subgraph "Application Server"
        A_main["main.py"]:::interface
        A_imports["imports.py"]:::interface
        A_handlers["handlers.py"]:::interface
        A_flask1["/api/certchecker (Flask Route)"]:::interface
        A_flask2["/cert-count (Flask Route)"]:::interface
    end

    %% Business Logic
    subgraph "Business Logic"
        B_parse["parse.py"]:::logic
        B_utils["cert_utils.py"]:::logic
        B_block["block_utils.py"]:::logic
        B_config["config.py"]:::logic
    end

    %% Data Layer
    subgraph "Data Layer"
        D_blocked["blocked_users.json"]:::storage
        D_spam["spam_messages.json"]:::storage
        D_warn["user_warnings.json"]:::storage
        D_count["counter.json"]:::storage
        D_notices["blocked_notices.json"]:::storage
    end

    %% Templates
    subgraph "Templates"
        T_ui["index.html"]:::interface
    end

    %% External Services
    subgraph "External Services"
        E_tg["Telegram Bot API"]:::external
        E_ocsp["OCSP Responders"]:::external
        E_crl["CRL Distribution Points"]:::external
        E_monitorpem["capricorn.pem"]:::external
    end

    %% Telegram Bot Flow
    C_user -->|"send/update"| E_tg
    E_tg -->|"deliver update"| A_handlers
    A_handlers -->|"parse cert"| B_parse
    A_handlers -->|"check status"| B_utils
    B_utils -->|"query OCSP/CRL"| E_ocsp
    B_utils -->|"query OCSP/CRL"| E_crl
    B_utils -->|"return result"| A_handlers
    A_handlers -->|"respond"| E_tg
    E_tg -->|"send message"| C_user

    A_handlers -->|"block logic"| B_block
    B_block -->|"update lists"| D_blocked
    B_block -->|"update lists"| D_spam
    B_block -->|"update lists"| D_warn
    B_block -->|"update lists"| D_notices

    %% HTTP REST Flow
    C_http -->|"POST /api/certchecker"| A_flask1
    A_flask1 -->|"parse cert"| B_parse
    A_flask1 -->|"check status"| B_utils
    B_utils -->|"query OCSP/CRL"| E_ocsp
    B_utils -->|"query OCSP/CRL"| E_crl
    B_utils -->|"return result"| A_flask1
    A_flask1 -->|"response JSON"| C_http

    C_http -->|"GET /cert-count"| A_flask2
    A_flask2 -->|"read counter"| D_count
    A_flask2 -->|"return count"| C_http

    %% Monitoring Flow
    E_monitorpem -->|"scheduled check"| B_utils
    B_utils -->|"on failure alert"| A_handlers
    A_handlers -->|"notify group"| E_tg

    %% Configuration
    A_main -->|"uses"| B_config
    A_imports -->|"uses"| B_config

    %% Click Events
    click A_main "https://github.com/aniketc068/ocspmonitorbot/blob/main/main.py"
    click A_imports "https://github.com/aniketc068/ocspmonitorbot/blob/main/imports.py"
    click A_handlers "https://github.com/aniketc068/ocspmonitorbot/blob/main/handlers.py"
    click B_parse "https://github.com/aniketc068/ocspmonitorbot/blob/main/parse.py"
    click B_utils "https://github.com/aniketc068/ocspmonitorbot/blob/main/cert_utils.py"
    click B_block "https://github.com/aniketc068/ocspmonitorbot/blob/main/block_utils.py"
    click B_config "https://github.com/aniketc068/ocspmonitorbot/blob/main/config.py"
    click D_blocked "https://github.com/aniketc068/ocspmonitorbot/blob/main/data/blocked_users.json"
    click D_spam "https://github.com/aniketc068/ocspmonitorbot/blob/main/data/spam_messages.json"
    click D_warn "https://github.com/aniketc068/ocspmonitorbot/blob/main/data/user_warnings.json"
    click D_count "https://github.com/aniketc068/ocspmonitorbot/blob/main/data/counter.json"
    click D_notices "https://github.com/aniketc068/ocspmonitorbot/blob/main/data/blocked_notices.json"
    click E_monitorpem "https://github.com/aniketc068/ocspmonitorbot/blob/main/pem/capricorn.pem"
    click T_ui "https://github.com/aniketc068/ocspmonitorbot/blob/main/templates/index.html"

    %% Styles
    classDef interface fill:#add8e6,stroke:#000;
    classDef logic fill:#ffff99,stroke:#000;
    classDef storage fill:#d3d3d3,stroke:#000;
    classDef external fill:#98fb98,stroke:#000;
    classDef client fill:#ffe4e1,stroke:#000;
```
