# mozartmarin/hotel_ia_poc architecture

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

- Interactive diagram: https://gitdiagram.com/mozartmarin/hotel_ia_poc
- Repository: https://github.com/mozartmarin/hotel_ia_poc

## Overview

##### Project type and purpose
- This is a full-stack MVP: a conversational AI agent (chatbot) tailored for the hotel industry.
- It uses a Streamlit front-end, an LLM (Mistral) hosted by Ollama for natural-language processing, and PostgreSQL as its data store for reservations and occupancy metrics.

##### File structure
- Top-level directories:
- app/ – core application logic (initialization, health-check)
- db/ – database connection module
- frontend/ – Streamlit app entrypoint (agent.py)
- rag/ – prompt templates for retrieval-augmented generation
- tools/ – auxiliary logic (e.g., building SQL queries for perguntas.py)
- static/ – images, CSS, UI assets
- Requirements files indicate Python dependencies and a “full” variant for development.
- No separate microservices—this is a monolith but with clear layering.

##### Additional README insights
- The system flow is: user → Streamlit UI → agent.py → RAG pipeline → Ollama LLM → database (via SQL) → response.
- Dependencies: Python 3.10+, Ollama (local LLM), PostgreSQL.

a. Components
1. User (browser)
2. Streamlit front-end (frontend/agent.py + static UI)
3. Application layer (app/__init__.py, test_connection.py)
4. RAG prompt layer (rag/prompt.txt)
5. Tools module (tools/perguntas.py) for SQL generation
6. Database layer (PostgreSQL via db/connection.py)
7. LLM service (Ollama hosting the mistral model)
b. Relationships & data flow
- Browser sends HTTP requests to Streamlit server.
- Streamlit invokes agent.py, which:
- Reads user query
- Calls tools/perguntas to construct or parse DB queries
- Optionally queries PostgreSQL via db/connection.py
- Loads prompt template from rag/prompt.txt
- Sends combined prompt + context to Ollama LLM REST/Socket API
- Receives LLM-generated answer
- Renders response in the front-end
c. Architectural patterns
- Layered Monolith: separation into UI, application logic, data access, external AI service.
- RAG (Retrieval-Augmented Generation) for dynamic data fetching.
d. Key technologies
- Python 3.10, Streamlit, Ollama (Mistral model), psycopg2/SQLAlchemy (implied), PostgreSQL.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User Interface Layer
    subgraph "User Interface"
        User["User (Browser)"]:::user
        UI["Streamlit UI"]:::ui
        Static["Static Assets"]:::ui
    end

    %% Application Layer
    subgraph "Application Layer"
        Init["App Init"]:::app
        Test["Health Check"]:::app
    end

    %% Logic Layer
    subgraph "Logic Layer"
        Tools["Tools/Query Builder"]:::logic
        RAG["RAG Prompt"]:::logic
    end

    %% Data Layer
    subgraph "Data Layer"
        DBConn["DB Connection Module"]:::db
        DB["PostgreSQL DB"]:::db
    end

    %% External Service
    LLM["Ollama LLM (Mistral)"]:::ext

    %% Connections
    User -->|"HTTP"| UI
    UI -->|"invoke"| Init
    UI -->|"serve assets"| Static
    Init -->|"use health check"| Test
    Init -->|"call"| Tools
    Tools -->|"psycopg2/SQL"| DBConn
    DBConn -->|"connect"| DB
    Init -->|"load template"| RAG
    RAG -->|"HTTP/WebSocket"| LLM
    LLM -->|"response"| Init
    Init -->|"render"| UI
    UI -->|"display"| User

    %% Click Events
    click UI "https://github.com/mozartmarin/hotel_ia_poc/blob/main/frontend/agent.py"
    click Static "https://github.com/mozartmarin/hotel_ia_poc/tree/main/static/"
    click Init "https://github.com/mozartmarin/hotel_ia_poc/blob/main/app/__init__.py"
    click Test "https://github.com/mozartmarin/hotel_ia_poc/blob/main/app/test_connection.py"
    click RAG "https://github.com/mozartmarin/hotel_ia_poc/blob/main/rag/prompt.txt"
    click Tools "https://github.com/mozartmarin/hotel_ia_poc/blob/main/tools/perguntas.py"
    click DBConn "https://github.com/mozartmarin/hotel_ia_poc/blob/main/db/connection.py"

    %% Styles
    classDef user fill:#D0E6FA,stroke:#2B82D0,color:#2B82D0;
    classDef ui fill:#AEDDFF,stroke:#4AAFE3,color:#0A3B5D;
    classDef app fill:#D5F5E3,stroke:#28B463,color:#145A32;
    classDef logic fill:#E8F8F5,stroke:#17A589,color:#0E6251;
    classDef db fill:#FCF3CF,stroke:#F1C40F,color:#7D6608;
    classDef ext fill:#F5EEF8,stroke:#BB8FCE,color:#6C3483;
```
