Skip to content

Commit 14860ad

Browse files
rsmithlalrsmithlal
committed
refactor: Update event flow and documentation to enhance event hosting system clarity
1 parent e0052ed commit 14860ad

File tree

3 files changed

+95
-10
lines changed

3 files changed

+95
-10
lines changed

‎docs/events_flow.mmd‎

Lines changed: 27 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -6,23 +6,33 @@ flowchart TD
66
V1 -->|No| ERR[Validation error]
77
V1 -->|Yes| SAVE[Save]
88

9+
%% Event Hosts System
10+
SAVE --> HOST[Assign Event Hosts]
11+
HOST --> DEFHOST[Set creator as default host]
12+
DEFHOST --> ADDHOST{Additional hosts?}
13+
ADDHOST -->|Yes| HOSTVAL[Validate host types\nHostsEvents concern]
14+
ADDHOST -->|No| HOSTS_DONE[Hosts configured]
15+
HOSTVAL --> EH[Create EventHost records]
16+
EH --> HOSTS_DONE
17+
918
%% Categorize & Media
10-
SAVE --> CAT[Assign categories]
11-
SAVE --> IMG[Attach cover image]
19+
HOSTS_DONE --> CAT[Assign categories]
20+
HOSTS_DONE --> IMG[Attach cover image]
1221

1322
%% Visibility & Scopes
14-
SAVE --> PZ{privacy}
15-
SAVE --> SCOPE{starts_at timing}
23+
CAT --> PZ{privacy}
24+
IMG --> SCOPE{starts_at timing}
1625
SCOPE -->|nil| DRAFT[Draft]
1726
SCOPE -->|>= now| UPCOMING[Upcoming]
1827
SCOPE -->|< now| PAST[Past]
1928

2029
%% Optional Geocoding & Location
21-
SAVE --> GEO[Optional: geocoding job]
22-
SAVE --> LOC[LocatableLocation\npolymorphic]
30+
IMG --> GEO[Optional: geocoding job]
31+
CAT --> LOC[LocatableLocation\npolymorphic]
2332

2433
%% Event Notification System
25-
SAVE --> SCHED[EventReminderSchedulerJob]
34+
LOC --> SCHED[EventReminderSchedulerJob]
35+
PZ --> SCHED
2636
SCHED --> CALC{Calculate reminder times}
2737
CALC --> R24[Schedule 24h reminder]
2838
CALC --> R1[Schedule 1h reminder]
@@ -51,12 +61,20 @@ flowchart TD
5161
EUN --> AC
5262
EUN --> EMAIL
5363

54-
%% Display & Actions
55-
PZ --> SHOW[Show page]
64+
%% Display & Actions with Host Information
65+
PZ --> SHOW[Show page with\nvisible_event_hosts]
5666
UPCOMING --> SHOW
5767
PAST --> SHOW
5868
DRAFT --> SHOW
5969

70+
%% Event Management Authorization
71+
SHOW --> MGMT{Can manage event?}
72+
MGMT --> OWNER[Event creator]
73+
MGMT --> EHAUTH[EventHost authorization\nevent_host_member?]
74+
EHAUTH --> HOSTMGMT[Host can manage]
75+
OWNER --> MANAGE[Edit/Delete event]
76+
HOSTMGMT --> MANAGE
77+
6078
%% RSVP System
6179
SHOW --> AUTH{User authenticated?}
6280
AUTH -->|Yes| RSVP[RSVP Actions]

‎docs/events_flow.png‎

12.8 KB
Loading

‎docs/events_system.md‎

Lines changed: 68 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,10 @@
11
# Events & Calendars
22

3-
This document explains the Event model, how events are created and displayed, how visibility works, how calendars fit in, and the comprehensive notification system for event reminders and updates.
3+
This document explains the Event model, how events are created and displayed, how visibility works, how calendars fit in, the comprehensive notification system for event reminders and updates, and the event hosting system.
44

