Find your way around

A tour of the repo

The repository is one pnpm + Turborepo monorepo. Everything that runs is under apps/, everything the apps compose is under packages/, and the tooling that keeps it honest sits at the root. Each row links to the page that explains it.

For the whole layout, package by package, see Monorepo & packages.

Frontend and components

For building or changing what the site looks like — components, themes, layout and motion. Start with Installation if the repo is not running yet.

1. Component system — how a component is put together, where it is registered and how theming reaches it. Everything else assumes this.
2. UI components overview — the design system as you will use it, and where to browse the catalogues.
3. Theming & colour sets — the colour-set axis that sets a surface's colours, and how ELB's brand layer re-skins it.
4. Token pipeline — where every value a component binds comes from, from Figma to CSS variable.
5. Create a component — the steps, from scaffold to registered and tested.
6. Refactor a component — reviewing against Figma, and the traps of building against ELB's forks of Ghost.
7. Responsive rungs and Motion — the two design-owned rule sets every new layout and animation must follow.
8. Testing — unit, story and e2e tests, and what each is for.

Content model and CMS

For changing what editors can author in Contentful and how the site reads it.

1. Content model — the model as code: migrations, the schema, fragments and transforms, and why Contentful is never edited by hand.
2. Content models — the content types themselves, to look up what exists before adding to it.
3. Change the content model — the steps for a new field or type, end to end, including this site's own migrations in migrations/club/.
4. Domains & bolt-ons — which domain owns each type, and why that decides where a migration goes.
5. Dictionary keys — interface copy: the keys in code, the labels in Contentful.
6. Rich text rendering — how an article body becomes components, embedded entries included.
7. @v4/model — the package's exports, subpaths and commands.

Pages, routes and basketball data

For adding pages, changing how they load data, and working on the basketball areas.

1. Site map — every page of the site and its address: start here to see where a new page belongs.
2. App & rendering — how the thin app mounts route packages and how data reaches a page.
3. Domains & bolt-ons — route packages, routes.json and the generated shims.
4. Add a page or route — the steps, including the data-area routes.
5. Competition sections — the address rules every page follows, and how the chrome follows the section.
6. Basketball and the Competition Engine — the data areas, the engine integration, live data and the Game Centre.
7. @v4/basketball-app and @v4/competition-engine — the route package and the data seam, in detail.
8. Caching & revalidation — tags, lifetimes and the webhook, for both Contentful and engine data.
9. Local basketball data — running the engine on your machine.

Release and operations

For getting work merged, released and running in an environment.

1. Branching & Git — the branch model, commit messages with their Jira key, and how work lands.
2. Pull requests & gates — what CI checks on every pull request, and how it merges.
3. GitHub Actions — what each workflow runs and when.
4. Releasing — cutting a release and its changelog.
5. Environments & secrets — which environments exist and where their secrets live.
6. Deployment — Flightcontrol hosting and the model deploy pipeline.
7. Environment variables — every variable, and what switches each integration on.
8. Troubleshooting — the failures that recur, and their fixes.
9. Take template updates — taking the template's changes in as a /sync-upstream pull request, and what they never touch.

QA and editors

For testing the site and authoring it, without reading code.

1. Site map — every page a reader can reach and the address it lives at.
2. What the site does — every feature area with its status: the first stop for "does the site do X?".
3. Content & publishing — the page types and blocks an editor works with, and how a published change goes live.
4. Competition sections — which address a page gets, and which Contentful field decides it.
5. Sport — the basketball pages, the Game Centre, live scores and the widgets on editorial pages.
6. The video section — the video pages and playback.
7. Content models — every content type and field, to check what an editor can set.
8. Accessibility — the accessibility bar every component ships to, and how it is checked.
9. Glossary — the house terms these docs use.