# gamkers/project_jarvis architecture

> Architecture diagram of the GitHub repository gamkers/project_jarvis, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/gamkers/project_jarvis
- Repository: https://github.com/gamkers/project_jarvis

## Overview

JARVIS supports web chat and desktop voice interaction, with the Flask API and standalone assistant both entering the core Jarvis logic. That logic handles agent-driven requests, task and reminder operations, conversation context, and semantic search; persistent data is stored in spreadsheets and vector files. README documents Gemini, Groq, and ESP32 Marauder capabilities. The source excerpts show API-to-assistant calls and some internal behavior, but not all agent-tool wiring or background-service details, so those relationships are omitted where unsupported.

Main entry points: [`jarvis_ai.py`](https://github.com/gamkers/project_jarvis/blob/main/jarvis_ai.py) (Agent tools), [`static/index.html`](https://github.com/gamkers/project_jarvis/blob/main/static/index.html) (Web UI), [`app.py`](https://github.com/gamkers/project_jarvis/blob/main/app.py) (Flask API), [`jarvis_data/conversations.xlsx`](https://github.com/gamkers/project_jarvis/blob/main/jarvis_data/conversations.xlsx) (Conversation sheet)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User interfaces"]
  node_web_ui["Web UI<br/>[index.html]"]
  node_flask_api["Flask API<br/>[app.py]"]
  node_voice_mode["Voice mode<br/>[jarvis_ai.py]"]
end

subgraph group_assistant["Assistant runtime"]
  node_jarvis["Jarvis assistant<br/>[jarvis_ai.py]"]
  node_agent["Agent tools<br/>[jarvis_ai.py]"]
end

subgraph group_domain["Assistant capabilities"]
  node_conversation["Conversation handling<br/>[jarvis_ai.py]"]
  node_tasks["Task management<br/>[jarvis_ai.py]"]
  node_reminders["Reminder management<br/>[jarvis_ai.py]"]
  node_memory["User context<br/>[jarvis_ai.py]"]
  node_vector_search["Vector search<br/>[jarvis_ai.py]"]
  node_marauder["Marauder control<br/>[jarvis_ai.py]"]
end

subgraph group_persistence["Persistent data"]
  node_conversation_store[("Conversation sheet<br/>[conversations.xlsx]")]
  node_task_store[("Task sheet<br/>[tasks.xlsx]")]
  node_reminder_store[("Reminder sheet<br/>[reminders.xlsx]")]
  node_vector_store[("Vector data<br/>[vector_db.pkl]")]
  node_faiss_index[("FAISS index<br/>[faiss_index.idx]")]
end

subgraph group_integrations["External integrations"]
  node_gemini{{"Google Gemini"}}
  node_groq{{"Groq Llama"}}
  node_esp32{{"ESP32 Marauder"}}
end

node_user(("User"))

node_user -->|"enters request"| node_web_ui
node_web_ui -->|"sends requests"| node_flask_api
node_flask_api -->|"calls assistant"| node_jarvis
node_user -.->|"speaks to"| node_voice_mode
node_voice_mode -.->|"runs assistant"| node_jarvis
node_jarvis -->|"invokes agent"| node_agent
node_jarvis -->|"processes input"| node_conversation
node_agent -->|"uses tools"| node_tasks
node_agent -->|"uses tools"| node_reminders
node_agent -->|"uses tools"| node_vector_search
node_conversation -->|"updates context"| node_memory
node_conversation -->|"stores embeddings"| node_vector_store
node_vector_search -->|"searches index"| node_faiss_index
node_tasks -->|"persists tasks"| node_task_store
node_reminders -->|"persists reminders"| node_reminder_store
node_conversation -->|"stores history"| node_conversation_store
node_conversation -->|"generates responses"| node_gemini
node_agent -->|"uses model"| node_groq
node_agent -.->|"offers security tools"| node_marauder
node_marauder -.->|"controls device"| node_esp32
node_jarvis -->|"returns response"| node_web_ui

click node_web_ui "https://github.com/gamkers/project_jarvis/blob/main/static/index.html"
click node_flask_api "https://github.com/gamkers/project_jarvis/blob/main/app.py"
click node_voice_mode "https://github.com/gamkers/project_jarvis/blob/main/jarvis_ai.py"
click node_jarvis "https://github.com/gamkers/project_jarvis/blob/main/jarvis_ai.py"
click node_agent "https://github.com/gamkers/project_jarvis/blob/main/jarvis_ai.py"
click node_conversation "https://github.com/gamkers/project_jarvis/blob/main/jarvis_ai.py"
click node_tasks "https://github.com/gamkers/project_jarvis/blob/main/jarvis_ai.py"
click node_reminders "https://github.com/gamkers/project_jarvis/blob/main/jarvis_ai.py"
click node_memory "https://github.com/gamkers/project_jarvis/blob/main/jarvis_ai.py"
click node_vector_search "https://github.com/gamkers/project_jarvis/blob/main/jarvis_ai.py"
click node_marauder "https://github.com/gamkers/project_jarvis/blob/main/jarvis_ai.py"
click node_conversation_store "https://github.com/gamkers/project_jarvis/blob/main/jarvis_data/conversations.xlsx"
click node_task_store "https://github.com/gamkers/project_jarvis/blob/main/jarvis_data/tasks.xlsx"
click node_reminder_store "https://github.com/gamkers/project_jarvis/blob/main/jarvis_data/reminders.xlsx"
click node_vector_store "https://github.com/gamkers/project_jarvis/blob/main/jarvis_data/vector_db.pkl"
click node_faiss_index "https://github.com/gamkers/project_jarvis/blob/main/jarvis_data/faiss_index.idx"

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_web_ui,node_flask_api,node_voice_mode,node_user toneBlue
class node_jarvis,node_agent toneAmber
class node_conversation,node_tasks,node_reminders,node_memory,node_vector_search,node_marauder toneMint
class node_conversation_store,node_task_store,node_reminder_store,node_vector_store,node_faiss_index toneRose
class node_gemini,node_groq,node_esp32 toneIndigo
```

## Components

### User interfaces

- [Web UI](https://github.com/gamkers/project_jarvis/blob/main/static/index.html): `static/index.html`
- [Flask API](https://github.com/gamkers/project_jarvis/blob/main/app.py): `app.py`
- [Voice mode](https://github.com/gamkers/project_jarvis/blob/main/jarvis_ai.py): `jarvis_ai.py`

### Assistant runtime

- [Jarvis assistant](https://github.com/gamkers/project_jarvis/blob/main/jarvis_ai.py): `jarvis_ai.py`
- [Agent tools](https://github.com/gamkers/project_jarvis/blob/main/jarvis_ai.py): `jarvis_ai.py`

### Assistant capabilities

- [Conversation handling](https://github.com/gamkers/project_jarvis/blob/main/jarvis_ai.py): `jarvis_ai.py`
- [Task management](https://github.com/gamkers/project_jarvis/blob/main/jarvis_ai.py): `jarvis_ai.py`
- [Reminder management](https://github.com/gamkers/project_jarvis/blob/main/jarvis_ai.py): `jarvis_ai.py`
- [User context](https://github.com/gamkers/project_jarvis/blob/main/jarvis_ai.py): `jarvis_ai.py`
- [Vector search](https://github.com/gamkers/project_jarvis/blob/main/jarvis_ai.py): `jarvis_ai.py`
- [Marauder control](https://github.com/gamkers/project_jarvis/blob/main/jarvis_ai.py): `jarvis_ai.py`

### Persistent data

- [Conversation sheet](https://github.com/gamkers/project_jarvis/blob/main/jarvis_data/conversations.xlsx): `jarvis_data/conversations.xlsx`
- [Task sheet](https://github.com/gamkers/project_jarvis/blob/main/jarvis_data/tasks.xlsx): `jarvis_data/tasks.xlsx`
- [Reminder sheet](https://github.com/gamkers/project_jarvis/blob/main/jarvis_data/reminders.xlsx): `jarvis_data/reminders.xlsx`
- [Vector data](https://github.com/gamkers/project_jarvis/blob/main/jarvis_data/vector_db.pkl): `jarvis_data/vector_db.pkl`
- [FAISS index](https://github.com/gamkers/project_jarvis/blob/main/jarvis_data/faiss_index.idx): `jarvis_data/faiss_index.idx`

### External integrations

- **Google Gemini**
- **Groq Llama**
- **ESP32 Marauder**

### Other components

- **User**

## Connections

- User → Web UI: enters request (evidence: `README.md`)
- Web UI → Flask API: sends requests (evidence: `README.md`)
- Flask API → Jarvis assistant: calls assistant (evidence: `app.py`)
- User → Voice mode: speaks to (evidence: `README.md`)
- Voice mode → Jarvis assistant: runs assistant (evidence: `README.md`)
- Jarvis assistant → Agent tools: invokes agent (evidence: `jarvis_ai.py`)
- Jarvis assistant → Conversation handling: processes input (evidence: `README.md`)
- Agent tools → Task management: uses tools (evidence: `README.md`)
- Agent tools → Reminder management: uses tools (evidence: `README.md`)
- Agent tools → Vector search: uses tools (evidence: `README.md`)
- Conversation handling → User context: updates context (evidence: `jarvis_ai.py`)
- Conversation handling → Vector data: stores embeddings (evidence: `README.md`)
- Vector search → FAISS index: searches index (evidence: `README.md`)
- Task management → Task sheet: persists tasks (evidence: `README.md`)
- Reminder management → Reminder sheet: persists reminders (evidence: `README.md`)
- Conversation handling → Conversation sheet: stores history (evidence: `README.md`)
- Conversation handling → Google Gemini: generates responses (evidence: `README.md`)
- Agent tools → Groq Llama: uses model (evidence: `README.md`)
- Agent tools → Marauder control: offers security tools (evidence: `README.md`)
- Marauder control → ESP32 Marauder: controls device (evidence: `README.md`)
- Jarvis assistant → Web UI: returns response (evidence: `README.md`)
