# jimdan-panda/calm-hypatia architecture

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

- Interactive diagram: https://gitdiagram.com/jimdan-panda/calm-hypatia
- Repository: https://github.com/jimdan-panda/calm-hypatia

## Overview

This tool archives Okta System Log events to Google Drive, with CLI and browser-dashboard entry points. A run chooses a date window, authenticates to Okta, fetches events, partitions them into deduplicated weekly JSON or CSV files, optionally uploads them into Shared Drive folders, and records a high-watermark for later runs. Progress can be shown in the terminal or streamed to the dashboard. The graph follows documented and excerpted calls; some partitioning and upload orchestration details are only partially shown, so uncertain links are marked unverified.

Main entry points: [`sync_manager.py`](https://github.com/jimdan-panda/calm-hypatia/blob/main/sync_manager.py) (Sync Manager), [`web_ui.py`](https://github.com/jimdan-panda/calm-hypatia/blob/main/web_ui.py) (Web Dashboard), [`main.py`](https://github.com/jimdan-panda/calm-hypatia/blob/main/main.py) (CLI), [`src/progress.py`](https://github.com/jimdan-panda/calm-hypatia/blob/main/src/progress.py) (Progress Reporter)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User Interfaces"]
  node_cli["CLI<br/>[main.py]"]
  node_dashboard["Web Dashboard<br/>[web_ui.py]"]
  node_event_stream["Dashboard Event Stream<br/>[web_ui.py]"]
end

subgraph group_runtime["Sync Runtime"]
  node_sync["Sync Manager<br/>[sync_manager.py]"]
  node_progress["Progress Reporter<br/>[progress.py]"]
end

subgraph group_archive["Archival"]
  node_partitioner["Partition &amp; Export<br/>[partitioner.py]"]
  node_local_files["Local Archive Files"]
  node_state[("High-Watermark State<br/>[state_manager.py]")]
end

subgraph group_services["External Services"]
  node_okta_auth["Okta Authentication<br/>[okta_client.py]"]
  node_okta_logs["Okta Log Fetch<br/>[okta_client.py]"]
  node_drive_auth["Drive Authentication<br/>[gdrive_client.py]"]
  node_drive_folders["Drive Folder Management<br/>[gdrive_client.py]"]
  node_drive_upload["Drive File Upload<br/>[gdrive_client.py]"]
end

node_user(("Operator"))
node_shared_drive[("Google Shared Drive")]
node_okta_service["Okta System Log API"]

node_user -->|"runs"| node_cli
node_user -->|"opens"| node_dashboard
node_cli -->|"runs sync"| node_sync
node_cli -->|"launches"| node_dashboard
node_dashboard -->|"starts sync"| node_sync
node_sync -->|"reads checkpoint"| node_state
node_sync -->|"records run"| node_state
node_sync -->|"authenticates"| node_okta_auth
node_sync -->|"fetches logs"| node_okta_logs
node_okta_auth -->|"requests tokens"| node_okta_service
node_okta_logs -->|"queries events"| node_okta_service
node_sync -.->|"partitions events"| node_partitioner
node_partitioner -->|"writes exports"| node_local_files
node_sync -->|"authenticates"| node_drive_auth
node_sync -->|"gets or creates"| node_drive_folders
node_sync -->|"uploads files"| node_drive_upload
node_drive_folders -->|"organizes folders"| node_shared_drive
node_drive_upload -->|"stores exports"| node_shared_drive
node_sync -->|"reports status"| node_progress
node_progress -->|"emits updates"| node_event_stream
node_event_stream -->|"streams progress"| node_dashboard

click node_cli "https://github.com/jimdan-panda/calm-hypatia/blob/main/main.py"
click node_dashboard "https://github.com/jimdan-panda/calm-hypatia/blob/main/web_ui.py"
click node_sync "https://github.com/jimdan-panda/calm-hypatia/blob/main/sync_manager.py"
click node_okta_auth "https://github.com/jimdan-panda/calm-hypatia/blob/main/src/okta_client.py"
click node_okta_logs "https://github.com/jimdan-panda/calm-hypatia/blob/main/src/okta_client.py"
click node_partitioner "https://github.com/jimdan-panda/calm-hypatia/blob/main/src/partitioner.py"
click node_state "https://github.com/jimdan-panda/calm-hypatia/blob/main/src/state_manager.py"
click node_drive_auth "https://github.com/jimdan-panda/calm-hypatia/blob/main/src/gdrive_client.py"
click node_drive_folders "https://github.com/jimdan-panda/calm-hypatia/blob/main/src/gdrive_client.py"
click node_drive_upload "https://github.com/jimdan-panda/calm-hypatia/blob/main/src/gdrive_client.py"
click node_progress "https://github.com/jimdan-panda/calm-hypatia/blob/main/src/progress.py"
click node_event_stream "https://github.com/jimdan-panda/calm-hypatia/blob/main/web_ui.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_cli,node_dashboard,node_event_stream toneBlue
class node_sync,node_progress,node_shared_drive toneAmber
class node_partitioner,node_local_files,node_state,node_okta_service toneMint
class node_okta_auth,node_okta_logs,node_drive_auth,node_drive_folders,node_drive_upload toneRose
class node_user toneIndigo
```

## Components

### User Interfaces

- [CLI](https://github.com/jimdan-panda/calm-hypatia/blob/main/main.py): `main.py`
- [Web Dashboard](https://github.com/jimdan-panda/calm-hypatia/blob/main/web_ui.py): `web_ui.py`
- [Dashboard Event Stream](https://github.com/jimdan-panda/calm-hypatia/blob/main/web_ui.py): `web_ui.py`

### Sync Runtime

- [Sync Manager](https://github.com/jimdan-panda/calm-hypatia/blob/main/sync_manager.py): `sync_manager.py`
- [Progress Reporter](https://github.com/jimdan-panda/calm-hypatia/blob/main/src/progress.py): `src/progress.py`

### Archival

- [Partition & Export](https://github.com/jimdan-panda/calm-hypatia/blob/main/src/partitioner.py): `src/partitioner.py`
- **Local Archive Files**
- [High-Watermark State](https://github.com/jimdan-panda/calm-hypatia/blob/main/src/state_manager.py): `src/state_manager.py`

### External Services

- [Okta Authentication](https://github.com/jimdan-panda/calm-hypatia/blob/main/src/okta_client.py): `src/okta_client.py`
- [Okta Log Fetch](https://github.com/jimdan-panda/calm-hypatia/blob/main/src/okta_client.py): `src/okta_client.py`
- [Drive Authentication](https://github.com/jimdan-panda/calm-hypatia/blob/main/src/gdrive_client.py): `src/gdrive_client.py`
- [Drive Folder Management](https://github.com/jimdan-panda/calm-hypatia/blob/main/src/gdrive_client.py): `src/gdrive_client.py`
- [Drive File Upload](https://github.com/jimdan-panda/calm-hypatia/blob/main/src/gdrive_client.py): `src/gdrive_client.py`

### Other components

- **Operator**
- **Google Shared Drive**
- **Okta System Log API**

## Connections

- Operator → CLI: runs (evidence: `main.py`)
- Operator → Web Dashboard: opens (evidence: `web_ui.py`)
- CLI → Sync Manager: runs sync (evidence: `main.py`)
- CLI → Web Dashboard: launches (evidence: `main.py`)
- Web Dashboard → Sync Manager: starts sync (evidence: `web_ui.py`)
- Sync Manager → High-Watermark State: reads checkpoint (evidence: `sync_manager.py`)
- Sync Manager → High-Watermark State: records run (evidence: `sync_manager.py`)
- Sync Manager → Okta Authentication: authenticates (evidence: `sync_manager.py`)
- Sync Manager → Okta Log Fetch: fetches logs (evidence: `sync_manager.py`)
- Okta Authentication → Okta System Log API: requests tokens (evidence: `src/okta_client.py`)
- Okta Log Fetch → Okta System Log API: queries events (evidence: `README.md`)
- Sync Manager → Partition & Export: partitions events (evidence: `sync_manager.py`)
- Partition & Export → Local Archive Files: writes exports (evidence: `src/partitioner.py`)
- Sync Manager → Drive Authentication: authenticates (evidence: `sync_manager.py`)
- Sync Manager → Drive Folder Management: gets or creates (evidence: `sync_manager.py`)
- Sync Manager → Drive File Upload: uploads files (evidence: `sync_manager.py`)
- Drive Folder Management → Google Shared Drive: organizes folders (evidence: `README.md`)
- Drive File Upload → Google Shared Drive: stores exports (evidence: `README.md`)
- Sync Manager → Progress Reporter: reports status (evidence: `sync_manager.py`)
- Progress Reporter → Dashboard Event Stream: emits updates (evidence: `web_ui.py`)
- Dashboard Event Stream → Web Dashboard: streams progress (evidence: `web_ui.py`)
