# emiwe3/wavelength architecture

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

- Interactive diagram: https://gitdiagram.com/emiwe3/wavelength
- Repository: https://github.com/emiwe3/wavelength

## Overview

Wavelength is a student-focused personal assistant that gathers academic and campus information, answers text-based requests, and sends proactive reminders through iMessage. The main interactive flow is the frontend connecting accounts and registering a phone, then backend request handling invoking the agent, which builds cached student context, fetches connected-source data, and returns a response or action. A separate scheduler drives deadline alerts and briefings. The README documents additional image/video, calendar, location, and personalization capabilities; unsampled implementation details and some integration wiring are not asserted beyond that documentation.

Main entry points: [`backend/agent.py`](https://github.com/emiwe3/wavelength/blob/main/backend/agent.py) (Claude assistant), [`backend/scheduler.py`](https://github.com/emiwe3/wavelength/blob/main/backend/scheduler.py) (Reminder scheduler), [`backend/context.py`](https://github.com/emiwe3/wavelength/blob/main/backend/context.py) (Student context), [`backend/db.py`](https://github.com/emiwe3/wavelength/blob/main/backend/db.py) (User and context store)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["User experience"]
  node_web_app["Connection dashboard<br/>[App.jsx]"]
  node_status_card["Connection status<br/>[StatusCard.jsx]"]
end

subgraph group_orchestration["Assistant runtime"]
  node_api["HTTP and auth API<br/>[main.py]"]
  node_agent["Claude assistant<br/>[agent.py]"]
  node_context["Student context<br/>[context.py]"]
  node_database[("User and context store<br/>[db.py]")]
  node_bot["Message bot<br/>[bot.py]"]
end

subgraph group_sources["Academic sources"]
  node_canvas["Canvas data<br/>[canvas.py]"]
  node_calendar_read["Calendar feed sync<br/>[calendar_sync.py]"]
  node_gmail["Gmail data<br/>[gmail.py]"]
  node_slack["Slack sync<br/>[slack_sync.py]"]
end

subgraph group_actions["Actions and reminders"]
  node_calendar_write["Calendar event writer<br/>[calendar_write.py]"]
  node_scheduler["Reminder scheduler<br/>[scheduler.py]"]
  node_messenger["Message delivery<br/>[messenger.py]"]
  node_imessage["iMessage bridge<br/>[imessage.py]"]
  node_audio["Audio transcription<br/>[audio.py]"]
  node_maps["Travel estimates<br/>[maps.py]"]
end

node_student(("Student"))
node_canvas_service{{"Canvas service"}}
node_google_services{{"Google services"}}
node_slack_service{{"Slack service"}}
node_photon{{"Photon iMessage"}}
node_ical{{"iCal feed"}}
node_maps_service{{"Google Maps"}}

node_student -->|"connects accounts"| node_web_app
node_web_app -->|"calls API"| node_api
node_web_app -->|"renders status"| node_status_card
node_api -->|"stores registration"| node_database
node_api -->|"requests reply"| node_agent
node_agent -->|"builds context"| node_context
node_agent -->|"reads cache and preferences"| node_database
node_context -->|"fetches events"| node_calendar_read
node_context -->|"fetches coursework"| node_canvas
node_context -->|"fetches emails"| node_gmail
node_context -->|"fetches announcements"| node_slack
node_context -->|"refreshes credentials"| node_database
node_calendar_read -.->|"reads feed"| node_ical
node_canvas -.->|"retrieves assignments"| node_canvas_service
node_gmail -.->|"retrieves messages"| node_google_services
node_slack -.->|"retrieves posts"| node_slack_service
node_agent -->|"creates events"| node_calendar_write
node_calendar_write -.->|"writes calendar"| node_google_services
node_agent -->|"uses transcription"| node_audio
node_agent -->|"gets travel details"| node_maps
node_maps -.->|"estimates travel"| node_maps_service
node_scheduler -->|"loads users"| node_database
node_scheduler -->|"checks assignments"| node_canvas
node_scheduler -->|"checks events"| node_calendar_read
node_scheduler -->|"drafts reminders"| node_agent
node_scheduler -->|"gets travel estimates"| node_maps
node_scheduler -->|"sends briefings"| node_messenger
node_messenger -.->|"delivers messages"| node_photon
node_bot -->|"requests replies"| node_agent
node_bot -->|"loads user data"| node_database
node_bot -->|"handles messages"| node_imessage
node_imessage -.->|"bridges messaging"| node_photon

click node_web_app "https://github.com/emiwe3/wavelength/blob/main/frontend/src/App.jsx"
click node_status_card "https://github.com/emiwe3/wavelength/blob/main/frontend/src/components/StatusCard.jsx"
click node_api "https://github.com/emiwe3/wavelength/blob/main/backend/main.py"
click node_agent "https://github.com/emiwe3/wavelength/blob/main/backend/agent.py"
click node_context "https://github.com/emiwe3/wavelength/blob/main/backend/context.py"
click node_database "https://github.com/emiwe3/wavelength/blob/main/backend/db.py"
click node_bot "https://github.com/emiwe3/wavelength/blob/main/backend/bot.py"
click node_canvas "https://github.com/emiwe3/wavelength/blob/main/backend/canvas.py"
click node_calendar_read "https://github.com/emiwe3/wavelength/blob/main/backend/calendar_sync.py"
click node_gmail "https://github.com/emiwe3/wavelength/blob/main/backend/gmail.py"
click node_slack "https://github.com/emiwe3/wavelength/blob/main/backend/slack_sync.py"
click node_calendar_write "https://github.com/emiwe3/wavelength/blob/main/backend/calendar_write.py"
click node_scheduler "https://github.com/emiwe3/wavelength/blob/main/backend/scheduler.py"
click node_messenger "https://github.com/emiwe3/wavelength/blob/main/backend/messenger.py"
click node_imessage "https://github.com/emiwe3/wavelength/blob/main/backend/imessage.py"
click node_audio "https://github.com/emiwe3/wavelength/blob/main/backend/audio.py"
click node_maps "https://github.com/emiwe3/wavelength/blob/main/backend/maps.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_web_app,node_status_card toneBlue
class node_api,node_agent,node_context,node_database,node_bot toneAmber
class node_canvas,node_calendar_read,node_gmail,node_slack toneMint
class node_calendar_write,node_scheduler,node_messenger,node_imessage,node_audio,node_maps toneRose
class node_student,node_canvas_service,node_google_services,node_slack_service,node_photon,node_ical,node_maps_service toneIndigo
```

## Components

### User experience

- [Connection dashboard](https://github.com/emiwe3/wavelength/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Connection status](https://github.com/emiwe3/wavelength/blob/main/frontend/src/components/StatusCard.jsx): `frontend/src/components/StatusCard.jsx`

### Assistant runtime

- [HTTP and auth API](https://github.com/emiwe3/wavelength/blob/main/backend/main.py): `backend/main.py`
- [Claude assistant](https://github.com/emiwe3/wavelength/blob/main/backend/agent.py): `backend/agent.py`
- [Student context](https://github.com/emiwe3/wavelength/blob/main/backend/context.py): `backend/context.py`
- [User and context store](https://github.com/emiwe3/wavelength/blob/main/backend/db.py): `backend/db.py`
- [Message bot](https://github.com/emiwe3/wavelength/blob/main/backend/bot.py): `backend/bot.py`

### Academic sources

- [Canvas data](https://github.com/emiwe3/wavelength/blob/main/backend/canvas.py): `backend/canvas.py`
- [Calendar feed sync](https://github.com/emiwe3/wavelength/blob/main/backend/calendar_sync.py): `backend/calendar_sync.py`
- [Gmail data](https://github.com/emiwe3/wavelength/blob/main/backend/gmail.py): `backend/gmail.py`
- [Slack sync](https://github.com/emiwe3/wavelength/blob/main/backend/slack_sync.py): `backend/slack_sync.py`

### Actions and reminders

- [Calendar event writer](https://github.com/emiwe3/wavelength/blob/main/backend/calendar_write.py): `backend/calendar_write.py`
- [Reminder scheduler](https://github.com/emiwe3/wavelength/blob/main/backend/scheduler.py): `backend/scheduler.py`
- [Message delivery](https://github.com/emiwe3/wavelength/blob/main/backend/messenger.py): `backend/messenger.py`
- [iMessage bridge](https://github.com/emiwe3/wavelength/blob/main/backend/imessage.py): `backend/imessage.py`
- [Audio transcription](https://github.com/emiwe3/wavelength/blob/main/backend/audio.py): `backend/audio.py`
- [Travel estimates](https://github.com/emiwe3/wavelength/blob/main/backend/maps.py): `backend/maps.py`

### Other components

- **Student**
- **Canvas service**
- **Google services**
- **Slack service**
- **Photon iMessage**
- **iCal feed**
- **Google Maps**

## Connections

- Student → Connection dashboard: connects accounts (evidence: `README.md`)
- Connection dashboard → HTTP and auth API: calls API (evidence: `frontend/src/App.jsx`)
- Connection dashboard → Connection status: renders status (evidence: `frontend/src/App.jsx`)
- HTTP and auth API → User and context store: stores registration (evidence: `backend/main.py`)
- HTTP and auth API → Claude assistant: requests reply (evidence: `backend/main.py`)
- Claude assistant → Student context: builds context (evidence: `backend/agent.py`)
- Claude assistant → User and context store: reads cache and preferences (evidence: `backend/agent.py`)
- Student context → Calendar feed sync: fetches events (evidence: `backend/context.py`)
- Student context → Canvas data: fetches coursework (evidence: `backend/context.py`)
- Student context → Gmail data: fetches emails (evidence: `backend/context.py`)
- Student context → Slack sync: fetches announcements (evidence: `backend/context.py`)
- Student context → User and context store: refreshes credentials (evidence: `backend/context.py`)
- Calendar feed sync → iCal feed: reads feed
- Canvas data → Canvas service: retrieves assignments
- Gmail data → Google services: retrieves messages
- Slack sync → Slack service: retrieves posts
- Claude assistant → Calendar event writer: creates events (evidence: `backend/agent.py`)
- Calendar event writer → Google services: writes calendar
- Claude assistant → Audio transcription: uses transcription (evidence: `backend/agent.py`)
- Claude assistant → Travel estimates: gets travel details (evidence: `backend/agent.py`)
- Travel estimates → Google Maps: estimates travel
- Reminder scheduler → User and context store: loads users (evidence: `backend/scheduler.py`)
- Reminder scheduler → Canvas data: checks assignments (evidence: `backend/scheduler.py`)
- Reminder scheduler → Calendar feed sync: checks events (evidence: `backend/scheduler.py`)
- Reminder scheduler → Claude assistant: drafts reminders (evidence: `backend/scheduler.py`)
- Reminder scheduler → Travel estimates: gets travel estimates (evidence: `backend/scheduler.py`)
- Reminder scheduler → Message delivery: sends briefings (evidence: `backend/scheduler.py`)
- Message delivery → Photon iMessage: delivers messages
- Message bot → Claude assistant: requests replies (evidence: `backend/bot.py`)
- Message bot → User and context store: loads user data (evidence: `backend/bot.py`)
- Message bot → iMessage bridge: handles messages (evidence: `backend/bot.py`)
- iMessage bridge → Photon iMessage: bridges messaging
