> **DRAFT** — under teacher review. # What Is an Entity? (It's Not Just a Person) The Hamilton and Alexandra College · Year 12 · 2026 On context diagrams and data flow diagrams, students frequently draw only the humans they can think of — *"Student"*, *"Teacher"* — and miss every external system their software talks to. Missing an entity is a rubric error at every level above 3–4, because the rubric rewards *"relationships between the existing system, entities and data flows"*. > [!TIP] > If your context diagram only has *people* as entities, you've almost certainly missed half of them. Every login, every email, every external API your project touches is its own entity. --- ## The VCAA definition > **Entity** — the users or external systems that interact with the system being created. Two words matter: **users** (human roles) and **external systems** (non-human). Both go on your context diagram as rectangles. --- ## Types of entity — with examples | Type | What it is | VCE SAT examples | |---|---|---| | **Human user (primary)** | The person the software is primarily built for | Student, Teacher, Administrator | | **Human user (secondary)** | A person affected by the system's outputs | Parent, School Principal | | **External software system** | An API, platform, or service your system sends data to or receives data from | Google Calendar API, Payment Gateway, Email Server | | **External data source** | A data feed or file system outside your application boundary | School database, CSV import, Government open data | --- ## A quick test: is it an entity? ::: success Ask three questions: 1. Does it send data **into** my system, or receive data **out** of it? 2. Is it **outside** the boundary of the software I am building? 3. Is it a **distinct role or system** (not an internal component of my software)? If all three answers are *"yes"* — it is an entity. Add it to your diagram. If it is *inside* your system (a function you are writing, a class in your code, a database table your code owns) — it is **not** an entity. It belongs on the DFD as a process or data store. ::: --- ::: danger **Commonly missed entities — by project type** These are the entities students most often miss. Check whether *any* apply to your project before submitting. | Project type | Commonly missed entity | Why it is missed | |---|---|---| | Any project with login | Authentication provider (e.g. Google OAuth) | Students think login is *"inside"* their app | | Any project that emails users | Email server / SMTP service | Students don't model outgoing system calls | | School management tool | Admin user or IT department | Students only think about the primary user | | App using external data | External database or API (e.g. weather API) | Students model the API as a feature, not an entity | | App with notifications | Push notification service | Treated as internal, but it is external | ::: --- ## User stories → entities: the reliable method Your `data-collection-plan.md` user stories are the best source of entities. For each story: - **"As a [role]"** → that role is probably an entity (if they interact with your system directly). - **"I want [goal] so that [benefit]"** → what external systems does achieving this goal require? Each one is a candidate entity. Work through every user story before finalising your context diagram. ### Going further: Gherkin scenarios *(optional but excellent)* ::: info **Not required by the VCAA curriculum** — but a powerful tool for surfacing entities you'd otherwise miss. Worth knowing if you want top-band detail. ::: A Gherkin scenario expands a user story into concrete **Given / When / Then** steps. Every noun in those steps is a candidate entity. {{Video|src=https://www.youtube.com/watch?v=bxeNxhOSGJg}} *LitheSpeed — What Is Gherkin? (~1 min). The bare-bones intro; no need to learn the BDD tooling around it.* **Example.** A user story like *"As an account holder I want to withdraw cash so that I have money for the day"* expands to: ```gherkin Feature: Account Holder withdraws cash Scenario: Account has sufficient funds Given the account balance is $100 And the card is valid And the machine contains enough money When the Account Holder requests $20 Then the ATM should dispense $20 And the account balance should be $80 And the card should be returned ``` **Entities this scenario surfaces** (each underlined noun is an external system the ATM software talks to): - **Account Holder** — the human user (you'd already have this). - **Card / Authentication system** — *"the card is valid"* implies an external check (bank network or token validator). - **Bank account database** — *"balance is $100 → $80"* means your software reads and writes to an external account store. - **Cash dispenser hardware** — *"dispense $20"* is a physical subsystem outside your software. - **Card reader hardware** — *"card should be returned"* is another physical subsystem. A user story alone might surface only *Account Holder*. The Gherkin expansion forces you to confront every Given precondition and every Then effect — that's where the missing entities live. --- ::: info **Why VCAA cares** The C2-2 rubric at **5–6** requires *"illustrates the relationships between the existing system, entities and data flows"*. *"Some errors or omissions exist"* is still acceptable at 5–6. But at **9–10**, *"no errors, inconsistencies or omissions exist"* — a missing entity **is** an omission, and omissions cost you the top band. The most common C2-2 omission flagged in past years: the **email server or notification service** that every project needs but few students draw. ::: --- ## See also - [Context Diagram vs Data Flow Diagram](/sd/C02/Context%20Diagram%20vs%20Data%20Flow%20Diagram) - C02 Resources: [external reading and videos](/sd/Resources/C02-Resources) --- ← Back to [VCE Software Development Hub](/sd/VCE%20Software%20Development%20Hub)