# ogonzalezc782/superpoderes-para-ia architecture

> Architecture diagram of the GitHub repository ogonzalezc782/superpoderes-para-ia, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ogonzalezc782/superpoderes-para-ia
- Repository: https://github.com/ogonzalezc782/superpoderes-para-ia

## Overview

#### Purpose
This repository packages an administrative AI agent for Colegio Universitario de Cartago (CUC). Users ask academic-data questions in natural language; the agent retrieves enrollment and grade data, performs multi-step analysis, and can send formatted email reports.

#### Primary Entry Point
The deployable artifact is the n8n workflow export: `Agente IA Administrativo CUC.json`. Import it into n8n, configure credentials, activate it, and access its chat trigger through n8n’s test or production chat URL.

#### Interaction and Orchestration
1. A user sends a chat message to the workflow.
2. The n8n AI Agent receives the message and conversational context.
3. Google Gemini interprets the request and selects one or more connected tools through function calling.
4. Tool results return to the agent, which synthesizes the final chat response or initiates an email action.

The orchestration, prompt, tool wiring, memory configuration, and trigger behavior are expected to reside in `Agente IA Administrativo CUC.json`.

#### Academic Data Boundary
Two workbook artifacts define the domain data model:
- `Estudiantes.xlsx`: enrollment records, centered on carnet, full name, and degree/career.
- `Notas.xlsx`: grade records, centered on full name, subject, and grade.

In deployment, these workbooks are hosted in Microsoft OneDrive or SharePoint and accessed through n8n Microsoft Excel nodes. The repository copies are sample/source data rather than a local runtime database.

#### Agent Tools and Actions
The workflow exposes three architecture-defining capabilities:
- Enrollment lookup against the student workbook: `Estudiantes.xlsx`.
- Grade lookup and performance analysis against the grades workbook: `Notas.xlsx`.
- Institutional email delivery via Gmail, including HTML-formatted reports.

Gemini decides whether to invoke one tool or combine them—for example, joining a student’s enrollment information with all grades before generating a response or email.

#### External Runtime and Services
n8n is the execution runtime, either n8n Cloud or self-hosted (Node.js 18+ is required only for self-hosted deployment). Material external dependencies are:
- Google Gemini API for chat reasoning and tool selection.
- Microsoft 365 Excel OAuth plus OneDrive/SharePoint for workbook access.
- Gmail API/OAuth for optional outbound messages.

Credential setup is intentionally environment-specific and should remain in n8n rather than repository files.

#### Operational Boundaries
The agent handles academic and personally identifiable student data, so production deployment needs authenticated chat access, least-privilege Microsoft/Gmail credentials, secret management, and log review. Service limits influence behavior: Gemini request quotas, Gmail daily sending limits, workbook format/size constraints, and a documented response-length limit.

#### Supporting Material
`README.md` is the setup and operational guide. `Charla Superpoders para IA.pdf` is presentation material and is not part of the runtime execution path.

