Naming Conventions

🧭 Overview

• Consistent naming across repos, routes, env vars, and diagrams
• Enforces predictable patterns for admin routes and APIs
• Follows Cloudflare Workers/Pages conventions

---

🧩 Repos and Service Names

• Pattern: ihnyc-rc-<service>
• Set in Wrangler config for each service
• Examples: ihnyc-rc-landing, ihnyc-rc-vote, ihnyc-rc-cal-landing, 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

• Public UI: /gallery, /gallery/:id
• 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 Variable Names

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	Public media URL
RC_LOGO_URL	Gallery	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

---

🗺️ Diagram Style (Vault Standard)

Diagram Best Practices

Use consistent Mermaid styles across all vault documentation

Diagram Types

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

Node Labels

Standard prefixes for clarity:

• USER: — User actors
• SVC: — Services
• EXT: — External systems
• STORE: — Storage layers

Example:

flowchart LR
  U_RES["USER: Resident"]
  S_LANDING["SVC: ihnyc-rc-landing"]
  EXT_GITHUB["EXT: GitHub API"]
  STORE_R2["STORE: R2"]

---

🔗 Related

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