# samcooksdc/hilldesk architecture

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

- Interactive diagram: https://gitdiagram.com/samcooksdc/hilldesk
- Repository: https://github.com/samcooksdc/hilldesk

## Overview

HillDesk is a private-office scheduling workflow: Outlook messages are ingested, screened without AI, converted into structured draft candidates, and presented for staff review before events are committed. Approved events then support calendar operations, recurring series, contact linking, briefings, exports, and House floor context. The central orchestration and several model/provider modules are evidenced by excerpts or the source index; UI and authentication details are included at subsystem level where implementation was not sampled.

Main entry points: [`apps/email_processing/tasks/pipeline.py`](https://github.com/samcooksdc/hilldesk/blob/main/apps/email_processing/tasks/pipeline.py) (Pipeline task), [`apps/event_management/tasks.py`](https://github.com/samcooksdc/hilldesk/blob/main/apps/event_management/tasks.py) (Event background tasks), [`apps/api/services.py`](https://github.com/samcooksdc/hilldesk/blob/main/apps/api/services.py) (Review services), [`apps/event_management/models.py`](https://github.com/samcooksdc/hilldesk/blob/main/apps/event_management/models.py) (Events and series)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingestion["Mail Intake"]
  node_graph["Graph client<br/>[graph_client.py]"]
  node_reception["Reception sync<br/>[reception.py]"]
  node_rawmail[("Message ledger<br/>[models.py]")]
  node_funnel["Deterministic funnel<br/>[engine.py]"]
  node_filterlog[("Filter audit<br/>[models.py]")]
end

subgraph group_review["Extraction Review"]
  node_pipeline["Pipeline task<br/>[pipeline.py]"]
  node_channels["Mail channels"]
  node_llm["Extraction providers"]
  node_schema["Candidate schema<br/>[schema.py]"]
  node_candidates[("Draft candidates<br/>[models.py]")]
  node_reviewui["Review workflow<br/>[views.py]"]
  node_api_services["Review services<br/>[services.py]"]
end

subgraph group_events["Scheduling"]
  node_eventdata[("Events and series<br/>[models.py]")]
  node_calendar["Calendar interface<br/>[calendar_views.py]"]
  node_contacts["Contact matching<br/>[services.py]"]
  node_exports["Briefings and exports<br/>[export_service.py]"]
  node_eventtasks["Event background tasks<br/>[tasks.py]"]
end

subgraph group_identity["Office Access"]
  node_auth["Authentication and security<br/>[models.py]"]
  node_permissions["Access permissions<br/>[permissions.py]"]
end

subgraph group_operations["External Context"]
  node_floor["House floor feeds"]
  node_proceedings["Floor proceedings"]
end

node_staff(("Office staff"))
node_outlook["Outlook mailbox"]
node_floor_source["House legislative feeds"]

node_outlook -->|"provides mail"| node_graph
node_reception -.->|"fetches messages"| node_graph
node_reception -.->|"records messages"| node_rawmail
node_rawmail -->|"enqueues processing"| node_pipeline
node_pipeline -->|"screens message"| node_funnel
node_funnel -->|"writes stage audit"| node_filterlog
node_pipeline -->|"parses channels"| node_channels
node_pipeline -->|"extracts candidates"| node_llm
node_llm -.->|"validates output"| node_schema
node_pipeline -->|"persists drafts"| node_candidates
node_staff -->|"reviews drafts"| node_reviewui
node_reviewui -.->|"invokes review actions"| node_api_services
node_api_services -.->|"commits decisions"| node_eventdata
node_api_services -->|"resolves contacts"| node_contacts
node_staff -.->|"manages schedule"| node_calendar
node_calendar -.->|"reads and updates events"| node_eventdata
node_eventtasks -->|"renders briefings"| node_exports
node_exports -->|"reads event data"| node_eventdata
node_staff -.->|"signs in"| node_auth
node_permissions -->|"checks identities"| node_auth
node_eventtasks -->|"refreshes schedule"| node_floor
node_eventtasks -->|"refreshes feed"| node_proceedings
node_floor -.->|"fetches schedule"| node_floor_source
node_proceedings -->|"fetches proceedings"| node_floor_source

click node_graph "https://github.com/samcooksdc/hilldesk/blob/main/apps/email_processing/graph_client.py"
click node_reception "https://github.com/samcooksdc/hilldesk/blob/main/apps/email_processing/tasks/reception.py"
click node_rawmail "https://github.com/samcooksdc/hilldesk/blob/main/apps/email_processing/models.py"
click node_funnel "https://github.com/samcooksdc/hilldesk/blob/main/apps/email_processing/funnel/engine.py"
click node_filterlog "https://github.com/samcooksdc/hilldesk/blob/main/apps/email_processing/models.py"
click node_pipeline "https://github.com/samcooksdc/hilldesk/blob/main/apps/email_processing/tasks/pipeline.py"
click node_channels "https://github.com/samcooksdc/hilldesk/tree/main/apps/email_processing/channels"
click node_llm "https://github.com/samcooksdc/hilldesk/tree/main/apps/email_processing/llm_providers"
click node_schema "https://github.com/samcooksdc/hilldesk/blob/main/apps/email_processing/llm_providers/schema.py"
click node_candidates "https://github.com/samcooksdc/hilldesk/blob/main/apps/email_processing/models.py"
click node_reviewui "https://github.com/samcooksdc/hilldesk/blob/main/apps/api/views.py"
click node_api_services "https://github.com/samcooksdc/hilldesk/blob/main/apps/api/services.py"
click node_eventdata "https://github.com/samcooksdc/hilldesk/blob/main/apps/event_management/models.py"
click node_calendar "https://github.com/samcooksdc/hilldesk/blob/main/apps/event_management/views/calendar_views.py"
click node_contacts "https://github.com/samcooksdc/hilldesk/blob/main/apps/contacts/services.py"
click node_exports "https://github.com/samcooksdc/hilldesk/blob/main/apps/event_management/services/export_service.py"
click node_eventtasks "https://github.com/samcooksdc/hilldesk/blob/main/apps/event_management/tasks.py"
click node_auth "https://github.com/samcooksdc/hilldesk/blob/main/apps/authentication/models.py"
click node_permissions "https://github.com/samcooksdc/hilldesk/blob/main/apps/authentication/permissions.py"
click node_floor "https://github.com/samcooksdc/hilldesk/blob/main/apps/event_management/services/house_floor_service.py"
click node_proceedings "https://github.com/samcooksdc/hilldesk/blob/main/apps/event_management/services/house_floor_proceedings_service.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_graph,node_reception,node_rawmail,node_funnel,node_filterlog toneBlue
class node_pipeline,node_channels,node_llm,node_schema,node_candidates,node_reviewui,node_api_services toneAmber
class node_eventdata,node_calendar,node_contacts,node_exports,node_eventtasks toneMint
class node_auth,node_permissions toneRose
class node_floor,node_proceedings,node_staff,node_outlook,node_floor_source toneIndigo
```

## Components

### Mail Intake

- [Graph client](https://github.com/samcooksdc/hilldesk/blob/main/apps/email_processing/graph_client.py): `apps/email_processing/graph_client.py`
- [Reception sync](https://github.com/samcooksdc/hilldesk/blob/main/apps/email_processing/tasks/reception.py): `apps/email_processing/tasks/reception.py`
- [Message ledger](https://github.com/samcooksdc/hilldesk/blob/main/apps/email_processing/models.py): `apps/email_processing/models.py`
- [Deterministic funnel](https://github.com/samcooksdc/hilldesk/blob/main/apps/email_processing/funnel/engine.py): `apps/email_processing/funnel/engine.py`
- [Filter audit](https://github.com/samcooksdc/hilldesk/blob/main/apps/email_processing/models.py): `apps/email_processing/models.py`

### Extraction Review

- [Pipeline task](https://github.com/samcooksdc/hilldesk/blob/main/apps/email_processing/tasks/pipeline.py): `apps/email_processing/tasks/pipeline.py`
- [Mail channels](https://github.com/samcooksdc/hilldesk/tree/main/apps/email_processing/channels): `apps/email_processing/channels`
- [Extraction providers](https://github.com/samcooksdc/hilldesk/tree/main/apps/email_processing/llm_providers): `apps/email_processing/llm_providers`
- [Candidate schema](https://github.com/samcooksdc/hilldesk/blob/main/apps/email_processing/llm_providers/schema.py): `apps/email_processing/llm_providers/schema.py`
- [Draft candidates](https://github.com/samcooksdc/hilldesk/blob/main/apps/email_processing/models.py): `apps/email_processing/models.py`
- [Review workflow](https://github.com/samcooksdc/hilldesk/blob/main/apps/api/views.py): `apps/api/views.py`
- [Review services](https://github.com/samcooksdc/hilldesk/blob/main/apps/api/services.py): `apps/api/services.py`

### Scheduling

- [Events and series](https://github.com/samcooksdc/hilldesk/blob/main/apps/event_management/models.py): `apps/event_management/models.py`
- [Calendar interface](https://github.com/samcooksdc/hilldesk/blob/main/apps/event_management/views/calendar_views.py): `apps/event_management/views/calendar_views.py`
- [Contact matching](https://github.com/samcooksdc/hilldesk/blob/main/apps/contacts/services.py): `apps/contacts/services.py`
- [Briefings and exports](https://github.com/samcooksdc/hilldesk/blob/main/apps/event_management/services/export_service.py): `apps/event_management/services/export_service.py`
- [Event background tasks](https://github.com/samcooksdc/hilldesk/blob/main/apps/event_management/tasks.py): `apps/event_management/tasks.py`

### Office Access

- [Authentication and security](https://github.com/samcooksdc/hilldesk/blob/main/apps/authentication/models.py): `apps/authentication/models.py`
- [Access permissions](https://github.com/samcooksdc/hilldesk/blob/main/apps/authentication/permissions.py): `apps/authentication/permissions.py`

### External Context

- [House floor feeds](https://github.com/samcooksdc/hilldesk/blob/main/apps/event_management/services/house_floor_service.py): `apps/event_management/services/house_floor_service.py`
- [Floor proceedings](https://github.com/samcooksdc/hilldesk/blob/main/apps/event_management/services/house_floor_proceedings_service.py): `apps/event_management/services/house_floor_proceedings_service.py`

### Other components

- **Office staff**
- **Outlook mailbox**
- **House legislative feeds**

## Connections

- Outlook mailbox → Graph client: provides mail (evidence: `README.md`)
- Reception sync → Graph client: fetches messages
- Reception sync → Message ledger: records messages
- Message ledger → Pipeline task: enqueues processing (evidence: `apps/email_processing/tasks/pipeline.py`)
- Pipeline task → Deterministic funnel: screens message (evidence: `apps/email_processing/tasks/pipeline.py`)
- Deterministic funnel → Filter audit: writes stage audit (evidence: `apps/email_processing/funnel/engine.py`)
- Pipeline task → Mail channels: parses channels (evidence: `apps/email_processing/tasks/pipeline.py`)
- Pipeline task → Extraction providers: extracts candidates (evidence: `apps/email_processing/tasks/pipeline.py`)
- Extraction providers → Candidate schema: validates output (evidence: `apps/email_processing/llm_providers/__init__.py`)
- Pipeline task → Draft candidates: persists drafts (evidence: `apps/email_processing/tasks/pipeline.py`)
- Office staff → Review workflow: reviews drafts (evidence: `README.md`)
- Review workflow → Review services: invokes review actions
- Review services → Events and series: commits decisions (evidence: `apps/api/services.py`)
- Review services → Contact matching: resolves contacts (evidence: `apps/api/services.py`)
- Office staff → Calendar interface: manages schedule
- Calendar interface → Events and series: reads and updates events
- Event background tasks → Briefings and exports: renders briefings (evidence: `apps/event_management/tasks.py`)
- Briefings and exports → Events and series: reads event data (evidence: `apps/event_management/services/export_service.py`)
- Office staff → Authentication and security: signs in
- Access permissions → Authentication and security: checks identities (evidence: `apps/authentication/permissions.py`)
- Event background tasks → House floor feeds: refreshes schedule (evidence: `apps/event_management/tasks.py`)
- Event background tasks → Floor proceedings: refreshes feed (evidence: `apps/event_management/tasks.py`)
- House floor feeds → House legislative feeds: fetches schedule
- Floor proceedings → House legislative feeds: fetches proceedings
