# koldbringer/gobeklitepe architecture

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

- Interactive diagram: https://gitdiagram.com/koldbringer/gobeklitepe
- Repository: https://github.com/koldbringer/gobeklitepe

## Overview

##### Project Type and Purpose
- This is a full-stack CRM/ERP web application specialized for HVAC companies.
- Frontend: Streamlit PWA running in a Docker container (or as a managed Fly.io app).
- Backend: Python “modular monolith” with pluggable service modules and gRPC microservices (including a Rust-based quantum engine).
- Data Stores: PostgreSQL (primary relational DB), Supabase (auth, storage), Qdrant (vector DB for embeddings), plus file-based OCR/DMS.
- External Services: ElevenLabs TTS API, SMTP/email gateways, SMS/voice gateways.

A. Frontend Layer
- Streamlit (app.py, components/, pages/)
- HTTP/WS endpoints for health checks, WebSocket tests
B. Backend Application Layer
- Core Python process (app.py imports config.py, utils/, services/)
- Business-logic modules in services/ (communication_service, email_service, voice_communication, quantum_communication)
- gRPC server (grpc_server.py), gRPC client stubs (grpc_client.py, generate_grpc.py)
C. Quantum Engine Microservice
- Rust code under przestrzeń_kwantowa/ compiled as a separate service
- Exposes gRPC interface defined in protos/service.proto
D. Persistence Layer
- PostgreSQL (utils/db.py, schemas in przestrzeń_kwantowa/schemat_bazy_danych.sql)
- Supabase client (utils/supabase_client.py)
- Qdrant vector store connector (src/qdrant_connector.rs and Python wrappers)
- OCR/DMS storage (local files or S3 via Supabase)
E. External Integrations
- ElevenLabs TTS (voice_interface)
- SMTP/email (templates/email/*.html)
- SMS/telephony APIs (voice interface, transcription services)
F. Infrastructure & Deployment
- NGINX reverse proxy (nginx/*.conf)
- Docker (Dockerfile via build.sh, entrypoint.sh)
- Fly.io (fly.toml), Heroku (Procfile)
- CI/CD scripts (deploy.sh, build_context.sh)
- Health checks (health_check.py, network_health_check.py)

##### Relationships & Data Flows
- The user’s browser/mobile calls the Streamlit frontend (HTTP/WS).
- Frontend invokes backend functions directly (in-process calls) or via gRPC to the quantum microservice.
- Backend modules call:
- PostgreSQL for transactional data (clients, orders, inventory)
- Qdrant for vector searches (quantum-inspired prioritization)
- Supabase for auth and file storage (DMS/OCR assets)
- External APIs (ElevenLabs, SMTP, SMS gateways).
- Rust quantum service computes entanglement scores and returns results over gRPC.
- NGINX sits in front to route traffic, terminate TLS, and serve static files (robots.txt, health.json).

##### Architectural Patterns & Principles
- Modular Monolith / Microservices hybrid
- Layered architecture (UI → Services → Data)
- Clean separation between:
- Presentation (Streamlit UI)
- Business Logic (services/)
- Infrastructure (utils/, networking, deployment scripts)
- Use of Protobuf/gRPC for inter-service contracts (language-agnostic quantum engine)
- Config-driven (config.py, .env templates) to toggle features (quantum, voice)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend Layer"
        A_streamlit["Streamlit App"]:::ui
        A_components["UI Components"]:::ui
        A_pages["Streamlit Pages"]:::ui
    end

    %% Backend Application Layer
    subgraph "Backend Application Layer"
        B_core["Core Process"]:::backend
        B_config["config.py"]:::backend
        B_services["Services Module"]:::backend
        B_grpc_server["grpc_server.py"]:::backend
        B_grpc_client["grpc_client.py"]:::backend
        B_generate["generate_grpc.py"]:::backend
        B_utils["Utils"]:::backend
        B_db_util["db.py"]:::backend
        B_supabase_util["supabase_client.py"]:::backend
        B_health_util["health_check.py"]:::backend
    end

    %% Quantum Engine Microservice
    subgraph "Quantum Engine Microservice"
        Q_service["Rust Quantum Service"]:::rust
        Q_proto["Protobuf Definition"]:::backend
    end

    %% Persistence Layer
    subgraph "Persistence Layer"
        DB_pg["PostgreSQL"]:::db
        DB_supabase["Supabase Auth/Storage"]:::db
        DB_qdrant["Qdrant Vector DB"]:::db
        DB_ocr["OCR/DMS Storage"]:::db
    end

    %% External Integrations
    subgraph "External Integrations"
        EI_tts["ElevenLabs TTS API"]:::external
        EI_email["SMTP/Email Gateway"]:::external
        EI_sms["SMS/Voice Gateways"]:::external
    end

    %% Infrastructure & Deployment
    subgraph "Infrastructure & Deployment"
        I_nginx["NGINX Reverse Proxy"]:::infra
        I_docker["Docker & Entrypoints"]:::infra
        I_platform["Fly.io / Heroku"]:::infra
        I_cicd["CI/CD & Scripts"]:::infra
        I_healthnet["Network Health Checks"]:::infra
    end

    %% Connections
    User["User (Browser/Mobile)"]:::external
    User -->|HTTP/WS| A_streamlit

    A_streamlit -->|Function Calls / gRPC| B_core
    A_components -->|Imported Modules| A_streamlit
    A_pages -->|Renders| A_streamlit

    B_core -->|loads| B_config
    B_core -->|calls| B_services
    B_core -->|uses| B_utils
    B_core -->|hosts| B_grpc_server
    B_core -->|invokes| B_grpc_client
    B_core -->|generates| B_generate

    B_services -->|SQL| DB_pg
    B_services -->|Vector Search| DB_qdrant
    B_services -->|Auth/Storage| DB_supabase
    B_services -->|File Storage| DB_ocr
    B_services -->|TTS| EI_tts
    B_services -->|Email| EI_email
    B_services -->|SMS/Voice| EI_sms

    B_grpc_client -->|gRPC| Q_service
    Q_service -->|defined in| Q_proto

    I_nginx -->|routes| A_streamlit
    I_nginx -->|routes| B_core
    I_docker -->|containers| A_streamlit
    I_docker -->|containers| B_core
    I_platform -->|deploys| I_docker
    I_cicd -->|deploys| I_platform
    I_healthnet -->|HTTP/WS| A_streamlit

    %% Click Events
    click A_streamlit "https://github.com/koldbringer/gobeklitepe/blob/main/app.py"
    click A_components "https://github.com/koldbringer/gobeklitepe/tree/main/components/"
    click A_pages "https://github.com/koldbringer/gobeklitepe/tree/main/pages/"
    click B_config "https://github.com/koldbringer/gobeklitepe/blob/main/config.py"
    click B_services "https://github.com/koldbringer/gobeklitepe/tree/main/services/"
    click B_grpc_server "https://github.com/koldbringer/gobeklitepe/blob/main/grpc_server.py"
    click B_grpc_client "https://github.com/koldbringer/gobeklitepe/blob/main/grpc_client.py"
    click B_generate "https://github.com/koldbringer/gobeklitepe/blob/main/generate_grpc.py"
    click B_db_util "https://github.com/koldbringer/gobeklitepe/blob/main/utils/db.py"
    click B_supabase_util "https://github.com/koldbringer/gobeklitepe/blob/main/utils/supabase_client.py"
    click B_health_util "https://github.com/koldbringer/gobeklitepe/blob/main/utils/health_check.py"
    click Q_proto "https://github.com/koldbringer/gobeklitepe/blob/main/protos/service.proto"
    click Q_service "https://github.com/koldbringer/gobeklitepe/tree/main/przestrzeń_kwantowa/"
    click DB_qdrant "https://github.com/koldbringer/gobeklitepe/blob/main/przestrzeń_kwantowa/src/qdrant_connector.rs"
    click DB_ocr "https://github.com/koldbringer/gobeklitepe/blob/main/przestrzeń_kwantowa/schemat_bazy_danych.sql"

    %% Styles
    classDef ui fill:#AEDFF7,stroke:#333,stroke-width:1px;
    classDef backend fill:#C6F5D4,stroke:#333,stroke-width:1px;
    classDef rust fill:#DFF7AE,stroke:#333,stroke-width:1px;
    classDef db fill:#F5D6C6,stroke:#333,stroke-width:1px;
    classDef external fill:#F7C6C6,stroke:#333,stroke-width:1px;
    classDef infra fill:#E0E0E0,stroke:#333,stroke-width:1px;
```
