Webscan Documentation
Lesson 1 · The webscan mental model
Phase 1 · Foundations — Lesson 1 of 21 · All lessons
Objective: understand the handful of concepts everything in webscan is built on, so that every screen you meet later already makes sense.
Before you start: just a webscan account. If you don't have one yet, that's the next lesson — you can still read this one first.
Why start with concepts?
Webscan has a lot of features — scans, journeys, audits, recordings, monitoring. They can look like separate tools, but they all move a finding along the same line:
Organization → Project → Website → Scan → Finding → Verdict → Issue → Fix → Retest
Learn that line once and the whole product falls into place. Every feature is either a different way to produce findings, or a step in acting on them.
The containers: where your work lives
These three nest inside each other. You set them up once and then mostly forget about them.
- Organization — your workspace and the billing boundary. Your plan, your team, and everything below it belong to an organization. Most people need only one; agencies create one per client.
- Project — a grouping inside an organization, usually one product or one client engagement. Issues and reports are organised per project.
- Website — a single site you scan, with a base URL, an environment (development / staging / production) and a page limit. A project can hold several websites (e.g. a marketing site and an app).
Think of it as folders: the organization is the drawer, the project is the folder, the website is the document you actually work on.
The work: how a barrier becomes a fix
Once you have a website, everything else is about finding accessibility barriers and closing them.
- Scan — one run of the automated checker against a website. It renders your pages in a real browser and runs the axe-core rules plus webscan's own checks.
- Finding — a single problem the scan reported on a specific page (for example, "button has no accessible name"). A scan produces many findings.
- Verdict — your judgement on a finding: is it a Confirmed barrier, a False positive, something you'll Accept / won't fix, or does it Need more info? Automated tools flag candidates; a human decides. Lesson 6 covers this in depth.
- Issue — a finding (or several) promoted into something trackable, with an owner, a status, comments, and evidence. Issues are how fixing actually gets managed.
- Fix & Retest — you resolve the issue (optionally with webscan's AI assistance and a GitHub pull request), then retest to prove the barrier is really gone before you close it.
Everything advanced you'll learn later — authenticated scans, journeys, recordings, manual audits — is just another source of findings that then flows down this same path.
The one decision that matters early: environment
When you add a website you'll label it development, staging, or production. This isn't just a tag — it controls how boldly webscan is allowed to interact with the site (its "blast radius").
- On development/staging, webscan can explore and click freely.
- On production, it holds back from actions that could change real data unless you explicitly allow them.
For learning, always point webscan at a development/staging site or a site you own. We'll return to this properly in Phase 5, but keep it in mind from day one.
Tips & pitfalls
- Don't over-structure at the start. One organization, one project, one website is the right amount to begin with. You can reorganise later.
- A finding is not yet a verdict. Automated results always include some noise; the verdict step is where you (or your team) turn raw output into truth.
- Findings flow, they don't get stranded. If you learn a feature later and wonder "what do I do with what it found?" — the answer is almost always "give it a verdict, then make it an issue."
Recap
- Webscan nests Organization → Project → Website.
- A Scan produces Findings; you give each a Verdict; real ones become Issues; issues get Fixed and Retested.
- Every advanced feature is just another way to produce findings on that same line.
- Environment decides how aggressively webscan may act on a site.
Try it yourself
Write down, in one sentence each: the organization, project, and website you intend to use webscan for. Pick the environment you'll practise on (ideally not production). You'll create these for real in the next two lessons.