# defog-ai/introspect architecture

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

- Interactive diagram: https://gitdiagram.com/defog-ai/introspect
- Repository: https://github.com/defog-ai/introspect

## Overview

##### Project Type & Purpose
- The project is a full-stack AI-driven application that performs “deep research” on structured data. It integrates data from databases, CSV/Excel files, and PDFs, and also pulls in external context via web searches.
- It uses an AI agent to recursively leverage several tool endpoints (e.g., text_to_sql, web_search, pdf_with_citations) alongside multiple language models (such as o3-mini, gemini-2.0-flash, claude-3-7-sonnet).

##### Main Components
a. Frontend Service:
- “frontend” directory which uses Next.js/React (files under pages, components, styles, etc.).
- This layer is responsible for the user interface, including pages for querying, authentication, file uploads, and administrative management.
b. Backend API:
- “backend” directory built on Python. This includes modules such as authentication routes, file upload routes, query data modules, oracle routes, and various utility modules.
- REST API endpoints (e.g., auth_routes, metadata_routes, query_data_routes) that interact with both the frontend and other system components.
c. AI Agent / Orchestration Component:
- Interactions with:
- The text_to_sql module (likely powered by the “o3-mini” model)
- The web_search module (using “gemini-2.0-flash”)
- The pdf_with_citations tool (using “claude-3-7-sonnet”)
d. Data Storage / Database Layer:
- Project’s support for various database connectors (e.g., PostgreSQL, MySQL, SQLite, BigQuery, etc.) as well as CSV/Excel file handling.
- A “datasets” component that holds sample SQL files and additional configuration files.
e. External Services:
- Connections indicating that the AI agent communicates with these services.
f. Docker & Deployment:
- A containerization layer that covers Docker Compose usage (with docker-compose.yaml and Dockerfiles for backend, agents, nginx, etc.).
- Deployment configuration, such as “nginx” for reverse proxy and the various Docker workflows.

##### Relationships & Data Flow
- From Frontend (UI in Next.js) → Backend API (via REST endpoints)
- Within the Backend, illustrate how various API endpoints interact with the AI orchestration tool.
- Data flow from the AI agent to external services (LLM APIs for text_to_sql, web search, PDF analysis).
- That the Docker orchestration ensures that both frontend and backend (as well as databases) are up-and-running, with appropriate configuration files managing the deployment.

##### Architectural Patterns / Design Principles
- Separation of concerns:
- Frontend presentation layer vs. Backend business logic.
- That the backend is separable into different modules (e.g., auth, query generation, file handling, Oracle-specific processes) which demonstrates a modular, layered design approach.
- Testing layers (unit and integration tests within the “backend/tests” and “frontend/tests”) if desired.

##### Extra Details & Noteworthy Points
- Testing and configuration files (like in “.github/workflows”, “docker-compose.yaml”, and various Dockerfiles) to highlight that the project follows a CI/CD and containerized deployment model.

## Diagram (Mermaid)

```mermaid
flowchart TD
    U("User"):::user

    F1("Frontend (Next.js UI)"):::frontend
    B1("Backend API (Python)"):::backend
    A1("AI Orchestrator (Tool Endpoints)"):::ai
    D1("Data Storage (Databases and Files)"):::storage

    subgraph "External LLM Services"
        E1("OpenAI LLM"):::external
        E2("Anthropic LLM"):::external
        E3("Gemini LLM"):::external
    end

    subgraph "Docker & Deployment"
        DC1("docker-compose.yaml"):::docker
        DC2("dockerfile.agents-nginx"):::docker
        DC3("dockerfile.agents-python-server"):::docker
        DC4("dockerfile.agents-python-server-export"):::docker
        DC5("nginx (configuration)"):::docker
        DC6("Docker Setup Files"):::docker
    end

    U --> F1
    F1 --> B1
    B1 --> A1
    B1 --> D1
    A1 -->|"text_to_sql_(o3-mini)"| E1
    A1 -->|"pdf_with_citations_(claude-3-7-sonnet)"| E2
    A1 -->|"web_search_(gemini-2.0-flash)"| E3
    DC1 -.-> F1
    DC1 -.-> B1
    DC1 -.-> D1

    click F1 "https://github.com/defog-ai/introspect/tree/main/frontend/"
    click B1 "https://github.com/defog-ai/introspect/tree/main/backend/"
    click A1 "https://github.com/defog-ai/introspect/tree/main/backend/tools/"
    click D1 "https://github.com/defog-ai/introspect/tree/main/datasets/"
    click DC1 "https://github.com/defog-ai/introspect/blob/main/docker-compose.yaml"
    click DC2 "https://github.com/defog-ai/introspect/blob/main/dockerfile.agents-nginx"
    click DC3 "https://github.com/defog-ai/introspect/blob/main/dockerfile.agents-python-server"
    click DC4 "https://github.com/defog-ai/introspect/blob/main/dockerfile.agents-python-server-export"
    click DC5 "https://github.com/defog-ai/introspect/tree/main/nginx/"
    click DC6 "https://github.com/defog-ai/introspect/tree/main/backend/docker-setup-files/"

    classDef frontend fill:#ADD8E6,stroke:#333,stroke-width:2px;
    classDef backend fill:#FFE4B5,stroke:#333,stroke-width:2px;
    classDef ai fill:#98FB98,stroke:#333,stroke-width:2px;
    classDef storage fill:#FFB6C1,stroke:#333,stroke-width:2px;
    classDef external fill:#FFFACD,stroke:#333,stroke-width:2px;
    classDef docker fill:#E0FFFF,stroke:#333,stroke-width:2px;
    classDef user fill:#D3D3D3,stroke:#333,stroke-width:2px;
```