55
## What's Implemented
66
- **RSVPs/Attendees**: `EventAttendance` model with `person_id`, `event_id`, `status` (interested/going/not_going), guarded by privacy/policy.
7+
- **Event Hosts**: Polymorphic `EventHost` model allowing multiple entities (People, Communities, Organizations) to host events.
78
- **ICS Export**: Export endpoint at `/events/:id/ics` that renders VEVENT from name/description/time/location.
89
- **Event Reminder System**: Comprehensive notification system for upcoming events with multiple delivery channels.
910
- **Event Update Notifications**: Automatic notifications when event details change.
@@ -15,6 +16,72 @@ This document explains the Event model, how events are created and displayed, ho
1516
- **Advanced RSVP Features**: No waitlists, capacity limits, or guest allowances.
1617
- **Bulk Operations**: No bulk event creation, editing, or management tools.
1718

19+
## Event Hosts System
20+
21+
### Overview
22+
Events can have multiple hosts through the polymorphic `EventHost` model. This allows different types of entities (People, Communities, Organizations) to co-host events and share hosting responsibilities.
23+
24+
### Components
25+
- **EventHost Model**: `BetterTogether::EventHost`
26+
- Join model between Events and hosts
27+
- Polymorphic relationship: `belongs_to :host, polymorphic: true`
28+
- Associates: `belongs_to :event`
29+
- Permitted attributes: `host_id`, `host_type`, `event_id`
30+
31+
- **HostsEvents Concern**: `BetterTogether::HostsEvents`
32+
- Must be included in models to permit them as event hosts
33+
- Provides associations: `has_many :event_hosts, as: :host` and `has_many :hosted_events`
34+
- Class method `included_in_models` returns allow-list of valid host types
35+
- Automatically included in `Person`, `Community`, and other hostable models
36+
37+
### Event Hosting Workflow
38+
39+
#### Creating Events with Hosts
40+
1. When creating an event, creator is automatically set as default host
41+
2. Additional hosts can be added through `event_hosts_attributes` in the form
42+
3. Host validation ensures only authorized entities can be assigned as hosts
43+
4. Policy validation through `Pundit.policy_scope!` filters available host options
44+
45+
#### Host Authorization & Permissions
46+
- **Event Host Member Check**: `event_host_member?` method in `EventPolicy`
47+
- Allows host representatives to manage events they're hosting
48+
- Checks if user can represent any of the event's hosts
49+
- Uses `agent.valid_event_host_ids` to determine user's hostable entities
50+
- **CRUD Permissions**: Event hosts can create, read, update, and delete events they host
51+
- **Visibility**: Event hosts are displayed on event pages via `visible_event_hosts` helper
52+
53+
#### Host Display & Interaction
54+
- **Event Cards**: Show host information on event listings
55+
- **Event Details**: Full "Hosted By" section with host cards
56+
- **Authorization Filter**: `visible_event_hosts` helper filters hosts by user permissions
57+
- **Multi-Host Support**: Events can display multiple hosts in responsive grid layout
58+
59+
### Technical Implementation
60+
61+
#### Models & Associations
62+
- **Event Model**: `has_many :event_hosts` and `has_many :hosts, through: :event_hosts`
63+
- **Host Models**: Include `HostsEvents` concern for `event_hosts` and `hosted_events` associations
64+
- **EventHost Model**: Polymorphic join table with validation and permitted attributes
65+
66+
#### Controller Integration
67+
- **EventsController**:
68+
- `build_event_hosts` method for form processing
69+
- `event_host_class` validation with allow-list checking
70+
- Host assignment through permitted parameters
71+
- **Authorization**: Policy-based access control throughout the hosting workflow
72+
73+
#### Views & Helpers
74+
- **Event Forms**: Nested form fields for `event_hosts_attributes`
75+
- **Event Display**: `_event_hosts.html.erb` partial for consistent host display
76+
- **Helper Methods**: `visible_event_hosts` centralizes authorization logic
77+
- **I18n Support**: "Hosted By" labels with full translation coverage
78+
79+
### Security & Validation
80+
- **Host Type Allow-List**: Only models including `HostsEvents` can be event hosts
81+
- **Policy Validation**: All host assignments validated through Pundit policies
82+
- **Authorization Checks**: Host visibility and management permissions enforced
83+
- **Creator Fallback**: Event creator automatically becomes default host
84+
1885
## Event Attendance & RSVPs
1986

2087
## Event Reminder & Notification System

0 commit comments

Comments
 (0)