# notwitcheer/portal-assistant architecture

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

- Interactive diagram: https://gitdiagram.com/notwitcheer/portal-assistant
- Repository: https://github.com/notwitcheer/portal-assistant

## Overview

portal-assistant is a Hermes Agent profile for personal-assistant chats, not a standalone application. A user chats through a supported client or messaging platform; Hermes runs the profile, applies its behavioral instructions and configured tools, and uses the main or task-specific models to respond. The profile emphasizes reminders, personal planning and notes, with confirmation before external actions. The repository contains configuration and profile instructions rather than runtime source, so this map shows only README-documented relationships; the exact internal execution flow is not visible.

Main entry points: [`config.yaml`](https://github.com/notwitcheer/portal-assistant/blob/main/config.yaml) (Main model), [`distribution.yaml`](https://github.com/notwitcheer/portal-assistant/blob/main/distribution.yaml) (Profile distribution), [`SOUL.md`](https://github.com/notwitcheer/portal-assistant/blob/main/SOUL.md) (Assistant instructions)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_profile["Profile behavior"]
  node_instructions["Assistant instructions<br/>[SOUL.md]"]
  node_reminders["Reminder tools<br/>[config.yaml]"]
  node_approvals["Action approvals<br/>[config.yaml]"]
end

subgraph group_settings["Runtime settings"]
  node_hermes["Hermes Agent"]
  node_profile_config["Profile configuration<br/>[config.yaml]"]
  node_distribution["Profile distribution<br/>[distribution.yaml]"]
  node_main_model["Main model<br/>[config.yaml]"]
  node_side_tasks["Auxiliary models<br/>[config.yaml]"]
end

subgraph group_channels["Chat channels"]
  node_clients["Chat clients"]
  node_messaging["Messaging platforms"]
end

node_user(("Assistant user"))
node_model_service["Model providers"]

node_user -->|"chats through"| node_clients
node_user -->|"chats through"| node_messaging
node_clients -->|"connect to"| node_hermes
node_messaging -->|"deliver messages"| node_hermes
node_distribution -->|"packages settings"| node_profile_config
node_hermes -->|"follows"| node_instructions
node_hermes -->|"uses"| node_profile_config
node_hermes -->|"handles turns"| node_main_model
node_hermes -->|"uses"| node_reminders
node_hermes -->|"checks actions"| node_approvals
node_hermes -->|"uses for side tasks"| node_side_tasks
node_main_model -->|"calls"| node_model_service
node_side_tasks -->|"calls"| node_model_service

click node_instructions "https://github.com/notwitcheer/portal-assistant/blob/main/SOUL.md"
click node_profile_config "https://github.com/notwitcheer/portal-assistant/blob/main/config.yaml"
click node_distribution "https://github.com/notwitcheer/portal-assistant/blob/main/distribution.yaml"
click node_main_model "https://github.com/notwitcheer/portal-assistant/blob/main/config.yaml"
click node_reminders "https://github.com/notwitcheer/portal-assistant/blob/main/config.yaml"
click node_approvals "https://github.com/notwitcheer/portal-assistant/blob/main/config.yaml"
click node_side_tasks "https://github.com/notwitcheer/portal-assistant/blob/main/config.yaml"

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_instructions,node_reminders,node_approvals,node_user toneBlue
class node_hermes,node_profile_config,node_distribution,node_main_model,node_side_tasks toneAmber
class node_clients,node_messaging toneMint
class node_model_service toneIndigo
```

## Components

### Profile behavior

- [Assistant instructions](https://github.com/notwitcheer/portal-assistant/blob/main/SOUL.md): `SOUL.md`
- [Reminder tools](https://github.com/notwitcheer/portal-assistant/blob/main/config.yaml): `config.yaml`
- [Action approvals](https://github.com/notwitcheer/portal-assistant/blob/main/config.yaml): `config.yaml`

### Runtime settings

- **Hermes Agent**
- [Profile configuration](https://github.com/notwitcheer/portal-assistant/blob/main/config.yaml): `config.yaml`
- [Profile distribution](https://github.com/notwitcheer/portal-assistant/blob/main/distribution.yaml): `distribution.yaml`
- [Main model](https://github.com/notwitcheer/portal-assistant/blob/main/config.yaml): `config.yaml`
- [Auxiliary models](https://github.com/notwitcheer/portal-assistant/blob/main/config.yaml): `config.yaml`

### Chat channels

- **Chat clients**
- **Messaging platforms**

### Other components

- **Assistant user**
- **Model providers**

## Connections

- Assistant user → Chat clients: chats through (evidence: `README.md`)
- Assistant user → Messaging platforms: chats through (evidence: `README.md`)
- Chat clients → Hermes Agent: connect to (evidence: `README.md`)
- Messaging platforms → Hermes Agent: deliver messages (evidence: `README.md`)
- Profile distribution → Profile configuration: packages settings (evidence: `README.md`)
- Hermes Agent → Assistant instructions: follows (evidence: `README.md`)
- Hermes Agent → Profile configuration: uses (evidence: `README.md`)
- Hermes Agent → Main model: handles turns (evidence: `README.md`)
- Hermes Agent → Reminder tools: uses (evidence: `README.md`)
- Hermes Agent → Action approvals: checks actions (evidence: `README.md`)
- Hermes Agent → Auxiliary models: uses for side tasks (evidence: `README.md`)
- Main model → Model providers: calls (evidence: `README.md`)
- Auxiliary models → Model providers: calls (evidence: `README.md`)
