# ggyll/condo_gpt architecture

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

- Interactive diagram: https://gitdiagram.com/ggyll/condo_gpt
- Repository: https://github.com/ggyll/condo_gpt

## Overview

##### Project type and purpose
- Project Type: Full-stack web application with AI/LLM integration

##### File structure
Top-level files and directories:
- server.py – Flask web server (HTTP routing, request/response)
- main.py – Core orchestration: receives user query, dispatches to LLM agent and tools, formats output
- tools.py – Utility functions: dynamic SQL builder, database access layer, Google Maps API client
- prefix.py – System-message templates for GPT prompting
- boilerplate.py – Common code for rendering maps (Chart.js wrappers), PDF generation (ReportLab)
- templates/index.html – Frontend UI (single-page form, chart/map placeholders)
- static/ – Static assets (JS for Chart.js, CSS, images)
- sample_db.sql – Schema + sample data for PostgreSQL
- requirements.txt – Dependencies (Flask, psycopg2, LangChain, OpenAI, Chart.js shipped via CDN)

##### README for additional insights
- Stack: Python 3.x, Flask, PostgreSQL, LangChain/LangGraph, OpenAI API, Google Maps API, Chart.js, ReportLab
- Features: NLP interface → dynamic SQL → DB queries → data visualization → PDF reporting
- Workflow hints: server.py calls main.py; main.py loads prefix.py; uses tools.py; boilerplate for charts & PDFs

a. Main components:
1. User Interface (Browser)
– HTML/CSS/JS (index.html + static)
– Chart.js for frontend graphs
2. Flask Backend (server.py)
– HTTP endpoints (/, /query, /report, /clear)
3. Application Logic (main.py + prefix.py + examples.py + sandbox.py)
– Natural language parsing & prompt construction
– LangChain/LangGraph agent orchestration
4. Tools Layer (tools.py)
– Database client (psycopg2/PostgreSQL)
– Dynamic SQL generator
– Google Maps API client
5. Visualization & Reporting (boilerplate.py)
– Chart.js config helpers (server-side JSON for frontend)
– ReportLab PDF generator
6. Data Store (PostgreSQL)
– Condo data tables (from sample_db.sql)
7. External Services
– OpenAI API (GPT model calls)
– Google Maps/Places API

b. Relationships & data flows:
- User submits question (Browser → Flask)
- Flask → main.py: apply prefix.py, form prompt, call LangChain agent
- LangChain agent → OpenAI API → returns SQL or high-level answer
- If SQL returned: main.py → tools.py → PostgreSQL → result set
- For location queries: tools.py → Google Maps API → geocoding/directions
- main.py → boilerplate.py → chart config or PDF buffer
- Flask → Browser: JSON payload for Chart.js or PDF file

c. Architectural patterns & principles:
- Layered architecture: Presentation (UI) → Application (Flask + orchestration) → Tools/Service → Data
- Use of agent pattern (LangChain) to encapsulate LLM interactions
- Separation of concerns: prompt templates (prefix.py) vs. business logic (main.py) vs. external integrations (tools.py)

d. Key technologies:
- Flask (web server)
- LangChain & LangGraph (agent framework)
- OpenAI GPT (LLM)
- psycopg2/PostgreSQL (database)
- Google Maps API (geocoding/directions)
- Chart.js (front-end visualization)
- ReportLab (PDF generation)

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Presentation Layer"
        direction TB
        UI["User Interface<br/>(templates/index.html<br/>static/)"]:::presentation
    end

    subgraph "Application Layer"
        direction TB
        Flask["Flask Server<br/>(server.py)"]:::application
        Main["Core Orchestration<br/>(main.py)"]:::application
        Prefix["Prompt Templates<br/>(prefix.py)"]:::application
        Examples["Example Workflows<br/>(examples.py)"]:::application
        Sandbox["Sandbox Utilities<br/>(sandbox.py)"]:::application
        Agent["LangChain Agent"]:::application
    end

    subgraph "Tools & Services"
        direction TB
        Tools["Tools Layer<br/>(tools.py)"]:::service
        Boiler["Visualization & Reporting<br/>(boilerplate.py)"]:::service
        DB["PostgreSQL<br/>(sample_db.sql)"]:::service
        Req["Dependencies<br/>(requirements.txt)"]:::service
    end

    subgraph "External Services"
        direction TB
        OpenAI["OpenAI API"]:::external
        Maps["Google Maps API"]:::external
    end

    UI -->|"User submits query"| Flask
    Flask -->|"HTTP request"| Main
    Main -->|"load templates"| Prefix
    Main -->|"invoke agent"| Agent
    Agent -->|"LLM call"| OpenAI
    OpenAI -->|"response"| Agent
    Agent -->|"parsed output"| Main
    Main -->|"SQL Query"| Tools
    Tools -->|"execute query"| DB
    Tools -->|"geocode/directions"| Maps
    Main -->|"Chart/PDF Request"| Boiler
    Boiler -->|"render output"| Flask
    Flask -->|"JSON/PDF response"| UI

    click UI "https://github.com/ggyll/condo_gpt/blob/main/templates/index.html"
    click UI "https://github.com/ggyll/condo_gpt/tree/main/static/"
    click Flask "https://github.com/ggyll/condo_gpt/blob/main/server.py"
    click Main "https://github.com/ggyll/condo_gpt/blob/main/main.py"
    click Prefix "https://github.com/ggyll/condo_gpt/blob/main/prefix.py"
    click Examples "https://github.com/ggyll/condo_gpt/blob/main/examples.py"
    click Sandbox "https://github.com/ggyll/condo_gpt/blob/main/sandbox.py"
    click Tools "https://github.com/ggyll/condo_gpt/blob/main/tools.py"
    click Boiler "https://github.com/ggyll/condo_gpt/blob/main/boilerplate.py"
    click DB "https://github.com/ggyll/condo_gpt/blob/main/sample_db.sql"
    click Req "https://github.com/ggyll/condo_gpt/blob/main/requirements.txt"

    classDef presentation fill:#D0E6FF,stroke:#333,stroke-width:1px;
    classDef application fill:#D0F2D0,stroke:#333,stroke-width:1px;
    classDef service fill:#FFE6A0,stroke:#333,stroke-width:1px;
    classDef external fill:#F0F0F0,stroke:#333,stroke-width:1px;
```
