# Brentwood College School — Website Migration: Project Brief

**Status:** Approved, in build. **Lead:** Adi.
**Launch target:** **August 1, 2026** — the whole schedule is anchored back from this date.
**Nature:** Migration, **not** a redesign. Preserve the current look, feel, and information architecture.

**Design latitude:** Exact visual parity is the goal, but **reasonable changes for better
compatibility, performance, or maintainability are absolutely fine.** Where matching the old design
*exactly* would cost significantly more time than a clean equivalent, **Adi and Rian talk it through**
rather than burning hours pixel-chasing.

**Effort budget (lead guidance):** Target ceiling **~450 hours**. Aim to get the **first complete
draft done in ~300–400 hours**; remaining hours go toward polish and going above-and-beyond on the
build. Use this to steer scope tradeoffs (e.g. the design-latitude calls above).

This brief is the working context for the development team. It captures what the migration is,
what we're migrating *from*, the constraints we discovered during discovery, and the decisions
already made. For deployment/operational commands see `CLAUDE.md` in this folder.

---

## 1. Objective

Migrate Brentwood's public website from a custom Laravel CMS to WordPress, preserving the current
visual identity, while solving three problems that built up over the years:

1. **Platform risk** — the current custom CMS is unmaintainable and is a single point of failure.
2. **Tracking gap** — ad campaigns are not connected to applications, so marketing can't measure
   the funnel from ad → inquiry → application.
3. **Editor friction** — an over-complex permission system and brittle tooling slow marketing down.

Preserve what's working: the current look and feel, the 700+ student blogs (with an SEO uplift
opportunity), the teacher-bio update workflow, and the content-approval process.

---

## 2. Stakeholders

| Who | Role |
|---|---|
| Erin | Brentwood marketing — primary day-to-day contact |
| Tracy | Brentwood marketing — owns the FinalSite account relationship (co-leads the FinalSite discovery call) |
| Ian | Brentwood — discovery/scoping input |
| Brentwood IT | Manages hosting (DigitalOcean); owns the YouTube embeds for ~10% of livestreams |
| Photojournalism teacher | Owns the student-blog workflow — gets a dedicated tutorial video |
| Mike | Original developer of the current custom Laravel CMS |

---

## 3. What we're migrating FROM (current system)

The current site is a **custom Laravel 11 CMS** (a working mirror runs in this project under
`./laravel`, served at `brentwood.demoing.info`). It is bespoke — most features are custom-built
modules rather than off-the-shelf. The data model gives the clearest map of scope. Key Eloquent
models / controllers and their migration target:

| Current CMS concept (Laravel model) | Volume | WordPress target |
|---|---|---|
| `Page` (+ `ContentElement`, `ContentFilter`, `Contentable`, `TextBlock`, `Quote`, `VideoText`) | ~200 pages | Gutenberg / ACF blocks |
| `Blog` | **700+** student blog posts | Posts (URL/author/date/tag preserved; + auto-archiving — see §6) |
| `StaffProfile` / `StaffProfileList` | **168** teacher bios | `Staff` custom post type |
| `Course` / `CourseDescription` / `CourseList` | **141** courses | `Courses` CPT w/ department + grade taxonomy |
| `Timetable` / `TimetableContent` | 1 interactive timetable | **Static image/PDF** (no interactive rebuild — see §6) |
| `Livestream` / `LivestreamList` / `LivestreamRegistration` | livestream module | Livestream CPT + Livestream List block |
| `Calendar` / `GoogleCalendar` | multi-source aggregator | Calendar plugin or custom (see §4) |
| `InquiryForm` / `Inquiry` | inquiry forms | Embedded FinalSite forms (see §4) |
| `Photo` / `PhotoBlock` / `InlinePhoto` / `Slideshow` | photo library | Media library (alt text + captions preserved) |
| `Announcement` | announcements | Posts (news/events/announcements) |
| `PageRedirect` / `PageSlug` | legacy URLs | 301 redirect map |
| `Permission` / `Role` | **118 individual permissions** | ~8 practical roles (see §4) |
| `Tag` / `Taggable` | tagging | Tags w/ tag→section relationships retained |
| `Chat`, `EmbedCode`, `EmbedVideo`, `YoutubeVideo`, `SocialMediaFeed`, `FileUpload`, `Version` | mixed | See notes below |

**Migration approach:** scripted extraction from the current database rebuilds content in
WordPress, followed by a manual cleanup pass on high-traffic pages. We already have the working
mirror, so most discovery is done.

---

## 4. Key constraints & decisions (discovered during discovery)

