IHNYC RC Calendar System

• Service Name: ihnyc-rc-cal-landing
• Live Site: https://calendar.ihnyc-rc.org
• Repository: https://github.com/dghauri0/ihnyc-rc-cal-landing.git

🧭 Overview

• Cloudflare Pages site with Pages Functions
• Programs calendar uses magic-link verification and token-gated ICS
• Internal calendar feed proxies to n8n
• Turnstile and Mixpanel integrations for bot protection and analytics
• Middleware redirects to /subscribe for onboarding

Sources: ihnyc-rc-cal-landing/wrangler.toml, ihnyc-rc-cal-landing/functions/_middleware.ts, ihnyc-rc-cal-landing/README.md

👥 Key User Flows

Programs Subscription Flow

1. User submits email on subscription page
2. Turnstile bot check (if enabled)
3. System sends magic link via Resend
4. User clicks link to verify
5. System mints token stored in D1
6. User receives tokenized ICS URL for calendar app

Internal Calendar Flow

• Admin-only access to /cal/internal.ics
• Proxies to n8n webhook
• Protected via Cloudflare Access at edge

Admin Management

• View subscription stats
• List subscribers
• Revoke or re-enable tokens

Sources: ihnyc-rc-cal-landing/functions/api/subs/new.ts, ihnyc-rc-cal-landing/functions/api/subs/verify.ts, ihnyc-rc-cal-landing/functions/cal/programs.ics.ts, ihnyc-rc-cal-landing/functions/cal/internal.ics.ts

📚 Detailed Guides

• end-user: How to subscribe, refresh timing, and troubleshooting
• architecture: System overview and routing behavior
• api: Endpoint-level reference
• data: D1 schema and storage model
• integrations: Resend, Turnstile, Mixpanel, n8n
• mixpanel: Event taxonomy and tracking diagrams
• ops: Runbook and operational notes

🔗 Key Routes and Endpoints

🗄️ Data and Storage

Sources: ihnyc-rc-cal-landing/wrangler.toml, ihnyc-rc-cal-landing/schema.sql

ER Diagram (Mermaid)

erDiagram
  subscribers {
    INTEGER id PK
    TEXT email
    TEXT name
    TEXT status
    TEXT created_at
    TEXT updated_at
  }
  calendars {
    TEXT id PK
    TEXT display_name
    TEXT ics_key
    INTEGER is_enabled
    TEXT created_at
    TEXT updated_at
  }
  verify_requests {
    INTEGER id PK
    TEXT email
    TEXT name
    TEXT calendar_id FK
    TEXT code_hash
    TEXT created_at
    TEXT expires_at
    TEXT consumed_at
    TEXT ip_hash
    TEXT ua
  }
  calendar_tokens {
    INTEGER id PK
    INTEGER subscriber_id FK
    TEXT calendar_id FK
    TEXT token_hash
    TEXT created_at
    TEXT expires_at
    TEXT last_seen_at
    TEXT revoked_at
  }
  calendar_access_log {
    INTEGER id PK
    TEXT ts
    TEXT calendar_id FK
    INTEGER token_id FK
    INTEGER status
    TEXT path
    TEXT ua
    TEXT ip_hash
  }

  subscribers ||--o{ calendar_tokens : has
  calendars ||--o{ verify_requests : verifies
  calendars ||--o{ calendar_tokens : issues
  calendars ||--o{ calendar_access_log : logs
  calendar_tokens ||--o{ calendar_access_log : used_by

Sources: ihnyc-rc-cal-landing/schema.sql

🔄 Automations and Integrations

Email Delivery

• Resend: Magic-link email delivery
• Configured via RESEND_API_KEY and FROM_EMAIL

Bot Protection

• Turnstile: Bot checks in programs subscription flow
• Activated when TURNSTILE_SECRET is set

Analytics

• Mixpanel: Event tracking with hashed distinct_id
• Logs subscription events and verification

n8n Integration

• Internal calendar feed proxies to n8n webhook
• Internal subscription flow triggers n8n workflow

Sources: ihnyc-rc-cal-landing/functions/api/subs/new.ts, ihnyc-rc-cal-landing/functions/api/turnstile-site-key.ts, ihnyc-rc-cal-landing/functions/_lib/mixpanel.ts, ihnyc-rc-cal-landing/functions/cal/internal.ics.ts

🗺️ Service Flow Diagram

Calendar service architecture and integrations

flowchart LR
  subgraph Users
    U_RES["USER: Resident"]
    U_ADMIN["USER: Admin"]
    U_CAL["USER: Calendar Client"]
  end

  subgraph Services
    S_CAL["SVC: ihnyc-rc-cal-landing"]
  end

  subgraph External_Systems
    EXT_RESEND["EXT: Resend"]
    EXT_TURNSTILE["EXT: Cloudflare Turnstile"]
    EXT_MIXPANEL["EXT: Mixpanel"]
    EXT_N8N["EXT: n8n"]
  end

  subgraph Storage
    STORE_D1["STORE: D1"]
    STORE_R2["STORE: R2"]
  end

  U_RES -->|subscribe| S_CAL
  U_ADMIN -->|admin| S_CAL
  U_CAL -->|fetch ICS| S_CAL

  S_CAL -->|subscriptions| STORE_D1
  S_CAL -->|read ICS| STORE_R2

  S_CAL -->|email| EXT_RESEND
  S_CAL -->|verify| EXT_TURNSTILE
  S_CAL -->|analytics| EXT_MIXPANEL
  S_CAL -->|proxy| EXT_N8N

Sources: ihnyc-rc-cal-landing/functions/api/subs/new.ts, ihnyc-rc-cal-landing/functions/api/subs/verify.ts, ihnyc-rc-cal-landing/functions/cal/programs.ics.ts, ihnyc-rc-cal-landing/functions/cal/internal.ics.ts, ihnyc-rc-cal-landing/wrangler.toml

🛠️ Common Ops

Local Development

npx wrangler pages dev public

Deployment

npx wrangler pages deploy public

Upload ICS File to R2

npx wrangler r2 object put ihnyc-calendars/programs.ics --file ./programs.ics

Sources: ihnyc-rc-cal-landing/README.md

🔐 Environment Variables

Sources: ihnyc-rc-cal-landing/wrangler.toml, ihnyc-rc-cal-landing/README.md

❓ Open Questions

Production Configuration

• Are /admin* and /subscribe-internal* protected by Cloudflare Access in production?

Sources: ihnyc-rc-cal-landing/README.md

🔗 Related

• system-overview
• api-contracts
• security-model
• ihnyc-rc-landing
• ihnyc-rc-vote
• ihnyc-rc-gallery