# sheyabernstein/family-birthdays architecture

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

- Interactive diagram: https://gitdiagram.com/sheyabernstein/family-birthdays
- Repository: https://github.com/sheyabernstein/family-birthdays

## Overview

Family Birthdays is a multi-tenant Django application for recording family life events and delivering Hebrew-calendar-aware reminders. Members sign in by passwordless email or SMS, access a private family tree according to their role, and manage notification subscriptions. The reminder workflow computes recurring occurrences from Hebrew dates, resolves recipients and channels, renders messages, then sends them by email or SMS; observances shifted off Shabbos or Yom Tov are a documented capability. The README documents additional tree, privacy, and broadcast features. Sampled excerpts are partial, so uncertain view-to-model wiring is omitted.

Main entry points: [`notifications/tasks.py`](https://github.com/sheyabernstein/family-birthdays/blob/main/notifications/tasks.py) (Occurrence and send tasks), [`family/views.py`](https://github.com/sheyabernstein/family-birthdays/blob/main/family/views.py) (Family views), [`notifications/services.py`](https://github.com/sheyabernstein/family-birthdays/blob/main/notifications/services.py) (Render and delivery), [`accounts/views.py`](https://github.com/sheyabernstein/family-birthdays/blob/main/accounts/views.py) (Sign-in views)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_access["Accounts and access"]
  node_accounts_views["Sign-in views<br/>[views.py]"]
  node_account_models[("Accounts<br/>[models.py]")]
  node_magic_links["Magic links<br/>[magic_links.py]"]
  node_account_tasks["Sign-in delivery task<br/>[tasks.py]"]
  node_tenant_views["Tenant views<br/>[views.py]"]
  node_tenant_access["Tenant permissions<br/>[permissions.py]"]
end

subgraph group_family["Family records"]
  node_family_views["Family views<br/>[views.py]"]
  node_family_models[("People and unions<br/>[models.py]")]
  node_family_access["Family access rules<br/>[access.py]"]
  node_hebrew_dates["Hebrew date math<br/>[hebrew.py]"]
  node_tree_chart["Tree chart<br/>[tree_chart.py]"]
end

subgraph group_reminders["Reminder lifecycle"]
  node_notification_views["Notification views<br/>[views.py]"]
  node_notification_models[("Events and messages<br/>[models.py]")]
  node_occurrence_tasks["Occurrence and send tasks<br/>[tasks.py]"]
  node_audience["Audience resolution<br/>[audience.py]"]
  node_delivery["Render and delivery<br/>[services.py]"]
  node_sms_backend["SMS backend<br/>[sms.py]"]
end

subgraph group_runtime["Runtime services"]
  node_celery["Celery workers<br/>[celery.py]"]
  node_postgres[("PostgreSQL")]
end

node_member(("Family member"))
node_email_service["Email service"]
node_sms_provider["SMS provider"]
node_hdate["hdate library"]

node_member -->|"requests sign-in"| node_accounts_views
node_member -->|"switches families"| node_tenant_views
node_member -->|"manages tree"| node_family_views
node_member -->|"manages subscriptions"| node_notification_views
node_accounts_views -->|"requests link"| node_magic_links
node_accounts_views -->|"queues delivery"| node_account_tasks
node_account_tasks -->|"sends sign-in"| node_delivery
node_tenant_views -->|"checks access"| node_tenant_access
node_family_views -->|"checks access"| node_family_access
node_family_views -->|"renders tree"| node_tree_chart
node_family_views -->|"formats dates"| node_hebrew_dates
node_occurrence_tasks -->|"reads people and unions"| node_family_models
node_occurrence_tasks -->|"reads event types"| node_notification_models
node_occurrence_tasks -->|"writes occurrences and messages"| node_notification_models
node_occurrence_tasks -->|"computes dates"| node_hebrew_dates
node_hebrew_dates -->|"uses calendar math"| node_hdate
node_occurrence_tasks -->|"resolves recipients"| node_audience
node_occurrence_tasks -->|"renders and sends"| node_delivery
node_delivery -->|"sends email"| node_email_service
node_delivery -->|"dispatches SMS"| node_sms_backend
node_sms_backend -.->|"sends SMS"| node_sms_provider
node_celery -->|"runs tasks"| node_occurrence_tasks
node_celery -->|"runs tasks"| node_account_tasks
node_family_views -->|"reads and writes"| node_postgres
node_notification_views -->|"uses notification data"| node_notification_models
node_occurrence_tasks -->|"persists task data"| node_postgres

click node_accounts_views "https://github.com/sheyabernstein/family-birthdays/blob/main/accounts/views.py"
click node_account_models "https://github.com/sheyabernstein/family-birthdays/blob/main/accounts/models.py"
click node_magic_links "https://github.com/sheyabernstein/family-birthdays/blob/main/accounts/magic_links.py"
click node_account_tasks "https://github.com/sheyabernstein/family-birthdays/blob/main/accounts/tasks.py"
click node_tenant_views "https://github.com/sheyabernstein/family-birthdays/blob/main/tenants/views.py"
click node_tenant_access "https://github.com/sheyabernstein/family-birthdays/blob/main/tenants/permissions.py"
click node_family_views "https://github.com/sheyabernstein/family-birthdays/blob/main/family/views.py"
click node_family_models "https://github.com/sheyabernstein/family-birthdays/blob/main/family/models.py"
click node_family_access "https://github.com/sheyabernstein/family-birthdays/blob/main/family/access.py"
click node_hebrew_dates "https://github.com/sheyabernstein/family-birthdays/blob/main/family/hebrew.py"
click node_tree_chart "https://github.com/sheyabernstein/family-birthdays/blob/main/family/tree_chart.py"
click node_notification_views "https://github.com/sheyabernstein/family-birthdays/blob/main/notifications/views.py"
click node_notification_models "https://github.com/sheyabernstein/family-birthdays/blob/main/notifications/models.py"
click node_occurrence_tasks "https://github.com/sheyabernstein/family-birthdays/blob/main/notifications/tasks.py"
click node_audience "https://github.com/sheyabernstein/family-birthdays/blob/main/notifications/audience.py"
click node_delivery "https://github.com/sheyabernstein/family-birthdays/blob/main/notifications/services.py"
click node_sms_backend "https://github.com/sheyabernstein/family-birthdays/blob/main/notifications/sms.py"
click node_celery "https://github.com/sheyabernstein/family-birthdays/blob/main/config/celery.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_accounts_views,node_account_models,node_magic_links,node_account_tasks,node_tenant_views,node_tenant_access toneBlue
class node_family_views,node_family_models,node_family_access,node_hebrew_dates,node_tree_chart toneAmber
class node_notification_views,node_notification_models,node_occurrence_tasks,node_audience,node_delivery,node_sms_backend toneMint
class node_celery,node_postgres toneRose
class node_member,node_email_service,node_sms_provider,node_hdate toneIndigo
```

## Components

### Accounts and access

- [Sign-in views](https://github.com/sheyabernstein/family-birthdays/blob/main/accounts/views.py): `accounts/views.py`
- [Accounts](https://github.com/sheyabernstein/family-birthdays/blob/main/accounts/models.py): `accounts/models.py`
- [Magic links](https://github.com/sheyabernstein/family-birthdays/blob/main/accounts/magic_links.py): `accounts/magic_links.py`
- [Sign-in delivery task](https://github.com/sheyabernstein/family-birthdays/blob/main/accounts/tasks.py): `accounts/tasks.py`
- [Tenant views](https://github.com/sheyabernstein/family-birthdays/blob/main/tenants/views.py): `tenants/views.py`
- [Tenant permissions](https://github.com/sheyabernstein/family-birthdays/blob/main/tenants/permissions.py): `tenants/permissions.py`

### Family records

- [Family views](https://github.com/sheyabernstein/family-birthdays/blob/main/family/views.py): `family/views.py`
- [People and unions](https://github.com/sheyabernstein/family-birthdays/blob/main/family/models.py): `family/models.py`
- [Family access rules](https://github.com/sheyabernstein/family-birthdays/blob/main/family/access.py): `family/access.py`
- [Hebrew date math](https://github.com/sheyabernstein/family-birthdays/blob/main/family/hebrew.py): `family/hebrew.py`
- [Tree chart](https://github.com/sheyabernstein/family-birthdays/blob/main/family/tree_chart.py): `family/tree_chart.py`

### Reminder lifecycle

- [Notification views](https://github.com/sheyabernstein/family-birthdays/blob/main/notifications/views.py): `notifications/views.py`
- [Events and messages](https://github.com/sheyabernstein/family-birthdays/blob/main/notifications/models.py): `notifications/models.py`
- [Occurrence and send tasks](https://github.com/sheyabernstein/family-birthdays/blob/main/notifications/tasks.py): `notifications/tasks.py`
- [Audience resolution](https://github.com/sheyabernstein/family-birthdays/blob/main/notifications/audience.py): `notifications/audience.py`
- [Render and delivery](https://github.com/sheyabernstein/family-birthdays/blob/main/notifications/services.py): `notifications/services.py`
- [SMS backend](https://github.com/sheyabernstein/family-birthdays/blob/main/notifications/sms.py): `notifications/sms.py`

### Runtime services

- [Celery workers](https://github.com/sheyabernstein/family-birthdays/blob/main/config/celery.py): `config/celery.py`
- **PostgreSQL**

### Other components

- **Family member**
- **Email service**
- **SMS provider**
- **hdate library**

## Connections

- Family member → Sign-in views: requests sign-in
- Family member → Tenant views: switches families
- Family member → Family views: manages tree
- Family member → Notification views: manages subscriptions
- Sign-in views → Magic links: requests link
- Sign-in views → Sign-in delivery task: queues delivery
- Sign-in delivery task → Render and delivery: sends sign-in
- Tenant views → Tenant permissions: checks access
- Family views → Family access rules: checks access
- Family views → Tree chart: renders tree
- Family views → Hebrew date math: formats dates
- Occurrence and send tasks → People and unions: reads people and unions
- Occurrence and send tasks → Events and messages: reads event types
- Occurrence and send tasks → Events and messages: writes occurrences and messages
- Occurrence and send tasks → Hebrew date math: computes dates
- Hebrew date math → hdate library: uses calendar math
- Occurrence and send tasks → Audience resolution: resolves recipients
- Occurrence and send tasks → Render and delivery: renders and sends
- Render and delivery → Email service: sends email
- Render and delivery → SMS backend: dispatches SMS
- SMS backend → SMS provider: sends SMS
- Celery workers → Occurrence and send tasks: runs tasks
- Celery workers → Sign-in delivery task: runs tasks
- Family views → PostgreSQL: reads and writes
- Notification views → Events and messages: uses notification data
- Occurrence and send tasks → PostgreSQL: persists task data