### FinalSite form integration — the biggest constraint
Brentwood processes applications in **FinalSite**. FinalSite has **no public inbound API** and its
forms don't document support for receiving custom hidden-field data. Data flows *out* of FinalSite,
not in. Consequences:

- **Inquiry/application forms must be embedded FinalSite forms** (code snippet in WordPress). We can
  wrap and style them, but **cannot** replace them with Gravity Forms.
- **First-party journey data** (campaign source, pages visited, multi-session history) is captured by
  our existing **BW Lead AI** plugin. It **cannot** currently be attached inside a FinalSite contact
  record — so we reconstruct journey reporting in **GA4 / Looker Studio** via email-matching.
  **Open task:** investigate whether there's *any* way to push this journey data into FinalSite
  (raise on the discovery call).
- **Per-campaign thank-you pages / conversion events** depend on what the FinalSite embed allows.
- **Non-applicant forms** (gated downloads, RSVPs) can use **Gravity Forms** freely.

**Action item:** discovery call with FinalSite support, co-led with Tracy, to confirm exactly what
the embed and hidden-field options support. Tracking add-ons depend on the outcome.

### Calendar
Not a simple embed — the current calendar aggregates multiple Google Calendars (**Brentwood,
Socials, Admissions, Box Office**) into a unified styled view with per-source color coding,
list/grid layouts, tag filtering, and per-page header/body content. Marketing drops different
calendar instances on different pages with different source combinations.
**Decision:** build a custom calendar matching the existing look 1:1 (multi-source aggregation,
color coding, layouts, tag filtering). This replaces the Simple Calendar Pro plugin option.

### Livestreams
Two paths today:
- **Huddle** handles ~90% (all sports), owns its own player/embed — keep embedding as-is, no
  integration needed.
- A **custom YouTube-based module** handles the remaining ~10% (graduation, regatta, TEDx, arts):
  banners, tags, scheduled date/time, **automatic live/completed state**, photo galleries, and
  reusable list blocks surfacing upcoming/completed/ongoing streams across pages.

**Decision:** rebuild the module (CPT + metadata, single page with auto live/completed state,
Livestream List block with filtering) and migrate existing entries. **Excluded** (present in code
but appear unused): real-time chat, RSVP/reminders, login-gated streams. Add later if confirmed used.

