# cel3brimbor/watagent architecture

> Architecture diagram of the GitHub repository cel3brimbor/watagent, 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/cel3brimbor/watagent
- Repository: https://github.com/cel3brimbor/watagent

## Overview

Watagent is a web/native calendar application with Google sign-in, calendar and task management, Google Calendar integration, and an AI chat interface for calendar actions. The main workflow restores or establishes a session, then presents the calendar; users can manage calendar items or use chat and review pending AI changes. The graph shows only relationships visible in the supplied excerpts, SOURCE INDEX references, or explicit calls. Several substantial calendar capabilities are represented, but their internal wiring is not asserted where source was not sampled.

Main entry points: [`src/shared/api-base.ts`](https://github.com/cel3brimbor/watagent/blob/main/src/shared/api-base.ts) (API transport), [`src/calendar/calendar-app.tsx`](https://github.com/cel3brimbor/watagent/blob/main/src/calendar/calendar-app.tsx) (Calendar workspace), [`src/app/page.tsx`](https://github.com/cel3brimbor/watagent/blob/main/src/app/page.tsx) (Home entry), [`src/auth/session.ts`](https://github.com/cel3brimbor/watagent/blob/main/src/auth/session.ts) (Session router)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["App and auth"]
  node_home["Home entry<br/>[page.tsx]"]
  node_login["Login screen<br/>[login-screen.tsx]"]
  node_auth["Session router<br/>[session.ts]"]
  node_webauth["Web auth<br/>[web-session.ts]"]
  node_nativeauth["Native auth<br/>[native-session.ts]"]
  node_oauth["Native OAuth<br/>[native-oauth.ts]"]
end

subgraph group_calendar["Calendar management"]
  node_calendarapp["Calendar workspace<br/>[calendar-app.tsx]"]
  node_calendarstate["Calendar state<br/>[store.tsx]"]
  node_calendarviews["Calendar views"]
  node_calendaritems["Calendar item API<br/>[client.ts]"]
  node_googlecal["Google Calendar sync"]
  node_calendarimport["Calendar import"]
  node_preferences["Calendar preferences"]
  node_approvalui["AI approval panel"]
  node_approvalapi["Approval client<br/>[approval-client.ts]"]
end

subgraph group_agent["AI assistant"]
  node_chatpanel["Chat panel"]
  node_chatsessions["Chat snapshots"]
  node_chatstream["Chat stream<br/>[stream.ts]"]
end

subgraph group_platform["Shared platform"]
  node_securestore["Secure token store<br/>[secure-store.ts]"]
  node_apibase["API transport<br/>[api-base.ts]"]
end

node_user(("User"))
node_backend{{"Watagent API"}}
node_google{{"Google Calendar"}}
node_supabase{{"Supabase auth"}}

node_user -->|"opens"| node_home
node_home -->|"restores session"| node_auth
node_home -->|"shows signed out"| node_login
node_home -->|"provides state"| node_calendarstate
node_home -->|"renders"| node_calendarapp
node_login -->|"signs in"| node_auth
node_auth -->|"selects web driver"| node_webauth
node_auth -->|"selects native driver"| node_nativeauth
node_nativeauth -->|"starts OAuth"| node_oauth
node_nativeauth -->|"persists token"| node_securestore
node_webauth -->|"refreshes session"| node_backend
node_nativeauth -->|"authenticates"| node_supabase
node_apibase -->|"gets access token"| node_auth
node_apibase -->|"sends API requests"| node_backend
node_calendaritems -->|"requests item data"| node_apibase
node_googlecal -->|"requests sync"| node_apibase
node_googlecal -->|"parses returned items"| node_calendaritems
node_approvalapi -->|"requests approvals"| node_apibase
node_chatsessions -->|"loads and saves chats"| node_apibase
node_chatpanel -->|"renders"| node_approvalui
node_chatpanel -->|"uses presence behavior"| node_apibase
node_googlecal -->|"connects and syncs"| node_google
node_calendarapp -.-> node_calendarviews
node_calendarapp -.-> node_chatpanel
node_calendarapp -.-> node_googlecal
node_calendarapp -.-> node_calendarimport
node_calendarapp -.-> node_preferences
node_approvalui -.-> node_approvalapi
node_chatpanel -.-> node_chatstream

click node_home "https://github.com/cel3brimbor/watagent/blob/main/src/app/page.tsx"
click node_login "https://github.com/cel3brimbor/watagent/blob/main/src/auth/login-screen.tsx"
click node_auth "https://github.com/cel3brimbor/watagent/blob/main/src/auth/session.ts"
click node_webauth "https://github.com/cel3brimbor/watagent/blob/main/src/auth/web-session.ts"
click node_nativeauth "https://github.com/cel3brimbor/watagent/blob/main/src/auth/native-session.ts"
click node_oauth "https://github.com/cel3brimbor/watagent/blob/main/src/auth/native-oauth.ts"
click node_securestore "https://github.com/cel3brimbor/watagent/blob/main/src/security/secure-store.ts"
click node_calendarapp "https://github.com/cel3brimbor/watagent/blob/main/src/calendar/calendar-app.tsx"
click node_calendarstate "https://github.com/cel3brimbor/watagent/blob/main/src/calendar/store.tsx"
click node_calendarviews "https://github.com/cel3brimbor/watagent/tree/main/src/calendar/views"
click node_calendaritems "https://github.com/cel3brimbor/watagent/blob/main/src/calendar/client.ts"
click node_googlecal "https://github.com/cel3brimbor/watagent/blob/main/src/calendar/google-calendar-client.ts"
click node_calendarimport "https://github.com/cel3brimbor/watagent/blob/main/src/calendar/calendar-import-panel.tsx"
click node_preferences "https://github.com/cel3brimbor/watagent/blob/main/src/calendar/calendar-preferences-doc.ts"
click node_approvalui "https://github.com/cel3brimbor/watagent/blob/main/src/calendar/ai-approval-panel.tsx"
click node_approvalapi "https://github.com/cel3brimbor/watagent/blob/main/src/calendar/approval-client.ts"
click node_chatpanel "https://github.com/cel3brimbor/watagent/blob/main/src/agent/calendar-chat-panel.tsx"
click node_chatsessions "https://github.com/cel3brimbor/watagent/blob/main/src/agent/snapshots-client.ts"
click node_chatstream "https://github.com/cel3brimbor/watagent/blob/main/src/agent/stream.ts"
click node_apibase "https://github.com/cel3brimbor/watagent/blob/main/src/shared/api-base.ts"

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_home,node_login,node_auth,node_webauth,node_nativeauth,node_oauth,node_user toneBlue
class node_calendarapp,node_calendarstate,node_calendarviews,node_calendaritems,node_googlecal,node_calendarimport,node_preferences,node_approvalui,node_approvalapi toneAmber
class node_chatpanel,node_chatsessions,node_chatstream,node_backend toneMint
class node_securestore,node_apibase toneRose
class node_google,node_supabase toneIndigo
```

## Components

### App and auth

- [Home entry](https://github.com/cel3brimbor/watagent/blob/main/src/app/page.tsx): `src/app/page.tsx`
- [Login screen](https://github.com/cel3brimbor/watagent/blob/main/src/auth/login-screen.tsx): `src/auth/login-screen.tsx`
- [Session router](https://github.com/cel3brimbor/watagent/blob/main/src/auth/session.ts): `src/auth/session.ts`
- [Web auth](https://github.com/cel3brimbor/watagent/blob/main/src/auth/web-session.ts): `src/auth/web-session.ts`
- [Native auth](https://github.com/cel3brimbor/watagent/blob/main/src/auth/native-session.ts): `src/auth/native-session.ts`
- [Native OAuth](https://github.com/cel3brimbor/watagent/blob/main/src/auth/native-oauth.ts): `src/auth/native-oauth.ts`

### Calendar management

- [Calendar workspace](https://github.com/cel3brimbor/watagent/blob/main/src/calendar/calendar-app.tsx): `src/calendar/calendar-app.tsx`
- [Calendar state](https://github.com/cel3brimbor/watagent/blob/main/src/calendar/store.tsx): `src/calendar/store.tsx`
- [Calendar views](https://github.com/cel3brimbor/watagent/tree/main/src/calendar/views): `src/calendar/views`
- [Calendar item API](https://github.com/cel3brimbor/watagent/blob/main/src/calendar/client.ts): `src/calendar/client.ts`
- [Google Calendar sync](https://github.com/cel3brimbor/watagent/blob/main/src/calendar/google-calendar-client.ts): `src/calendar/google-calendar-client.ts`
- [Calendar import](https://github.com/cel3brimbor/watagent/blob/main/src/calendar/calendar-import-panel.tsx): `src/calendar/calendar-import-panel.tsx`
- [Calendar preferences](https://github.com/cel3brimbor/watagent/blob/main/src/calendar/calendar-preferences-doc.ts): `src/calendar/calendar-preferences-doc.ts`
- [AI approval panel](https://github.com/cel3brimbor/watagent/blob/main/src/calendar/ai-approval-panel.tsx): `src/calendar/ai-approval-panel.tsx`
- [Approval client](https://github.com/cel3brimbor/watagent/blob/main/src/calendar/approval-client.ts): `src/calendar/approval-client.ts`

### AI assistant

- [Chat panel](https://github.com/cel3brimbor/watagent/blob/main/src/agent/calendar-chat-panel.tsx): `src/agent/calendar-chat-panel.tsx`
- [Chat snapshots](https://github.com/cel3brimbor/watagent/blob/main/src/agent/snapshots-client.ts): `src/agent/snapshots-client.ts`
- [Chat stream](https://github.com/cel3brimbor/watagent/blob/main/src/agent/stream.ts): `src/agent/stream.ts`

### Shared platform

- [Secure token store](https://github.com/cel3brimbor/watagent/blob/main/src/security/secure-store.ts): `src/security/secure-store.ts`
- [API transport](https://github.com/cel3brimbor/watagent/blob/main/src/shared/api-base.ts): `src/shared/api-base.ts`

### Other components

- **User**
- **Watagent API**
- **Google Calendar**
- **Supabase auth**

## Connections

- User → Home entry: opens (evidence: `src/app/page.tsx`)
- Home entry → Session router: restores session (evidence: `src/app/page.tsx`)
- Home entry → Login screen: shows signed out (evidence: `src/app/page.tsx`)
- Home entry → Calendar state: provides state (evidence: `src/app/page.tsx`)
- Home entry → Calendar workspace: renders (evidence: `src/app/page.tsx`)
- Login screen → Session router: signs in (evidence: `src/auth/login-page.tsx`)
- Session router → Web auth: selects web driver (evidence: `src/auth/session.ts`)
- Session router → Native auth: selects native driver (evidence: `src/auth/session.ts`)
- Native auth → Native OAuth: starts OAuth (evidence: `src/auth/native-session.ts`)
- Native auth → Secure token store: persists token (evidence: `src/auth/native-session.ts`)
- Web auth → Watagent API: refreshes session (evidence: `src/auth/web-session.ts`)
- Native auth → Supabase auth: authenticates (evidence: `src/auth/native-session.ts`)
- API transport → Session router: gets access token (evidence: `src/shared/api-base.ts`)
- API transport → Watagent API: sends API requests (evidence: `src/shared/api-base.ts`)
- Calendar item API → API transport: requests item data (evidence: `src/calendar/client.ts`)
- Google Calendar sync → API transport: requests sync (evidence: `src/calendar/google-calendar-client.ts`)
- Google Calendar sync → Calendar item API: parses returned items (evidence: `src/calendar/google-calendar-client.ts`)
- Approval client → API transport: requests approvals (evidence: `src/calendar/approval-client.ts`)
- Chat snapshots → API transport: loads and saves chats (evidence: `src/agent/snapshots-client.ts`)
- Chat panel → AI approval panel: renders (evidence: `src/agent/calendar-chat-panel.tsx`)
- Chat panel → API transport: uses presence behavior (evidence: `src/agent/calendar-chat-panel.tsx`)
- Google Calendar sync → Google Calendar: connects and syncs (evidence: `src/calendar/google-calendar-client.ts`)
- Calendar workspace → Calendar views
- Calendar workspace → Chat panel
- Calendar workspace → Google Calendar sync
- Calendar workspace → Calendar import
- Calendar workspace → Calendar preferences
- AI approval panel → Approval client
- Chat panel → Chat stream
