# trinity808/tt-scheduler architecture

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

- Interactive diagram: https://gitdiagram.com/trinity808/tt-scheduler
- Repository: https://github.com/trinity808/tt-scheduler

## Overview

Trinity Dropbox Scheduler processes incoming appointment PDFs into reports and an updated daily schedule, then uploads the schedule and moves the source PDFs. Google Sheets helpers form a separate, apparently optional workflow; the excerpts do not show them being called by the scheduler entry point. The README documents operational alerts and overlap protection, while sampled source confirms startup checks, Dropbox operations, extraction, and document generation; unsampled wiring is not inferred.

Main entry points: [`main.py`](https://github.com/trinity808/tt-scheduler/blob/main/main.py) (Scheduler entry), [`apis/dropbox_api.py`](https://github.com/trinity808/tt-scheduler/blob/main/apis/dropbox_api.py) (Dropbox operations), [`app/ongoing_row_mapper.py`](https://github.com/trinity808/tt-scheduler/blob/main/app/ongoing_row_mapper.py) (Ongoing row mapping), [`app/template_filler.py`](https://github.com/trinity808/tt-scheduler/blob/main/app/template_filler.py) (Report generation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_orchestration["Run control"]
  node_scheduler["Scheduler entry<br/>[main.py]"]
  node_configuration["Runtime configuration<br/>[config_loader.py]"]
  node_health["Health and alerts<br/>[health_monitor.py]"]
end

subgraph group_dropbox["Dropbox exchange"]
  node_dropbox_api["Dropbox operations<br/>[dropbox_api.py]"]
  node_dropbox_service["Dropbox"]
end

subgraph group_documents["Appointment documents"]
  node_pdf_extractor["PDF data extraction<br/>[pdf_extractor.py]"]
  node_report_filler["Report generation<br/>[template_filler.py]"]
  node_schedule_generator["Daily schedule"]
  node_local_documents["Local DOCX files"]
end

subgraph group_sheets["Sheets workflow"]
  node_sheet_mapper["Ongoing row mapping"]
  node_sheet_client["Sheets client<br/>[sheet_client.py]"]
  node_google_sheets["Google Sheets"]
  node_comment_parser["Comment shorthand parser<br/>[comment_parser.py]"]
end

node_scheduler_operator(("Run operator"))

node_scheduler_operator -->|"starts run"| node_scheduler
node_scheduler -->|"loads settings"| node_configuration
node_scheduler -->|"checks and alerts"| node_health
node_scheduler -->|"lists and downloads"| node_dropbox_api
node_dropbox_api -->|"reads files"| node_dropbox_service
node_scheduler -->|"extracts fields"| node_pdf_extractor
node_scheduler -->|"fills template"| node_report_filler
node_report_filler -->|"writes report"| node_local_documents
node_scheduler -->|"checks schedule"| node_dropbox_api
node_scheduler -->|"creates or updates"| node_schedule_generator
node_schedule_generator -->|"writes schedule"| node_local_documents
node_scheduler -->|"uploads schedule"| node_dropbox_api
node_dropbox_api -->|"writes schedule"| node_dropbox_service
node_scheduler -->|"moves processed PDF"| node_dropbox_api
node_dropbox_api -->|"moves file"| node_dropbox_service
node_sheet_mapper -.->|"extracts case data"| node_pdf_extractor
node_sheet_mapper -.->|"finds and updates rows"| node_sheet_client
node_sheet_client -.->|"reads and writes"| node_google_sheets

click node_scheduler "https://github.com/trinity808/tt-scheduler/blob/main/main.py"
click node_configuration "https://github.com/trinity808/tt-scheduler/blob/main/app/config_loader.py"
click node_health "https://github.com/trinity808/tt-scheduler/blob/main/app/health_monitor.py"
click node_dropbox_api "https://github.com/trinity808/tt-scheduler/blob/main/apis/dropbox_api.py"
click node_pdf_extractor "https://github.com/trinity808/tt-scheduler/blob/main/app/pdf_extractor.py"
click node_report_filler "https://github.com/trinity808/tt-scheduler/blob/main/app/template_filler.py"
click node_schedule_generator "https://github.com/trinity808/tt-scheduler/blob/main/app/schedule_generator.py"
click node_sheet_mapper "https://github.com/trinity808/tt-scheduler/blob/main/app/ongoing_row_mapper.py"
click node_sheet_client "https://github.com/trinity808/tt-scheduler/blob/main/app/sheet_client.py"
click node_comment_parser "https://github.com/trinity808/tt-scheduler/blob/main/app/comment_parser.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_scheduler,node_configuration,node_health toneBlue
class node_dropbox_api,node_dropbox_service toneAmber
class node_pdf_extractor,node_report_filler,node_schedule_generator,node_local_documents toneMint
class node_sheet_mapper,node_sheet_client,node_google_sheets,node_comment_parser toneRose
class node_scheduler_operator toneIndigo
```

## Components

### Run control

- [Scheduler entry](https://github.com/trinity808/tt-scheduler/blob/main/main.py): `main.py`
- [Runtime configuration](https://github.com/trinity808/tt-scheduler/blob/main/app/config_loader.py): `app/config_loader.py`
- [Health and alerts](https://github.com/trinity808/tt-scheduler/blob/main/app/health_monitor.py): `app/health_monitor.py`

### Dropbox exchange

- [Dropbox operations](https://github.com/trinity808/tt-scheduler/blob/main/apis/dropbox_api.py): `apis/dropbox_api.py`
- **Dropbox**

### Appointment documents

- [PDF data extraction](https://github.com/trinity808/tt-scheduler/blob/main/app/pdf_extractor.py): `app/pdf_extractor.py`
- [Report generation](https://github.com/trinity808/tt-scheduler/blob/main/app/template_filler.py): `app/template_filler.py`
- [Daily schedule](https://github.com/trinity808/tt-scheduler/blob/main/app/schedule_generator.py): `app/schedule_generator.py`
- **Local DOCX files**

### Sheets workflow

- [Ongoing row mapping](https://github.com/trinity808/tt-scheduler/blob/main/app/ongoing_row_mapper.py): `app/ongoing_row_mapper.py`
- [Sheets client](https://github.com/trinity808/tt-scheduler/blob/main/app/sheet_client.py): `app/sheet_client.py`
- **Google Sheets**
- [Comment shorthand parser](https://github.com/trinity808/tt-scheduler/blob/main/app/comment_parser.py): `app/comment_parser.py`

### Other components

- **Run operator**

## Connections

- Run operator → Scheduler entry: starts run
- Scheduler entry → Runtime configuration: loads settings
- Scheduler entry → Health and alerts: checks and alerts
- Scheduler entry → Dropbox operations: lists and downloads
- Dropbox operations → Dropbox: reads files
- Scheduler entry → PDF data extraction: extracts fields
- Scheduler entry → Report generation: fills template
- Report generation → Local DOCX files: writes report
- Scheduler entry → Dropbox operations: checks schedule
- Scheduler entry → Daily schedule: creates or updates
- Daily schedule → Local DOCX files: writes schedule
- Scheduler entry → Dropbox operations: uploads schedule
- Dropbox operations → Dropbox: writes schedule
- Scheduler entry → Dropbox operations: moves processed PDF
- Dropbox operations → Dropbox: moves file
- Ongoing row mapping → PDF data extraction: extracts case data
- Ongoing row mapping → Sheets client: finds and updates rows
- Sheets client → Google Sheets: reads and writes