**Still unclear:** we don't yet fully understand how Brentwood's livestream workflow actually
operates day-to-day (including the "old system" they've referenced for posting some streams). Expect
to learn more during migration — treat the above as our current best understanding, not final.

### User roles & permissions
Collapse **118 permissions → ~8 practical roles**: Admin (Developer + IT), Marketing (Erin, Tracy),
Teachers (own bios), plus WordPress core roles as needed. The **7–8 core admissions/brochure pages**
(home, admissions, academics, arts, athletics, financial info, etc.) are locked to Marketing + Admin;
everyone else is read-only on those. Remaining pages stay on the existing trust-based model.

### Content approval workflow
Use WordPress's native revision + pending-review workflow (most notably for the teacher-bio editor).
Marketing sees a pending queue, reviews/edits, and publishes in one click. No custom dashboard.

### Image optimization
A broken auto-compression tool on the current site caused an "images aren't loading" problem.
**Use the image-optimization feature in our own BW plugin (`bw-dev`)** — install it and set up
image-optimization profiles for the site, rather than a third-party plugin like ShortPixel/Imagify.

---

## 5. Baseline build (in scope)

- **Template system:** header/footer/template areas, color palette + typography + spacing carried
  over from the current site, reusable UI blocks. Gutenberg + a premium theme framework (lifetime
  license). Mobile-first, plugin-compatible, content-management-friendly, no hard-coded content
  except where it makes sense.
- **Structural SEO:** correct heading structure; schema for Organization, EducationalOrganization,
  Person (staff), Course; clean XML sitemap; block thin pages; Open Graph meta; **301 redirect map
  for every legacy URL**; site search.
- **Performance/backups:** image auto-optimization (via the BW plugin — see §4), page caching + CDN,
  daily DB backups + weekly full-site backups stored off-server and verified restorable.
- **Content migration:** ~200 pages, 700+ blogs, 168 bios, 141 courses, photo library (see §3).
- **Post types & templates:** Posts, Staff, Courses (index + single templates, thumbnails,
  categorization, excerpts).
- **Training & handover:** 2-hour recorded editor session (5–10 staff); dedicated student-blog
  workflow video for the photojournalism teacher; documented image/video specs with upload
  validation; living admin documentation; 30-day post-launch bug-fix window.
- **Launch:** redirect verification, SEO continuity check, tracking validation, form testing.

---

## 6. Selected add-ons (confirmed in scope)

- Custom Calendar matching the existing look 1:1 (replaces the plugin option)
- Per-page footer images (ACF field)
- Google Login (matches current login experience)
- Video Hero Block (autoplay, mute toggle, fallback image — matches the existing `/giving` example)
- Campaign-Variant Inquiry Forms + Thank-You Pages *(FinalSite-constrained — confirm in discovery call)*
- GA4 + GTM + Meta Pixel baseline with per-form conversion events + cross-domain to the app platform
- First-Party Journey Tracking — **this is our existing BW Lead AI plugin**; set it up and configure
  it for the site (landing page, UTMs, referrer, multi-session history in a first-party cookie).
  *FinalSite-constrained — see the open task in §4.*
- Campaign Landing Page Template System (marketing self-serve clone for ad pushes)
- Looker Studio Reporting Dashboard (ad spend → inquiry → application funnel, per campaign)
- **Blog auto-archiving (added post-approval):** a configurable setting (N years) that filters blog
  posts older than the threshold out of on-site post queries/listings, **while keeping them published
  and reachable via Google/search** (not unpublished, not noindexed).

**Timetable:** Brentwood opted **not** to do an interactive/hard-coded timetable build. The timetable
will simply be a **static image or PDF** on the page.

**Considered but NOT in scope** (may return as future work): teacher-bio self-service editor,
form-gated downloads, faculty schema AI/GEO uplift, student-blog SEO uplift, internal announcements
module.

---

## 7. Open questions to resolve

- **Livestream workflow** — how the current livestream system actually works isn't fully understood
  yet (including the "old system" referenced for posting some streams). Expect to discover details
  during migration.
- **FinalSite embed capabilities** — pending the discovery call (gates the tracking add-ons).
- **Getting BW Lead AI journey data into FinalSite** — investigate whether it's possible at all.

*(Resolved: `Volleyball.brentwood.ca` is being dropped — no action needed.)*

---

## 8. Timeline

Anchored to the **August 1, 2026** launch; everything else is scheduled back from there.

| Milestone | Target |
|---|---|
| Discovery + add-on confirmation | Week 1 |
| Staging environment + content migration script | Weeks 2–4 |
| Custom post types + template build | Weeks 3–5 |
| Content cleanup pass + editor tooling | Weeks 5–7 |
| Tracking integration | Weeks 4–8 |
| QA, training, stakeholder review | up to launch |
| **Launch** | **August 1, 2026** |
| 30-day bug-fix window | Through early September 2026 |

The August 1 launch is the hard constraint driving the schedule (more buffer than the original
mid-July target allowed).

---

## 9. Assumptions & exclusions

**Assumptions:**
- Hosting target is **DigitalOcean** (see the deployment pipeline in §10).
- Brand assets (logos, typography, approved photography) are provided by Brentwood.
- These third-party platforms stay on their current systems (not in scope, integration touchpoints
  only): LMS/Moodle, advancement/`giving.brentwood.ca`, Huddle (sports streams), MySchool SIS,
  MailChimp parent newsletter.

**Not included:**
- Visual redesign or new information architecture (but see **Design latitude** at the top)
- School store / e-commerce (future project)
- New photography or video production
- Paid-media strategy (the tracking work makes it measurable later)

---

## 10. Environments & deployment pipeline

**dev → staging → live:**

| Environment | Where | Role |
|---|---|---|
| **Dev** | `mosiah` (this server) | Active development. WordPress target at `https://brentwoodwp.demoing.info`. |
| **Staging** | DigitalOcean (to be set up) | Client review / pre-launch. Linked from mosiah. |
| **Live** | DigitalOcean | Production at launch (staging promotes to / becomes live). |

The source and target both live co-located under `/srv/apps/brentwood/` on mosiah:

| Path | What | URL |
|---|---|---|
| `./laravel` | Working mirror of the **current** Laravel CMS (migration source) | `https://brentwood.demoing.info` |
| `./wp` | **WordPress** target (migration destination) | `https://brentwoodwp.demoing.info` |

WordPress has its own isolated database (`wp-db`), separate from the Laravel app's MySQL, so
migration work can't affect the source mirror. Both demoing.info sites sit behind the shared access
gate (ask the team for the password). See `CLAUDE.md` for `srv-gw` operational commands.

**Infrastructure to set up:**
- Provision a DigitalOcean droplet for **staging** (→ later **live**), and link to it from mosiah.
- Goal: enable Claude to **SSH into the DigitalOcean box** for deploys/management. *(When we wire this
  up we'll do it carefully — SSH key/credential handling gets a security pass before anything is
  stored or exposed.)*