Main entry points: [`Agente IA Administrativo CUC.json`](https://github.com/ogonzalezc782/superpoderes-para-ia/blob/main/Agente%20IA%20Administrativo%20CUC.json) (AI Agent), [`README.md`](https://github.com/ogonzalezc782/superpoderes-para-ia/blob/main/README.md) (Setup Guide), [`Estudiantes.xlsx`](https://github.com/ogonzalezc782/superpoderes-para-ia/blob/main/Estudiantes.xlsx) (Student Records), [`Notas.xlsx`](https://github.com/ogonzalezc782/superpoderes-para-ia/blob/main/Notas.xlsx) (Grade Records)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workflow["n8n Workflow"]
  node_chat_trigger["Chat Trigger<br/>n8n trigger"]
  node_ai_agent{{"AI Agent<br/>n8n agent"}}
  node_agent_memory["Conversation Memory<br/>agent memory"]
  node_enrollment_tool["Enrollment Lookup<br/>n8n Excel tool"]
  node_grades_tool["Grades Analysis<br/>n8n Excel tool"]
  node_email_tool["Email Reports<br/>n8n Gmail tool"]
end

subgraph group_academic_data["Academic Data"]
  node_student_workbook[("Student Records<br/>Excel workbook<br/>[Estudiantes.xlsx]")]
  node_grades_workbook[("Grade Records<br/>Excel workbook<br/>[Notas.xlsx]")]
end

subgraph group_external_services["External Services"]
  node_gemini{{"Google Gemini<br/>LLM API"}}
  node_microsoft_365["Microsoft 365 Excel<br/>OAuth API"]
  node_gmail["Gmail API<br/>OAuth API"]
end

node_user(("Academic User<br/>actor"))
node_n8n_runtime["n8n Runtime<br/>cloud or self-hosted runtime"]
node_readme["Setup Guide<br/>documentation<br/>[README.md]"]

node_user -->|"sends question"| node_chat_trigger
node_n8n_runtime -->|"hosts"| node_chat_trigger
node_chat_trigger -->|"message and context"| node_ai_agent
node_ai_agent -->|"reads/writes context"| node_agent_memory
node_ai_agent -->|"reasoning and tool selection"| node_gemini
node_ai_agent -->|"invokes"| node_enrollment_tool
node_ai_agent -->|"invokes"| node_grades_tool
node_ai_agent -->|"optionally invokes"| node_email_tool
node_enrollment_tool -->|"queries via OAuth"| node_microsoft_365
node_grades_tool -->|"queries via OAuth"| node_microsoft_365
node_microsoft_365 -->|"accesses hosted copy"| node_student_workbook
node_microsoft_365 -->|"accesses hosted copy"| node_grades_workbook
node_email_tool -->|"sends via OAuth"| node_gmail
node_ai_agent -->|"chat response"| node_user
node_readme -.->|"deployment guidance"| node_n8n_runtime

click node_chat_trigger "https://github.com/ogonzalezc782/superpoderes-para-ia/blob/main/Agente%20IA%20Administrativo%20CUC.json"
click node_ai_agent "https://github.com/ogonzalezc782/superpoderes-para-ia/blob/main/Agente%20IA%20Administrativo%20CUC.json"
click node_agent_memory "https://github.com/ogonzalezc782/superpoderes-para-ia/blob/main/Agente%20IA%20Administrativo%20CUC.json"
click node_enrollment_tool "https://github.com/ogonzalezc782/superpoderes-para-ia/blob/main/Agente%20IA%20Administrativo%20CUC.json"
click node_grades_tool "https://github.com/ogonzalezc782/superpoderes-para-ia/blob/main/Agente%20IA%20Administrativo%20CUC.json"
click node_email_tool "https://github.com/ogonzalezc782/superpoderes-para-ia/blob/main/Agente%20IA%20Administrativo%20CUC.json"
click node_student_workbook "https://github.com/ogonzalezc782/superpoderes-para-ia/blob/main/Estudiantes.xlsx"
click node_grades_workbook "https://github.com/ogonzalezc782/superpoderes-para-ia/blob/main/Notas.xlsx"
click node_readme "https://github.com/ogonzalezc782/superpoderes-para-ia/blob/main/README.md"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_chat_trigger,node_ai_agent,node_agent_memory,node_enrollment_tool,node_grades_tool,node_email_tool toneBlue
class node_student_workbook,node_grades_workbook toneAmber
class node_gemini,node_microsoft_365,node_gmail toneMint
class node_user,node_n8n_runtime,node_readme toneNeutral
```

## Components

### n8n Workflow

Deployable orchestration and agent configuration.

- [Chat Trigger](https://github.com/ogonzalezc782/superpoderes-para-ia/blob/main/Agente%20IA%20Administrativo%20CUC.json): n8n trigger · Accepts test or production chat messages. · `Agente IA Administrativo CUC.json`
- [AI Agent](https://github.com/ogonzalezc782/superpoderes-para-ia/blob/main/Agente%20IA%20Administrativo%20CUC.json): n8n agent · Coordinates conversation, tools, and responses. · `Agente IA Administrativo CUC.json`
- [Conversation Memory](https://github.com/ogonzalezc782/superpoderes-para-ia/blob/main/Agente%20IA%20Administrativo%20CUC.json): agent memory · `Agente IA Administrativo CUC.json`
- [Enrollment Lookup](https://github.com/ogonzalezc782/superpoderes-para-ia/blob/main/Agente%20IA%20Administrativo%20CUC.json): n8n Excel tool · `Agente IA Administrativo CUC.json`
- [Grades Analysis](https://github.com/ogonzalezc782/superpoderes-para-ia/blob/main/Agente%20IA%20Administrativo%20CUC.json): n8n Excel tool · Retrieves grades and supports performance analysis. · `Agente IA Administrativo CUC.json`
- [Email Reports](https://github.com/ogonzalezc782/superpoderes-para-ia/blob/main/Agente%20IA%20Administrativo%20CUC.json): n8n Gmail tool · Sends HTML-formatted institutional reports. · `Agente IA Administrativo CUC.json`

### Academic Data

Sample/source workbooks hosted externally at runtime.

- [Student Records](https://github.com/ogonzalezc782/superpoderes-para-ia/blob/main/Estudiantes.xlsx): Excel workbook · Enrollment data keyed by carnet, name, and career. · `Estudiantes.xlsx`
- [Grade Records](https://github.com/ogonzalezc782/superpoderes-para-ia/blob/main/Notas.xlsx): Excel workbook · Grades keyed by student name and subject. · `Notas.xlsx`

### External Services

Credentialed services configured in n8n.

- **Google Gemini**: LLM API · Interprets requests and selects tools through function calling.
- **Microsoft 365 Excel**: OAuth API · Reads workbooks from OneDrive or SharePoint.
- **Gmail API**: OAuth API · Delivers outbound email.

### Other components

- **Academic User**: actor
- **n8n Runtime**: cloud or self-hosted runtime · Hosts the imported workflow.
- [Setup Guide](https://github.com/ogonzalezc782/superpoderes-para-ia/blob/main/README.md): documentation · Deployment and operational guidance. · `README.md`

## Connections

- Academic User → Chat Trigger: sends question
- n8n Runtime → Chat Trigger: hosts
- Chat Trigger → AI Agent: message and context
- AI Agent → Conversation Memory: reads/writes context
- AI Agent → Google Gemini: reasoning and tool selection
- AI Agent → Enrollment Lookup: invokes
- AI Agent → Grades Analysis: invokes
- AI Agent → Email Reports: optionally invokes
- Enrollment Lookup → Microsoft 365 Excel: queries via OAuth
- Grades Analysis → Microsoft 365 Excel: queries via OAuth
- Microsoft 365 Excel → Student Records: accesses hosted copy
- Microsoft 365 Excel → Grade Records: accesses hosted copy
- Email Reports → Gmail API: sends via OAuth
- AI Agent → Academic User: chat response
- Setup Guide → n8n Runtime: deployment guidance