# simaraconceicao/ai-agent-finance architecture

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

- Interactive diagram: https://gitdiagram.com/simaraconceicao/ai-agent-finance
- Repository: https://github.com/simaraconceicao/ai-agent-finance

## Overview

##### Project Type and Purpose
- This is a serverless, micro-service based AI assistant for personal finance management.
- Two main codebases:
a. AI Agent (`agente-financeiro/finance_agent/`): built with Google ADK + Gemini for conversational interactions and intent parsing.
b. MCP Server (`my-mcp/`): a FastMCP service that exposes tool calls (`list_expenses_by_user`, `create_expense`) via HTTP to the Agent.
- The system orchestrates user queries, LLM processing, tool invocation, and interactions with an external Finance REST API (hosted on Render with MongoDB).

##### File Structure Analysis
- Top level
- .gitignore, README.md
- `agente-financeiro/` → `finance_agent/`: contains `agent.py`, `.env.example`, ADK configuration.
- `my-mcp/`: contains `my_server.py`, Dockerfile, requirements.txt — this is the MCP Server service.
- Patterns
- Each component is a standalone service (microservice).
- Deployment configuration present (Dockerfile in `my-mcp/`; ADK CLI for `finance_agent/`).
- Environment files (.env example) and Cloud Run deployment instructions.

##### Key Architectural Insights from README
- The Agent uses prompt engineering + Gemini “gemini-2.0-flash” to interpret user intent.
- Tooling layer is implemented via the Model Context Protocol (FastMCP).
- Both services are deployed serverlessly on Google Cloud Run, requiring containerization (MCP) or ADK deployment (Agent).
- External dependency: a RESTful Finance API (separate service) backed by MongoDB.

a. AI Agent Service
- Tech: Python, Google ADK, Google Gemini (LLM via Vertex AI or builtin).
- Deployed on Cloud Run (with ADK CLI).
- Exposes a Dev UI (frontend to the user).
b. Gemini LLM
- A managed model; invoked by the Agent for natural language understanding/generation.
c. MCP Server
- Tech: Python, FastMCP, httpx.
- Exposes REST endpoints under `/mcp/`.
- Containerized via Dockerfile, deployed on Cloud Run.
d. External Finance Backend
- A third-party RESTful API (hosted on Render).
- Manages user finances and stores data in MongoDB.

##### Data Flow & Relationships
1. User → ADK Dev UI → Agent Service
2. Agent → Gemini LLM (prompt + user query) → Intent & action decision
3. Agent → MCP Server (`/mcp/` endpoint) → Tool invocation
4. MCP Server → External Finance API (httpx calls) → Retrieves or writes finance data
5. External API → MongoDB (persistence)
6. MCP Server returns response → Agent → Formats NL response → User

##### Architectural Patterns & Principles
- Microservices: each service has a single responsibility (Agent vs. Toolset).
- Serverless: Cloud Run hosting, auto-scaling, containerized deployment.
- LLM Tooling Pattern: LLM-driven agent with a well-defined tool interface (MCP).
- Environment-driven configuration: `.env`, Cloud Run env vars, fixed URLs in code.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interaction
    User["User"]:::user
    UI["ADK Dev UI"]:::ui

    %% Agent Subgraph
    subgraph "Cloud Run (Agent)" 
        AgentService["Finance Agent Service\n(Python 3.10, ADK CLI)"]:::service
        AgentEnv[".env.example"]:::env
        GeminiLLM["Gemini LLM"]:::llm
    end

    %% MCP Server Subgraph
    subgraph "Cloud Run (MCP Server)"
        MCPServer["MCP Server\n(Python 3.10, FastMCP, Docker)"]:::service
        Dockerfile["Dockerfile"]:::config
        Requirements["requirements.txt"]:::config
        Dockerignore[".dockerignore"]:::config
    end

    %% External Components
    FinanceAPI["Finance REST API\n(Render)"]:::external
    MongoDB["MongoDB\n(persistence)"]:::db

    %% Data Flows
    User -->|"interacts via"| UI
    UI -->|"HTTP"| AgentService
    AgentService -->|"gRPC/REST"| GeminiLLM
    AgentService -->|"/mcp/ HTTPS"| MCPServer
    MCPServer -->|"HTTPs (httpx)"| FinanceAPI
    FinanceAPI -->|"internal DB calls"| MongoDB
    MCPServer -->|"response"| AgentService
    AgentService -->|"formats NL response"| UI

    %% Click Events
    click AgentService "https://github.com/simaraconceicao/ai-agent-finance/blob/main/agente-financeiro/finance_agent/agent.py"
    click AgentEnv "https://github.com/simaraconceicao/ai-agent-finance/blob/main/agente-financeiro/finance_agent/.env.example"
    click MCPServer "https://github.com/simaraconceicao/ai-agent-finance/blob/main/my-mcp/my_server.py"
    click Dockerfile "https://github.com/simaraconceicao/ai-agent-finance/tree/main/my-mcp/dockerfile"
    click Requirements "https://github.com/simaraconceicao/ai-agent-finance/blob/main/my-mcp/requirements.txt"
    click Dockerignore "https://github.com/simaraconceicao/ai-agent-finance/blob/main/my-mcp/.dockerignore"

    %% Styles
    classDef user fill:#ccccff,stroke:#333,stroke-width:1px;
    classDef ui fill:#cce5ff,stroke:#333,stroke-width:1px;
    classDef service fill:#cce0ff,stroke:#0044cc,stroke-width:2px;
    classDef llm fill:#e5ccff,stroke:#660099,stroke-width:2px,shape:hexagon;
    classDef external fill:#ffe0b3,stroke:#cc8400,stroke-width:2px,shape:cloud;
    classDef db fill:#ccffcc,stroke:#008800,stroke-width:2px,shape:cylinder;
    classDef config fill:#f2f2f2,stroke:#999,stroke-width:1px,stroke-dasharray: 5 5;
    classDef env fill:#ffffcc,stroke:#999900,stroke-width:1px,stroke-dasharray: 5 5;
```
