# totan-santra/final-year-project architecture

> Architecture diagram of the GitHub repository totan-santra/final-year-project, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/totan-santra/final-year-project
- Repository: https://github.com/totan-santra/final-year-project

## Overview

Marvin is a terminal voice and text assistant. The principal workflow is terminal input (or wake-word speech), routing through the assistant’s conversation graph, optional tool execution, then a text or spoken reply. Its tool capabilities include notes, persistent personal facts, web and weather queries, browser actions, Google email/calendar, file management, system information, and app launching. The graph reflects imports and registrations shown in the excerpts; storage and service links are included only where those excerpts or the README support them.

Main entry points: [`core/agent.py`](https://github.com/totan-santra/final-year-project/blob/main/core/agent.py) (Assistant graph), [`main.py`](https://github.com/totan-santra/final-year-project/blob/main/main.py) (Runtime entry), [`tools/memory_web.py`](https://github.com/totan-santra/final-year-project/blob/main/tools/memory_web.py) (Fact memory), [`tools/weather.py`](https://github.com/totan-santra/final-year-project/blob/main/tools/weather.py) (Weather lookup)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interaction["User interaction"]
  node_main["Runtime entry<br/>[main.py]"]
  node_audio["Voice I/O<br/>[audio.py]"]
end

subgraph group_orchestration["Assistant orchestration"]
  node_agent["Assistant graph<br/>[agent.py]"]
  node_model{{"Groq language model"}}
  node_checkpoint[("Conversation checkpoint<br/>[settings.py]")]
end

subgraph group_information["Information tools"]
  node_notes["Notes and time<br/>[notes.py]"]
  node_memory["Fact memory<br/>[memory_web.py]"]
  node_chroma[("Persistent fact store")]
  node_web_search["Web search<br/>[memory_web.py]"]
  node_weather["Weather lookup<br/>[weather.py]"]
  node_browser["Browser actions<br/>[browser.py]"]
end

subgraph group_local_actions["Local and connected actions"]
  node_google["Email and calendar<br/>[google.py]"]
  node_files["Workspace files<br/>[files.py]"]
  node_workspace[("Workspace storage")]
  node_system["System information<br/>[system.py]"]
  node_apps["App launcher<br/>[apps.py]"]
end

node_user(("Terminal user"))
node_web_services{{"Web services"}}
node_google_services{{"Google services"}}
node_local_os{{"Local operating system"}}

node_user -->|"enters request"| node_main
node_main -->|"captures and speaks"| node_audio
node_main -->|"submits request"| node_agent
node_agent -->|"invokes model"| node_model
node_agent -->|"registers tools"| node_notes
node_agent -->|"registers tools"| node_memory
node_agent -->|"registers tools"| node_web_search
node_agent -->|"registers tools"| node_weather
node_agent -->|"registers tools"| node_browser
node_agent -->|"registers tools"| node_google
node_agent -->|"registers tools"| node_files
node_agent -->|"registers tools"| node_system
node_agent -->|"registers tools"| node_apps
node_agent -->|"saves conversation state"| node_checkpoint
node_memory -->|"reads and writes facts"| node_chroma
node_web_search -->|"queries web"| node_web_services
node_weather -->|"requests conditions"| node_web_services
node_browser -->|"opens or fetches pages"| node_web_services
node_google -->|"reads and updates"| node_google_services
node_files -->|"reads and writes"| node_workspace
node_system -->|"reads metrics"| node_local_os
node_apps -->|"launches approved apps"| node_local_os

click node_main "https://github.com/totan-santra/final-year-project/blob/main/main.py"
click node_audio "https://github.com/totan-santra/final-year-project/blob/main/voice/audio.py"
click node_agent "https://github.com/totan-santra/final-year-project/blob/main/core/agent.py"
click node_notes "https://github.com/totan-santra/final-year-project/blob/main/tools/notes.py"
click node_memory "https://github.com/totan-santra/final-year-project/blob/main/tools/memory_web.py"
click node_chroma "https://github.com/totan-santra/final-year-project/tree/main/Marvin_chroma"
click node_web_search "https://github.com/totan-santra/final-year-project/blob/main/tools/memory_web.py"
click node_weather "https://github.com/totan-santra/final-year-project/blob/main/tools/weather.py"
click node_browser "https://github.com/totan-santra/final-year-project/blob/main/tools/browser.py"
click node_google "https://github.com/totan-santra/final-year-project/blob/main/tools/google.py"
click node_files "https://github.com/totan-santra/final-year-project/blob/main/tools/files.py"
click node_system "https://github.com/totan-santra/final-year-project/blob/main/tools/system.py"
click node_apps "https://github.com/totan-santra/final-year-project/blob/main/tools/apps.py"
click node_checkpoint "https://github.com/totan-santra/final-year-project/blob/main/settings.py"

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_main,node_audio,node_user toneBlue
class node_agent,node_model,node_checkpoint toneAmber
class node_notes,node_memory,node_chroma,node_web_search,node_weather,node_browser toneMint
class node_google,node_files,node_workspace,node_system,node_apps toneRose
class node_web_services,node_google_services,node_local_os toneIndigo
```

## Components

### User interaction

- [Runtime entry](https://github.com/totan-santra/final-year-project/blob/main/main.py): `main.py`
- [Voice I/O](https://github.com/totan-santra/final-year-project/blob/main/voice/audio.py): `voice/audio.py`

### Assistant orchestration

- [Assistant graph](https://github.com/totan-santra/final-year-project/blob/main/core/agent.py): `core/agent.py`
- **Groq language model**
- [Conversation checkpoint](https://github.com/totan-santra/final-year-project/blob/main/settings.py): `settings.py`

### Information tools

- [Notes and time](https://github.com/totan-santra/final-year-project/blob/main/tools/notes.py): `tools/notes.py`
- [Fact memory](https://github.com/totan-santra/final-year-project/blob/main/tools/memory_web.py): `tools/memory_web.py`
- [Persistent fact store](https://github.com/totan-santra/final-year-project/tree/main/Marvin_chroma): `Marvin_chroma`
- [Web search](https://github.com/totan-santra/final-year-project/blob/main/tools/memory_web.py): `tools/memory_web.py`
- [Weather lookup](https://github.com/totan-santra/final-year-project/blob/main/tools/weather.py): `tools/weather.py`
- [Browser actions](https://github.com/totan-santra/final-year-project/blob/main/tools/browser.py): `tools/browser.py`

### Local and connected actions

- [Email and calendar](https://github.com/totan-santra/final-year-project/blob/main/tools/google.py): `tools/google.py`
- [Workspace files](https://github.com/totan-santra/final-year-project/blob/main/tools/files.py): `tools/files.py`
- **Workspace storage**
- [System information](https://github.com/totan-santra/final-year-project/blob/main/tools/system.py): `tools/system.py`
- [App launcher](https://github.com/totan-santra/final-year-project/blob/main/tools/apps.py): `tools/apps.py`

### Other components

- **Terminal user**
- **Web services**
- **Google services**
- **Local operating system**

## Connections

- Terminal user → Runtime entry: enters request (evidence: `README.md`)
- Runtime entry → Voice I/O: captures and speaks (evidence: `main.py`)
- Runtime entry → Assistant graph: submits request (evidence: `main.py`)
- Assistant graph → Groq language model: invokes model (evidence: `core/agent.py`)
- Assistant graph → Notes and time: registers tools (evidence: `core/agent.py`)
- Assistant graph → Fact memory: registers tools (evidence: `core/agent.py`)
- Assistant graph → Web search: registers tools (evidence: `core/agent.py`)
- Assistant graph → Weather lookup: registers tools (evidence: `core/agent.py`)
- Assistant graph → Browser actions: registers tools (evidence: `core/agent.py`)
- Assistant graph → Email and calendar: registers tools (evidence: `core/agent.py`)
- Assistant graph → Workspace files: registers tools (evidence: `core/agent.py`)
- Assistant graph → System information: registers tools (evidence: `core/agent.py`)
- Assistant graph → App launcher: registers tools (evidence: `core/agent.py`)
- Assistant graph → Conversation checkpoint: saves conversation state (evidence: `core/agent.py`)
- Fact memory → Persistent fact store: reads and writes facts (evidence: `tools/memory_web.py`)
- Web search → Web services: queries web (evidence: `tools/memory_web.py`)
- Weather lookup → Web services: requests conditions (evidence: `tools/weather.py`)
- Browser actions → Web services: opens or fetches pages (evidence: `tools/browser.py`)
- Email and calendar → Google services: reads and updates (evidence: `tools/google.py`)
- Workspace files → Workspace storage: reads and writes (evidence: `tools/files.py`)
- System information → Local operating system: reads metrics (evidence: `README.md`)
- App launcher → Local operating system: launches approved apps (evidence: `tools/apps.py`)