# modlee-ai/uconn_modlee_ai_ml_club_hackathons architecture

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

- Interactive diagram: https://gitdiagram.com/modlee-ai/uconn_modlee_ai_ml_club_hackathons
- Repository: https://github.com/modlee-ai/uconn_modlee_ai_ml_club_hackathons

## Overview

##### Project type and purpose
- This is a **starter template / sample code repository** for the UCONN Modlee AI/ML Club Hackathon.
- Its purpose is to demonstrate how to build AI-agent-based applications by calling the **Modlee Agents API**.
- It provides example “client” scripts (in Python) that show how to invoke various agents:
- Core document agents (blog, social media)
- Data operator agents (REST connectors, SQL queries)

##### File structure
- Top-level:
- README.md – instructions for the hackathon and how to use the samples
- examples/ – all of the runnable client-side code samples
- modlee_agents_wiki.md – extended documentation link
- examples/core_docs_agent:
- blog_example.py – shows how to generate blog posts
- social_example.py – shows how to generate social posts
- examples/data_operator_agent:
- rest/ – subfolders for REST API connectors
– google_places_api, news_api, newsdata_api (each has docs, schema, Python examples, tests)
- sql/ – an SQLite mock database plus a Python example for SQL queries
- No “backend” code here – this repo is purely client-side integration with the Modlee Agents API.

##### README for additional insights
- Confirms that teams will use at least one Modlee Agent (SQL, blog generator, social media)
- Provides context on API keys, support sessions, submission guidelines
- No internal architecture details – so we infer based on examples that the key system under test is the **Modlee Agents API** itself, plus external data sources.

