# dhanushramesh/personal-assistant architecture

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

- Interactive diagram: https://gitdiagram.com/dhanushramesh/personal-assistant
- Repository: https://github.com/dhanushramesh/personal-assistant

## Overview

This repository is a Go personal-assistant server. The documented workflow accepts API work, continues it in a background runner, asks a model to reason and invoke tools, then reports progress or completion to listeners. The tree also contains distinct calendar, memory, reminder, profile, speech, and Google-integration domains. The README describes chat and tools as “not started,” which conflicts with the substantial implementation files; the graph includes those modules but avoids asserting unsampled wiring beyond documented relationships and visible startup references.

Main entry points: [`internal/runner/execute.go`](https://github.com/dhanushramesh/personal-assistant/blob/main/internal/runner/execute.go) (Chat runner), [`cmd/server/main.go`](https://github.com/dhanushramesh/personal-assistant/blob/main/cmd/server/main.go) (Server startup), [`internal/tool/registry.go`](https://github.com/dhanushramesh/personal-assistant/blob/main/internal/tool/registry.go) (Tool registry), [`internal/api`](https://github.com/dhanushramesh/personal-assistant/tree/main/internal/api) (HTTP API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Server and API"]
  node_server["Server startup<br/>[main.go]"]
  node_api["HTTP API"]
  node_auth["Authentication<br/>[authn.go]"]
end

subgraph group_agent["Assistant execution"]
  node_runner["Chat runner<br/>[execute.go]"]
  node_provider["Model provider<br/>[client.go]"]
  node_toolregistry["Tool registry<br/>[registry.go]"]
  node_events["Event stream<br/>[bus.go]"]
end

subgraph group_domains["Assistant domains"]
  node_chat["Chats and conversations"]
  node_calendar["Calendar events<br/>[events.go]"]
  node_tasks["Tasks<br/>[tasks.go]"]
  node_reminders["Reminders<br/>[remind.go]"]
  node_memory["Memory and recall"]
  node_profile["Personal profile<br/>[rhythm.go]"]
  node_speech["Speech<br/>[speech.go]"]
  node_announcements["Announcements<br/>[announcement.go]"]
end

subgraph group_persistence["Persistence and integrations"]
  node_google["Google account link<br/>[oauth.go]"]
  node_mysql[("MySQL storage<br/>[storage.go]")]
  node_chatrepo["Chat repository<br/>[repository.go]"]
end

node_user(("Person or client"))
node_platformai{{"Platform AI"}}

node_user -->|"sends request"| node_api
node_api -->|"authenticates"| node_auth
node_api -->|"starts background work"| node_runner
node_runner -->|"requests model"| node_provider
node_provider -->|"sends prompt"| node_platformai
node_runner -->|"dispatches tools"| node_toolregistry
node_runner -->|"publishes updates"| node_events
node_api -->|"streams messages"| node_events
node_runner -->|"runs chat"| node_chat
node_server -->|"configures"| node_runner
node_server -->|"registers tools"| node_toolregistry
node_server -->|"opens database"| node_mysql
node_chatrepo -->|"reads and writes"| node_mysql
node_server -->|"constructs repository"| node_chatrepo
node_toolregistry -.->|"offers calendar tools"| node_calendar
node_toolregistry -->|"offers task tools"| node_tasks
node_toolregistry -.->|"offers reminder tools"| node_reminders
node_runner -.->|"uses recalled context"| node_memory
node_server -.->|"configures account link"| node_google
node_server -->|"starts reminder loop"| node_reminders
node_server -->|"runs profile pass"| node_profile
node_runner -.->|"produces speech"| node_speech
node_runner -.->|"announces outcomes"| node_announcements

click node_server "https://github.com/dhanushramesh/personal-assistant/blob/main/cmd/server/main.go"
click node_api "https://github.com/dhanushramesh/personal-assistant/tree/main/internal/api"
click node_auth "https://github.com/dhanushramesh/personal-assistant/blob/main/internal/api/authn/authn.go"
click node_runner "https://github.com/dhanushramesh/personal-assistant/blob/main/internal/runner/execute.go"
click node_provider "https://github.com/dhanushramesh/personal-assistant/blob/main/internal/environment/platformai/client.go"
click node_toolregistry "https://github.com/dhanushramesh/personal-assistant/blob/main/internal/tool/registry.go"
click node_events "https://github.com/dhanushramesh/personal-assistant/blob/main/internal/events/bus.go"
click node_chat "https://github.com/dhanushramesh/personal-assistant/tree/main/internal/chat"
click node_calendar "https://github.com/dhanushramesh/personal-assistant/blob/main/internal/calendar/events.go"
click node_tasks "https://github.com/dhanushramesh/personal-assistant/blob/main/internal/tasks/tasks.go"
click node_reminders "https://github.com/dhanushramesh/personal-assistant/blob/main/internal/remind/remind.go"
click node_memory "https://github.com/dhanushramesh/personal-assistant/tree/main/internal/memory"
click node_profile "https://github.com/dhanushramesh/personal-assistant/blob/main/internal/profile/rhythm.go"
click node_speech "https://github.com/dhanushramesh/personal-assistant/blob/main/internal/speech/speech.go"
click node_announcements "https://github.com/dhanushramesh/personal-assistant/blob/main/internal/announcement/announcement.go"
click node_google "https://github.com/dhanushramesh/personal-assistant/blob/main/internal/google/oauth.go"
click node_mysql "https://github.com/dhanushramesh/personal-assistant/blob/main/internal/storage/storage.go"
click node_chatrepo "https://github.com/dhanushramesh/personal-assistant/blob/main/internal/chat/mysql/repository.go"

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_server,node_api,node_auth,node_user toneBlue
class node_runner,node_provider,node_toolregistry,node_events toneAmber
class node_chat,node_calendar,node_tasks,node_reminders,node_memory,node_profile,node_speech,node_announcements toneMint
class node_google,node_mysql,node_chatrepo toneRose
class node_platformai toneIndigo
```

## Components

### Server and API

- [Server startup](https://github.com/dhanushramesh/personal-assistant/blob/main/cmd/server/main.go): `cmd/server/main.go`
- [HTTP API](https://github.com/dhanushramesh/personal-assistant/tree/main/internal/api): `internal/api`
- [Authentication](https://github.com/dhanushramesh/personal-assistant/blob/main/internal/api/authn/authn.go): `internal/api/authn/authn.go`

### Assistant execution

- [Chat runner](https://github.com/dhanushramesh/personal-assistant/blob/main/internal/runner/execute.go): `internal/runner/execute.go`
- [Model provider](https://github.com/dhanushramesh/personal-assistant/blob/main/internal/environment/platformai/client.go): `internal/environment/platformai/client.go`
- [Tool registry](https://github.com/dhanushramesh/personal-assistant/blob/main/internal/tool/registry.go): `internal/tool/registry.go`
- [Event stream](https://github.com/dhanushramesh/personal-assistant/blob/main/internal/events/bus.go): `internal/events/bus.go`

### Assistant domains

- [Chats and conversations](https://github.com/dhanushramesh/personal-assistant/tree/main/internal/chat): `internal/chat`
- [Calendar events](https://github.com/dhanushramesh/personal-assistant/blob/main/internal/calendar/events.go): `internal/calendar/events.go`
- [Tasks](https://github.com/dhanushramesh/personal-assistant/blob/main/internal/tasks/tasks.go): `internal/tasks/tasks.go`
- [Reminders](https://github.com/dhanushramesh/personal-assistant/blob/main/internal/remind/remind.go): `internal/remind/remind.go`
- [Memory and recall](https://github.com/dhanushramesh/personal-assistant/tree/main/internal/memory): `internal/memory`
- [Personal profile](https://github.com/dhanushramesh/personal-assistant/blob/main/internal/profile/rhythm.go): `internal/profile/rhythm.go`
- [Speech](https://github.com/dhanushramesh/personal-assistant/blob/main/internal/speech/speech.go): `internal/speech/speech.go`
- [Announcements](https://github.com/dhanushramesh/personal-assistant/blob/main/internal/announcement/announcement.go): `internal/announcement/announcement.go`

### Persistence and integrations

- [Google account link](https://github.com/dhanushramesh/personal-assistant/blob/main/internal/google/oauth.go): `internal/google/oauth.go`
- [MySQL storage](https://github.com/dhanushramesh/personal-assistant/blob/main/internal/storage/storage.go): `internal/storage/storage.go`
- [Chat repository](https://github.com/dhanushramesh/personal-assistant/blob/main/internal/chat/mysql/repository.go): `internal/chat/mysql/repository.go`

### Other components

- **Person or client**
- **Platform AI**

## Connections

- Person or client → HTTP API: sends request
- HTTP API → Authentication: authenticates (evidence: `internal/api/authn/authn.go`)
- HTTP API → Chat runner: starts background work
- Chat runner → Model provider: requests model (evidence: `internal/runner/execute.go`)
- Model provider → Platform AI: sends prompt (evidence: `internal/environment/platformai/client.go`)
- Chat runner → Tool registry: dispatches tools (evidence: `internal/runner/execute.go`)
- Chat runner → Event stream: publishes updates (evidence: `internal/runner/execute.go`)
- HTTP API → Event stream: streams messages
- Chat runner → Chats and conversations: runs chat (evidence: `internal/runner/execute.go`)
- Server startup → Chat runner: configures (evidence: `cmd/server/main.go`)
- Server startup → Tool registry: registers tools (evidence: `cmd/server/main.go`)
- Server startup → MySQL storage: opens database (evidence: `cmd/server/main.go`)
- Chat repository → MySQL storage: reads and writes (evidence: `internal/chat/mysql/repository.go`)
- Server startup → Chat repository: constructs repository (evidence: `cmd/server/main.go`)
- Tool registry → Calendar events: offers calendar tools
- Tool registry → Tasks: offers task tools
- Tool registry → Reminders: offers reminder tools
- Chat runner → Memory and recall: uses recalled context
- Server startup → Google account link: configures account link
- Server startup → Reminders: starts reminder loop (evidence: `cmd/server/main.go`)
- Server startup → Personal profile: runs profile pass (evidence: `cmd/server/main.go`)
- Chat runner → Speech: produces speech
- Chat runner → Announcements: announces outcomes
