Directory
All 158 pages of the handbook, in reading order. Every one of them is free to read and needs no account.
Part 0
Welcome
What this handbook is, how it is organised, and how to read it.
- How to use this handbookThe page types, the audience labels, the callouts, and the conventions this handbook follows so you can read it quickly.
- Words you will see everywhereThe handful of VGSpartans terms that turn up on every page, and where the full glossary lives.
- ChangelogWhat changed in VGSpartans, release by release, and what it means for the people using it.
Part 1
Getting started
Three first-day walkthroughs: one for students, one for admins, one for developers.
- Getting startedunfinishedThree first-day walkthroughs, one for each kind of person who uses VGSpartans.
- For adminsunfinishedYour first day with an admin account: getting in, finding the console, and handling your first case.
- Your first day as an adminunfinishedGetting into the admin console for the first time, including the browser check that guards it.
- A tour of the admin consoleunfinishedEvery panel in the admin console and what it is for.
- Your first moderation caseunfinishedWorking one item from the moderation queue end to end.
- For developersunfinishedFrom a fresh machine to a running local copy of the whole platform.
- Setting up your machineunfinishedOne script installs Node, pnpm, the workspace and the browsers the tests need.
- Running it locallyunfinishedWhat `pnpm dev` starts, on which addresses, and how to boot more of the platform.
- Making your first changeunfinishedA small change, from branch to pull request, with every check that has to pass.
- A tour of the codebaseunfinishedWhere everything lives in the workspace, and why it is split the way it is.
- For studentsunfinishedYour first hour on VGSpartans: signing in, finding your way around, and knowing who to ask.
- Your first sign-inunfinishedHow to sign in to VGSpartans for the first time with your school email.
- A tour of the hubunfinishedWhat is on the hub board after you sign in, and what each card takes you to.
- Set up your accountunfinishedYour profile, your display name, your avatar, and the security settings worth turning on.
- Getting helpunfinishedWhere to ask when something is confusing, broken, or wrong.
Part 2
Platform guides
One chapter per platform: what it is, how to use it, who can do what, and what breaks.
- Platform guidesunfinishedOne chapter for each platform that makes up VGSpartans.
- CoreunfinishedThe apex site, the account system, and the admin and developer consoles.
- Using CoreunfinishedWhat you can do in Core and how to do it.
- Roles in CoreunfinishedWho can do what in Core, and how those permissions are decided.
- Core under the hoodunfinishedHow Core is built: its worker, its data, and its moving parts.
- Troubleshooting CoreunfinishedThings that go wrong in Core, what causes them, and how to fix them.
- VGAdvisorThe console a member of staff opens for whatever the school has given them, assembled from modules the platforms contribute.
- VGSitesunfinishedPersonal pages for students and staff, built and published from a dashboard.
- Using VGSitesunfinishedWhat you can do in VGSites and how to do it.
- Roles in VGSitesunfinishedWho can do what in VGSites, and how those permissions are decided.
- VGSites under the hoodunfinishedHow VGSites is built: its worker, its data, and its moving parts.
- Troubleshooting VGSitesunfinishedThings that go wrong in VGSites, what causes them, and how to fix them.
- VGClubsunfinishedA real website for every club, run by elected student webmasters.
- Using VGClubsunfinishedWhat you can do in VGClubs and how to do it.
- Roles in VGClubsunfinishedWho can do what in VGClubs, and how those permissions are decided.
- VGClubs under the hoodunfinishedHow VGClubs is built: its worker, its data, and its moving parts.
- Troubleshooting VGClubsunfinishedThings that go wrong in VGClubs, what causes them, and how to fix them.
- Advising a clubWhat a club advisor can see and do, where each of those controls lives, and how they seat the student officers.
- The webmaster consoleunfinishedThe club site builder: pages, events, news, officers and photos.
- The treasurer consoleunfinishedThe club's money screens and what a treasurer is allowed to record.
- The secretary consoleunfinishedThe club's minutes and membership screens.
- VGWikiunfinishedThe campus encyclopedia, written and kept current by Spartans.
- Using VGWikiunfinishedWhat you can do in VGWiki and how to do it.
- Roles in VGWikiunfinishedWho can do what in VGWiki, and how those permissions are decided.
- VGWiki under the hoodunfinishedHow VGWiki is built: its worker, its data, and its moving parts.
- Troubleshooting VGWikiunfinishedThings that go wrong in VGWiki, what causes them, and how to fix them.
- The VGWiki editorunfinishedWriting and editing an article, and what happens to your text when you save.
- Searching VGWikiunfinishedHow VGWiki search works and what it can and cannot find.
- VGWritesunfinishedA private writing space for students, with a shared word editor.
- Using VGWritesunfinishedWhat you can do in VGWrites and how to do it.
- Roles in VGWritesunfinishedWho can do what in VGWrites, and how those permissions are decided.
- VGWrites under the hoodunfinishedHow VGWrites is built: its worker, its data, and its moving parts.
- Troubleshooting VGWritesunfinishedThings that go wrong in VGWrites, what causes them, and how to fix them.
- VGSynergyunfinishedPrivate circles for collaboration, gated by member approval.
- Using VGSynergyunfinishedWhat you can do in VGSynergy and how to do it.
- Roles in VGSynergyunfinishedWho can do what in VGSynergy, and how those permissions are decided.
- VGSynergy under the hoodunfinishedHow VGSynergy is built: its worker, its data, and its moving parts.
- Troubleshooting VGSynergyunfinishedThings that go wrong in VGSynergy, what causes them, and how to fix them.
- VGAgoraunfinishedThe campus discussion board, organised into fixed categories.
- Using VGAgoraunfinishedWhat you can do in VGAgora and how to do it.
- Roles in VGAgoraunfinishedWho can do what in VGAgora, and how those permissions are decided.
- VGAgora under the hoodunfinishedHow VGAgora is built: its worker, its data, and its moving parts.
- Troubleshooting VGAgoraunfinishedThings that go wrong in VGAgora, what causes them, and how to fix them.
- VGNewsThe student newsroom on its own subdomain, with bylines, section desks, and an editor's approval in front of everything that publishes.
- Using VGNewsFiling a story in one of the five formats, running the budget, and what happens to a reader's tip.
- Roles in VGNewsReporter, editor, editor in chief and adviser, what each one can do, and how a story moves between them.
- VGNews under the hoodThe two-axis state model, the scan-first ordering that stops an unscanned story publishing, and the one function that decides who can read what.
- Troubleshooting VGNewsunfinishedThings that go wrong in VGNews, what causes them, and how to fix them.
- VGGalleryunfinishedThe campus photo and art gallery. Designed, not yet built.
- Using VGGalleryPutting up your own work on the arts wall, shooting and publishing a campus album, and what the crew reviews.
- Roles in VGGalleryunfinishedWho can do what in VGGallery, and how those permissions are decided.
- VGGallery under the hoodunfinishedHow VGGallery is built: its worker, its data, and its moving parts.
- Troubleshooting VGGalleryunfinishedThings that go wrong in VGGallery, what causes them, and how to fix them.
Part 3
Administration
The role model, the consoles, moderation, and the settings that govern the school.
- AdministrationunfinishedThe role model behind VGSpartans, and the consoles that act on it.
- The consolesunfinishedEvery authenticated management surface on the platform, and who reaches it.
- The admin consoleunfinishedThe school admin console, panel by panel.
- The developer consoleThe highest-privilege console on the platform, the two independent locks in front of it, and the manual setup one of them needs.
- The club consolesunfinishedThe four club officer consoles and what separates them.
- The bug bounty consoleThe invite-only, time-boxed security research programme, its access model, and the runbook for provisioning and ending access.
- ModerationOne pipeline checks every piece of text, every image and every video on every platform. This is how it decides, and what an admin's part in it is.
- Working the moderation queueunfinishedTaking a case, reading the evidence, and recording an outcome.
- Take-downsunfinishedRemoving content for real, what is preserved first, and how to undo it.
- Troubleshooting moderationunfinishedWhen the pipeline flags the wrong thing, or nothing at all.
- Managing peopleunfinishedFinding an account, changing what it can do, and ending its access.
- Platform settingsunfinishedThe settings that govern the whole school, where they live, and how to change one.
- The school registryunfinishedThe one file that says which platforms a school runs and on which domains.
Part 4
Security
How sign-in, sessions, devices, bots, privacy and content safety actually work.
- SecurityunfinishedHow VGSpartans protects accounts, content and privacy, and what it deliberately does not try to protect against.
- The threat modelunfinishedWho this platform is defending against, and what it accepts it cannot stop.
- Signing inunfinishedWhat happens between typing your email and being signed in.
- MFA and passkeysunfinishedThe second factor: when it is required, and the forms it can take.
- Sessions and devicesWhat a signed-in session is, how long it lasts, the three layers that tie it to the device that created it, and every event that ends one.
- CryptographyWhich algorithm protects which secret, the parameters it runs at, where every key comes from, and why each choice went the way it did.
- Admin browser attestationThe browser check in front of the highest-privilege consoles, what each of its four tests actually looks at, and the levers that stop it locking the team out.
- Bot protectionThe human checks a public form runs before it accepts a submission, how they stack, and how each one fails.
- Rate limitingunfinishedWhat is limited, by how much, and what a limited request sees.
- Detail privacyWhy the platform stores one-way tokens instead of raw addresses and devices for one account, and exactly what that buys.
- Audit and anomaly detectionunfinishedWhat gets recorded, and what the platform does when a pattern looks wrong.
- Content safetyunfinishedThe automated checks every piece of content passes through.
- Email securityunfinishedHow login mail is sent, and what stops it being forged or lost.
- Privacy and regulationsunfinishedWhat the platform collects, why, and the rights it honours voluntarily.
- Reporting a vulnerabilityunfinishedHow to report a security problem, and what happens after you do.
Part 5
Architecture
How a request travels, how the workers split, and why each big decision went the way it did.
- ArchitectureunfinishedOne picture of how VGSpartans fits together, and an analogy for the shape of it.
- Life of a requestunfinishedEverything that happens between a click and a page appearing.
- The gatewayunfinishedThe single edge worker that decides which platform answers a request.
- The multi-worker splitWhy VGSpartans runs as nine separate programs instead of one, how they talk to each other, and where identity lives.
- The monorepounfinishedHow the workspace is laid out and what belongs where.
- DataEvery database, bucket and cache the platform binds, what lives in each, and how they are kept in step.
- Auth internalsunfinishedHow identity actually works underneath the sign-in screen.
- RenderingunfinishedWhat is built ahead of time, what is rendered per request, and why.
- The design systemunfinishedThe tokens, the stylesheets, and the rules that keep the platform looking like one thing.
- EmailunfinishedHow the platform sends mail and what happens when a provider fails.
- AI usageEvery place VGSpartans calls a model, what each call costs, and why the help bubble is proxied through our own worker.
- Design decisionsShort records of the decisions that shaped the platform, and why each went the way it did.
- Why the app CSP still allows inline scriptWhat it would cost to remove 'unsafe-inline' from the app Content-Security-Policy, why that price is not worth paying yet, and what is in place instead.
Part 6
Operations
Deploys, migrations, backups, monitoring, and a runbook for every symptom.
- OperationsRunning VGSpartans: deploying it, changing its databases, backing it up, watching it, and fixing it when it breaks.
- Incident runbooksA table of symptoms. Find the one you are seeing, open its runbook, and follow the steps in order.
- Users cannot sign inSign-in is failing for one person or for everyone. Work out which, then which of the four gates in front of it is refusing.
- Locked out of a consoleAn admin or developer console refuses someone who should have access. Four independent gates can do that, and they fail in different ways.
- Emails are not arrivingLogin codes or notifications are not reaching people. Work out whether it is one mailbox or the whole chain, then which transport is failing.
- A page returns an errorunfinishedOne page or route is failing while the rest of the site works.
- The site is slow or downunfinishedThe whole platform is unreachable or crawling.
- Moderation is misbehavingunfinishedContent is being flagged wrongly, or not at all.
- The preview stack is brokenunfinishedThe preview deploy failed, or the preview site does not answer.
- The data looks wrongunfinishedA screen is showing something that does not match reality.
- A suspected security incidentunfinishedSomething suggests an account, a session, or the platform has been compromised.
- DeploysHow code becomes the live site, what runs before it is allowed to, and what a deploy can and cannot undo.
- How a push deploysEvery step between a merge into the production branch and the site changing, in the order they run and why that order matters.
- The preview stackA complete second copy of the platform, on its own domains with its own data and its own credentials, and how it tears itself down.
- Rolling backGetting the live site back to a version that worked, and the asymmetry between code and data that makes it harder than it sounds.
- The egress guardThe default-deny outbound firewall every job that holds a credential runs behind, why it exists, and how to add a host to one when a deploy needs a new endpoint.
- Moving deploy secrets into environmentsA checklist for putting the production and preview deploy jobs behind GitHub environments, what it buys, and the plan requirement that decides whether it is available.
- ProvisioningunfinishedCreating the databases, buckets and namespaces a stack needs.
- MigrationsChanging the shape of a database safely, the one rule that must never be broken, and how a migration is rehearsed before it touches production.
- Backups and restoreWhat is copied, how often, where it goes, what is deliberately not in a backup, and how to put a stack back.
- Secrets managementThe name of every secret the platform reads, where each one is set, and how to rotate it. Names and procedures only, never values.
- MonitoringWhat is watched, where the signals appear, what a healthy platform looks like, and the gaps that are still open.
- What it costsEvery bill behind VGSpartans for a year, how each figure was worked out, and what more funding would buy.
Part 7
Contributing
The workflow, the standards, the tests, and how to write for this handbook.
- ContributingHow work gets into VGSpartans: the branches, the pull requests, the sign-off, and the checks that have to pass.
- Development workflowThe four permanent branches, the route a change takes through them, and the rules that govern each step.
- Code standardsunfinishedThe conventions this codebase holds itself to, and the checks that enforce them.
- Design standardsunfinishedThe rules for anything that renders: where styles live and what never goes in a page.
- AccessibilityThe standard the platform holds to, what the automated checks actually prove, and the gaps we know about.
- Languages and translationHow the site is published in more than one language, where the copy lives, and which names must never be translated.
- TestingunfinishedThe four test suites, what each one covers, and how to run them.
- Adding a subplatformunfinishedEverything a new platform needs, from its worker to its routing.
- Writing documentationThe style guide for this handbook: where pages live, the front-matter, the page anatomy, and the rule against writing anything you have not verified.
- Security policyHow to report a security problem in VGSpartans privately, what is in scope, and what happens after you send it.
Part 8
Reference
The lists: variables, config keys, routes, schemas, codes, tokens and scripts.
- ReferenceunfinishedThe lookup tables: variables, keys, routes, schemas, codes and tokens.
- Environment variablesunfinishedEvery environment variable the platform reads, and what it does.
- Platform config keysunfinishedEvery tunable setting stored in the database, with its default.
- Feature flags and modesunfinishedThe switches that turn parts of the platform on, off, or into observe-only.
- API routesunfinishedEvery endpoint the platform serves, and what it takes.
- Database schemasunfinishedEvery database, every table, and what each one holds.
- Events and audit codesEvery action written to the audit trail, what it means, and how sensitive it is.
- Email templatesunfinishedEvery message the platform sends, and when it sends it.
- Error messagesunfinishedErrors a person can see, what causes each, and what to do.
- Commands and scriptsunfinishedEvery command in the workspace and what it does.
- Design tokensunfinishedEvery colour, size and font variable in the design system.
- Domains and routingunfinishedEvery hostname the platform answers on, and which worker answers it.
- GlossaryunfinishedEvery term and acronym used across VGSpartans, in one alphabetical list.