Naming conventions

Use these conventions to keep repository names, routes, environment variables, and diagrams predictable across services. They follow the Cloudflare Workers and Pages patterns used by the platform.

---

Repositories and services

• Pattern: ihnyc-rc-<service>
• Set in Wrangler config for each service
• Examples: ihnyc-rc-landing, ihnyc-rc-vote, ihnyc-rc-cal-landing; the decommissioned Gallery used ihnyc-rc-gallery

Sources: ihnyc-rc-landing/wrangler.toml, ihnyc-rc-cal-landing/wrangler.toml, ihnyc-rc-gallery/wrangler.toml, ihnyc-rc-vote/wrangler.jsonc

---

Routes

Admin routes

• Admin UI: /admin
• Admin APIs: /api/admin/*
• Used across services that expose admin tooling

Sources: ihnyc-rc-vote/src/index.ts, ihnyc-rc-vote/src/routes/admin.ts, ihnyc-rc-gallery/src/index.ts, ihnyc-rc-cal-landing/functions/_middleware.ts, ihnyc-rc-cal-landing/functions/api/admin/stats.ts

Public APIs

• Pattern: /api/*
• Used on Pages Functions and Workers

Sources: ihnyc-rc-landing/functions/api/changelog.ts, ihnyc-rc-cal-landing/functions/api/subs/new.ts, ihnyc-rc-gallery/src/index.ts

Calendar feeds

• Pattern: /cal/*.ics
• Examples: /cal/programs.ics, /cal/internal.ics

Sources: ihnyc-rc-cal-landing/functions/cal/programs.ics.ts, ihnyc-rc-cal-landing/functions/cal/internal.ics.ts

Gallery (decommissioned)

• Historical public UI: /gallery, /gallery/:id
• Historical media delivery: /media/*

Sources: ihnyc-rc-gallery/src/index.ts

Vote

• Public UI: /e/* (election pages), /vote/my-elections
• Vote Submission: /e/:id/vote, /e/:id/vote/poll

Sources: ihnyc-rc-vote/src/routes/vote.ts, ihnyc-rc-vote/src/index.ts

---

Environment variables

Pattern

• Uppercase snake_case with semantic prefixes
• Examples: RESEND_API_KEY, FROM_EMAIL, BASE_URL, ADMIN_API_KEY

Sources: ihnyc-rc-vote/.dev.vars.example, ihnyc-rc-vote/README.md

Service-specific variables

Variable	Service	Purpose
N8N_BASE	Calendar	n8n webhook base URL
TURNSTILE_SECRET, TURNSTILE_SITE_KEY	Calendar	Bot protection
PROGRAMS_ICS_KEY	Calendar	ICS file key in R2
PUBLIC_MEDIA_BASE_URL	Gallery (decommissioned)	Historical public media URL
RC_LOGO_URL	Gallery (decommissioned)	Historical logo asset URL
GITHUB_TOKEN	Landing	GitHub API access
CHANGELOG_REPOS	Landing	Repo list for changelog
ANALYTICS_STORE_URL, ANALYTICS_STORE_TOKEN	Landing	Analytics store service

Sources: ihnyc-rc-cal-landing/wrangler.toml, ihnyc-rc-gallery/wrangler.toml, ihnyc-rc-landing/functions/api/changelog.ts, ihnyc-rc-landing/functions/api/publish.ts

---

Architecture diagrams

Diagram types

Type	When to use
flowchart LR	System and service flows
sequenceDiagram	Request and auth flows
erDiagram	DB schema only

Labels

Use human-readable Mermaid labels. Name actors, services, external dependencies, and storage explicitly; keep implementation identifiers in the surrounding prose.

Example:

flowchart LR
  RESIDENT["Resident"]
  LANDING["Resident Council website"]
  GITHUB["GitHub API"]
  STORAGE["R2 changelog cache"]

---

Related

• api-contracts
• security-model
• system-overview