a. Main components to include:
1. Client Applications (Python scripts in examples/)
2. Modlee Agents API Platform
- API Gateway / Authentication Layer
- Agent Engine (orchestration of different agents)
- Agent Modules:
- Core Docs Agent
- Data Operator Agent – REST Connectors
- Data Operator Agent – SQL Connector
3. External Services
- Google Places REST API
- News API
- NewsData API
4. Local Data Store
- SQLite mock_database.db in examples/data_operator_agent/sql
b. Relationships and data flow:
- Client scripts → HTTP request → API Gateway
- API Gateway → routes to specific Agent Module
- Agent Module (e.g. REST connector) → calls External Service → returns data → Agent Engine processes response
- SQL connector → runs queries on SQLite DB → returns results
- Agent Engine → constructs final response → returns to Client
c. Architectural patterns and principles:
- **Separation of Concerns**: each agent is a self-contained module (docs vs data)
- **Micro-style connectors**: each external API or database is accessed via its own sub-agent
- **API-driven design**: all interactions are over HTTP via a centralized gateway
d. Key technologies / frameworks:
- Python client code (examples/*.py)
- Modlee Agents API (hosted service)
- External REST APIs (Google Places, News, NewsData)
- SQLite for local SQL examples

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client Applications
    subgraph "Client Scripts"
        direction TB
        blog["blog_example.py"]:::client
        social["social_example.py"]:::client
        rp1["rest_places_api_example.py"]:::client
        rp2["rest_places_api_example_chat.py"]:::client
        rp3["rest_places_api_example_chat_scratch.py"]:::client
        rn["rest_news_example.py"]:::client
        rnd["rest_newsdata_example.py"]:::client
        sqlc["sql_example.py"]:::client
    end

    %% Modlee Agents Platform
    subgraph "Modlee Agents Platform"
        direction TB
        gateway["API Gateway / Auth Layer"]:::internal
        engine["Agent Engine"]:::internal

        subgraph "Agent Modules"
            direction TB
            core["Core Docs Agent"]:::internal
            subgraph "Data Operator Agents"
                direction TB
                restAgents["REST Connectors"]:::internal
                sqlAgent["SQL Connector Agent"]:::internal
            end
        end
    end

    %% External Services & DB
    subgraph "External Services"
        direction TB
        gpapi["Google Places API"]:::external
        napi["News API"]:::external
        ndapi["NewsData API"]:::external
    end
    db["SQLite Mock Database"]:::db

    %% Connections
    blog -->|calls| gateway
    social -->|calls| gateway
    rp1 -->|calls| gateway
    rp2 -->|calls| gateway
    rp3 -->|calls| gateway
    rn -->|calls| gateway
    rnd -->|calls| gateway
    sqlc -->|calls| gateway

    gateway -->|routes to| engine
    engine -->|invokes| core
    engine -->|invokes| restAgents
    engine -->|invokes| sqlAgent

    restAgents -->|uses| gpapi
    restAgents -->|uses| napi
    restAgents -->|uses| ndapi
    sqlAgent -->|queries| db

    engine -->|returns response| gateway
    gateway -->|responds to| blog
    gateway -->|responds to| social
    gateway -->|responds to| rp1
    gateway -->|responds to| rp2
    gateway -->|responds to| rp3
    gateway -->|responds to| rn
    gateway -->|responds to| rnd
    gateway -->|responds to| sqlc

    %% Click Events
    click blog "https://github.com/modlee-ai/uconn_modlee_ai_ml_club_hackathons/blob/main/examples/core_docs_agent/blog_example.py"
    click social "https://github.com/modlee-ai/uconn_modlee_ai_ml_club_hackathons/blob/main/examples/core_docs_agent/social_example.py"
    click rp1 "https://github.com/modlee-ai/uconn_modlee_ai_ml_club_hackathons/blob/main/examples/data_operator_agent/rest/google_places_api/rest_places_api_example.py"
    click rp2 "https://github.com/modlee-ai/uconn_modlee_ai_ml_club_hackathons/blob/main/examples/data_operator_agent/rest/google_places_api/rest_places_api_example_chat.py"
    click rp3 "https://github.com/modlee-ai/uconn_modlee_ai_ml_club_hackathons/blob/main/examples/data_operator_agent/rest/google_places_api/rest_places_api_example_chat_scratch.py"
    click rn "https://github.com/modlee-ai/uconn_modlee_ai_ml_club_hackathons/blob/main/examples/data_operator_agent/rest/news_api/rest_news_example.py"
    click rnd "https://github.com/modlee-ai/uconn_modlee_ai_ml_club_hackathons/blob/main/examples/data_operator_agent/rest/newsdata_api/rest_newsdata_example.py"
    click sqlc "https://github.com/modlee-ai/uconn_modlee_ai_ml_club_hackathons/blob/main/examples/data_operator_agent/sql/sql_example.py"
    click core "https://github.com/modlee-ai/uconn_modlee_ai_ml_club_hackathons/tree/main/examples/core_docs_agent"
    click restAgents "https://github.com/modlee-ai/uconn_modlee_ai_ml_club_hackathons/tree/main/examples/data_operator_agent/rest"
    click gpapi "https://github.com/modlee-ai/uconn_modlee_ai_ml_club_hackathons/tree/main/examples/data_operator_agent/rest/google_places_api"
    click napi "https://github.com/modlee-ai/uconn_modlee_ai_ml_club_hackathons/tree/main/examples/data_operator_agent/rest/news_api"
    click ndapi "https://github.com/modlee-ai/uconn_modlee_ai_ml_club_hackathons/tree/main/examples/data_operator_agent/rest/newsdata_api"
    click sqlAgent "https://github.com/modlee-ai/uconn_modlee_ai_ml_club_hackathons/tree/main/examples/data_operator_agent/sql"
    click db "https://github.com/modlee-ai/uconn_modlee_ai_ml_club_hackathons/blob/main/examples/data_operator_agent/sql/mock_database.db"

    %% Styles
    classDef internal fill:#D6EAF8,stroke:#21618C,stroke-width:1px
    classDef external fill:#D5F5E3,stroke:#1D8348,stroke-width:1px
    classDef db fill:#FAD7A0,stroke:#B9770E,stroke-width:1px
    classDef client fill:#FFFFFF,stroke:#7D3C98,stroke-width:1px,stroke-dasharray: 5 5
```
