System Requirements Document for raven-rfid

1. Introduction

raven-rfid is an RFID-based personalized lost-item detection and reminder application that connects to an ESP32 device performing RFID reads of tagged personal belongings. The product's intent is to let a person tag their own belongings with RFID tags, wire up an ESP32 reader, register each item together with its tag identifier, and then have the system continuously watch for those tagged items — detecting when a registered item is no longer in range and issuing a reminder so the item can be recovered before it is truly lost.

The audience is twofold. The Item Owner is a maker-adjacent, technically curious person who tags their own belongings, connects and maintains the ESP32 reader, and monitors which tagged items are currently detected or missing. The Reminder Recipient / Caregiver is a person — a family member or companion — who needs to be alerted when a tagged item is not detected and who acts on that reminder to locate or return the missing item. The product is deliberately an instrument rather than a lifestyle brand: precise, private, and trustworthy, with dense status data presented as a well-set readout.

2. System Overview

raven-rfid is a web application with a first-party backend that maintains durable state for accounts, registered items, RFID tag associations, ESP32 device connections, detection status, and reminders. The application connects to an ESP32 device that performs RFID reading of tagged personal items; the ESP32 is the hardware source of tag reads, and the application is the system of record for what those reads mean.

Current delivery covers:

• A public Landing surface explaining the RFID-based personalized lost-item detection and reminder application, its intended users, and the ESP32 connection.
• Self-service identity: Sign Up for first-use enrollment and Login for returning verification, protecting durable item records, device connections, detection status, and reminders for the appropriate persona.
• Items — browsing and monitoring registered personal items with their current detected or missing status.
• Add Item — registering a personal item and associating it with its RFID tag identifier.
• Device Setup — connecting the application to the ESP32 RFID reader used for item detection.
• Alerts — reviewing reminders issued when a registered tagged item is not detected and acting on the missing-item alert.

Actors are the two accepted human personas (Item Owner, Reminder Recipient / Caregiver) plus the ESP32 RFID reader as a typed non-persona device actor. Background automation evaluates detection status from incoming reads and issues reminders; it is not a human-facing capability on its own.

Narrow exclusions: this document does not add adjacent capabilities such as inventory management, shopping, social sharing, geolocation tracking, or consumer-wellness features. The ESP32 remains the accepted hardware boundary for RFID reading; the application does not replace it with a different sensing technology.

2a. Product Interpretation and Delivery Boundary

The application owns identity and durable state. Because item records, tag associations, device connections, detection status, and reminders must remain bound to the correct person and be resumable across sessions, raven-rfid uses application-owned accounts: a person establishes identity once through self-service enrollment on Sign Up, and returns through Login. The anonymous entry point is Landing, which is reachable without identity; protected item, device, status, and alert workflows are not available until identity is established. There is no invitation, provisioning, or pre-existing-account boundary in the source, so self-service enrollment is the accepted path.

Access is role-aware. Items, Add Item, and Device Setup are the Item Owner's surfaces: registering items, associating RFID tag identifiers, and connecting the ESP32 reader are the owner's control responsibilities. Alerts is the Reminder Recipient / Caregiver's surface: reviewing reminders issued when a registered tagged item is not detected and acting on the missing-item alert. Landing, Sign Up, and Login are reachable without prior identity.

The ESP32 device is an external hardware actor owned outside the application. The application connects to it, receives its RFID reads, and reflects device link state; it does not own the reader firmware or the physical tag hardware. Detection evaluation and reminder issuance run as background automation in the first-party backend, but every human-facing side of that automation — the owner's status view and the caregiver's alert review — is owned by a first-party page.

Current scope is the detection-and-reminder loop described above. Nothing in this document commits to future capabilities; any future horizon is explicitly out of current acceptance.

2b. Source Content Inventory

Not applicable. No reference directive in this request declares content_source; the authoritative material is the user requirement thread and the Planning Scope contract, which are covered by the sections below rather than by a content inventory.

2c. Page Content and Component Coverage

Landing

• Information/state: Anonymous public entry. Explains the RFID-based personalized lost-item detection and reminder application, its intended users (Item Owner and Reminder Recipient / Caregiver), and the ESP32 connection. Presents the product as an instrument: a split hero with a large headline, one line of supporting copy, and a live-looking reader console panel showing monospace serial tag reads, a lime LINKED pill with a breathing dot, and a small ESP32 pinout schematic.
• Primary actions: Connect ESP32 (tangerine primary) leading toward device setup; See a live demo (hairline-bordered secondary) showing the reader console behavior.
• Supporting actions: Navigate to Sign Up; navigate to Login.
• Domain entities: Product description, intended-user description, ESP32 connection concept, illustrative tag read (tag ID, item name, RSSI, timestamp), device link state.
• Component responsibilities: Split hero (7-column text / 5-column console); headline with tangerine emphasis on ACCOUNTED FOR; reader console panel with monospace serial log, LINKED pill, and pinout schematic; primary and secondary call-to-action controls; entry links to identity surfaces.
• States: Loading — console panel renders its frame and hairline borders immediately, with the serial log populating as content resolves. Empty — if no illustrative reads are available, the console shows its frame, the LINKED pill, and the pinout schematic without log rows. Success — hero and console render fully; entry links are reachable. Error — if the console content cannot load, the panel renders its frame and schematic with a muted note in place of the log; the hero copy and both call-to-action controls remain fully usable. Recovery — the visitor can still proceed to Sign Up or Login regardless of console state.

Sign Up

• Information/state: Anonymous identity-access surface for first-use self-service enrollment. Collects the information needed to establish an account that will own durable item records, device connections, detection status, and reminders.
• Primary actions: Submit enrollment to create the account.
• Supporting actions: Navigate to Login for an existing account; return to Landing.
• Domain entities: Account identity, credential, role selection distinguishing Item Owner from Reminder Recipient / Caregiver.
• Component responsibilities: Enrollment form with labeled fields; role selection control; submit control; validation messaging; link to Login.
• States: Loading — submit control shows in-progress state and prevents duplicate submission. Empty — form renders with empty fields and no validation errors. Success — account is created and the person proceeds into the application with their role established. Error — field-level validation errors (missing or malformed required fields, already-enrolled identity) render inline next to the offending field; the form retains entered values. Recovery — the person corrects the flagged fields and resubmits, or switches to Login if they already have an account.

Login

• Information/state: Anonymous identity-access surface for returning verification, protecting durable item records, device connections, detection status, and reminders for the appropriate persona.
• Primary actions: Submit credentials to verify identity and resume the person's own state.
• Supporting actions: Navigate to Sign Up for a new account; return to Landing.
• Domain entities: Account identity, credential, established role.
• Component responsibilities: Credential form with labeled fields; submit control; validation and failure messaging; link to Sign Up.
• States: Loading — submit control shows in-progress state and prevents duplicate submission. Empty — form renders with empty fields and no errors. Success — identity is verified and the person lands in the surface appropriate to their role (Items for Item Owner, Alerts for Reminder Recipient / Caregiver). Error — invalid credentials render a clear failure message without revealing which field was wrong; the form retains the entered identity value. Recovery — the person retries, or switches to Sign Up if they have no account.

Items

• Information/state: The Item Owner's monitoring surface. Leads with an oversized tabular status sentence — for example 3 ITEMS OUT OF RANGE with the numeral in tangerine — followed by a ruled item table with tabular columns: item · tag ID · last seen · reader · status. Each row's status is a three-part token: a 6px dot, an 11px caps label, and a colour — lime DETECTED, tangerine MISSING, muted STALE. RFID tag IDs render as monospace chips with a copy-on-click affordance.
• Primary actions: Open an item row to inspect its detail and current detection state; navigate to Add Item to register a new item.
• Supporting actions: Copy a tag ID chip; navigate to Device Setup when the reader link needs attention; navigate to Alerts if the person also holds the caregiver role.
• Domain entities: Registered item, RFID tag identifier, last-seen timestamp, reader/device identity, detection status, read count.
• Component responsibilities: Oversized tabular status sentence; ruled item table with aligned tabular columns; status token (dot + caps label + colour); monospace tag-ID chip with copy affordance; row expansion for item detail; empty-state guidance pointing to Add Item; device-link indicator reflecting reader availability.
• States: Loading — table renders its ruled frame and column headers while rows resolve. Empty — no registered items: the status sentence reads zero out of range and the table area shows guidance to register a first item via Add Item. Success — items render with current status; detected items show lime DETECTED, missing items show tangerine MISSING, stale items show muted STALE. Error — if status data cannot be retrieved, the table shows the last known rows with a muted note that status is unavailable, and the device-link indicator reflects the reader state. Recovery — the owner can retry the status view, check Device Setup if the reader link is down, or proceed to Add Item.

Add Item

• Information/state: The Item Owner's registration surface. Captures the personal item's identity and associates it with its RFID tag identifier so that item's detection status can be evaluated.
• Primary actions: Submit the item registration with its associated RFID tag identifier.
• Supporting actions: Capture or enter the RFID tag identifier; return to Items without saving.
• Domain entities: Item name/description, RFID tag identifier, associated reader/device, registration timestamp.
• Component responsibilities: Item detail fields; RFID tag identifier field rendered as a monospace chip once captured; tag-capture control; submit control; validation messaging; cancel/return control.
• States: Loading — submit control shows in-progress state and prevents duplicate submission. Empty — form renders with empty fields and no tag captured. Success — the item is registered with its tag association and appears in Items with an evaluable detection status. Error — missing required fields or a tag identifier already associated with another item render inline errors; entered values are retained. Recovery — the owner corrects the flagged fields or supplies a different tag identifier and resubmits, or returns to Items.

Device Setup

• Information/state: The Item Owner's connection surface for the ESP32 RFID reader used for item detection. Shows the reader's connection state, its device identity in 11px caps monospace, and the link indicator with its lime/amber dot. Includes a schematic line diagram of the ESP32 + RC522 wiring (SCK/MISO/MOSI/SS/3V3/GND as labelled hairlines).
• Primary actions: Connect the application to the ESP32 RFID reader; reconnect when the link is down.
• Supporting actions: Review the wiring schematic; return to Items to confirm detection status once connected.
• Domain entities: ESP32 device identity, connection/link state, reader configuration, wiring reference.
• Component responsibilities: Connection control; device identity display in monospace; link indicator with lime/amber dot and 2s pulse while connected; wiring schematic panel; connection status messaging.
• States: Loading — the surface renders its frame and device identity while connection state resolves. Empty — no reader has been connected yet: the surface shows the wiring schematic and the connect control with guidance to link the ESP32. Success — the reader is connected: the link indicator shows lime with its breathing pulse and the device ID is displayed. Error — connection fails or the link drops: the indicator shows amber with a clear failure message and a Reconnect control. Recovery — the owner retries the connection, verifies the wiring against the schematic, and returns to Items once the link is restored.

Alerts

• Information/state: The Reminder Recipient / Caregiver's surface. Presents reminders issued when a registered tagged item is not detected, at a lower density than the owner's surfaces: one big status word and one action. Each alert identifies the missing item and its tag ID chip, with the time the item was last seen.
• Primary actions: Act on the missing-item alert — mark it as being handled or resolved once the item is located or returned.
• Supporting actions: Copy the tag ID chip; review the alert's item and last-seen detail.
• Domain entities: Reminder/alert, associated item, RFID tag identifier, last-seen timestamp, alert state (open / handled / resolved).
• Component responsibilities: Oversized status word for the current alert; alert feed or list; per-alert item identity and monospace tag-ID chip; last-seen timestamp; action control to handle or resolve the alert; empty-state message when no reminders are outstanding.
• States: Loading — the alert area renders its frame while reminders resolve. Empty — no outstanding reminders: the surface shows a calm all-clear state with no action required. Success — outstanding reminders render with their item identity, tag chip, and last-seen time; acting on one updates its state to handled or resolved. Error — if reminders cannot be retrieved, the surface shows a clear unavailable message rather than a misleading all-clear. Recovery — the caregiver can retry the alert view; a resolved alert leaves the outstanding list and the surface returns to its all-clear state when none remain.

3. Functional Requirements

FR-1 — RFID-based personalized lost-item detection and reminders (explicit) As an Item Owner, I should have an application that detects when my personalized tagged items are missing and issues reminders, so that I can recover or avoid losing my personal belongings.

• Trigger/input: Registered items with associated RFID tag identifiers and an active ESP32 reader connection.
• Observable result: Each registered item carries a current detection status (detected / missing / stale), and a reminder is issued when a registered tagged item is not detected.
• Access state: Requires an established, verified identity with the Item Owner role.
• Failure/recovery: If detection status cannot be evaluated, the owner sees an explicit unavailable state rather than a false all-clear, and can check the reader link on Device Setup.
• Continuation: The owner monitors status on Items and acts on missing items; the caregiver receives and acts on the reminder on Alerts.

FR-2 — ESP32 RFID reader connection (explicit) As an Item Owner, I should be able to connect the application to an ESP32 device that performs RFID reading of tagged personal items, so that device-based detection can operate.

• Trigger/input: The owner initiates a connection to the ESP32 RFID reader from Device Setup.
• Observable result: The reader's link state is shown with a device identity in monospace and a link indicator (lime while connected, amber when down).
• Access state: Requires an established, verified identity with the Item Owner role.
• Failure/recovery: A failed or dropped connection shows an amber indicator, a clear failure message, and a Reconnect control; the owner can verify wiring against the on-surface schematic.
• Continuation: Once connected, the owner returns to Items to confirm detection status; the link indicator remains permanently visible in the left rail.

FR-3 — ESP32 connection prerequisite for detection (required_inference) As an Item Owner, I should have the ESP32 RFID reader connected before device-based detection can operate, so that detection results reflect real reads rather than stale assumptions.

• Trigger/input: The owner attempts to rely on detection status while no reader is connected.
• Observable result: Detection status is not presented as live; the device-link indicator reflects the disconnected state and the owner is directed to Device Setup.
• Access state: Requires an established, verified identity with the Item Owner role.
• Failure/recovery: The owner connects or reconnects the reader on Device Setup and returns to Items.
• Continuation: Detection status becomes evaluable once the reader link is established.

FR-4 — RFID tag association with each registered item (required_inference) As an Item Owner, I should associate an RFID tag identifier with each registered personal item, so that the item's detection status can be evaluated.

• Trigger/input: The owner registers an item on Add Item and supplies or captures its RFID tag identifier.
• Observable result: The item is registered with its tag association and appears in Items with an evaluable detection status; the tag ID renders as a monospace chip.
• Access state: Requires an established, verified identity with the Item Owner role.
• Failure/recovery: A missing required field or a tag identifier already associated with another item renders an inline error and retains entered values; the owner corrects and resubmits.
• Continuation: The registered item appears in Items and participates in detection.

FR-5 — Browse and monitor registered items with current status (required_inference) As an Item Owner, I should browse and monitor my registered personal items with their current detected or missing status, so that I know at a glance which of my things are accounted for.

• Trigger/input: The owner opens Items.
• Observable result: An oversized tabular status sentence (for example 3 ITEMS OUT OF RANGE) leads a ruled table of item · tag ID · last seen · reader · status, with each status shown as a dot, an 11px caps label, and a colour.
• Access state: Requires an established, verified identity with the Item Owner role.
• Failure/recovery: If status data cannot be retrieved, the table shows last known rows with an explicit unavailable note; the owner can retry or check Device Setup.
• Continuation: The owner opens an item row for detail or proceeds to Add Item to register another item.

FR-6 — Review and act on missing-item reminders (required_inference) As a Reminder Recipient / Caregiver, I should review reminders issued when a registered tagged item is not detected and act on the missing-item alert, so that I can locate or return the missing item.

• Trigger/input: A registered tagged item is not detected and a reminder is issued; the caregiver opens Alerts.
• Observable result: The outstanding reminder shows the missing item, its tag ID chip, and when it was last seen; acting on it updates the alert state to handled or resolved.
• Access state: Requires an established, verified identity with the Reminder Recipient / Caregiver role.
• Failure/recovery: If reminders cannot be retrieved, the surface shows an explicit unavailable message rather than a misleading all-clear; the caregiver can retry.
• Continuation: A resolved alert leaves the outstanding list; when none remain, the surface returns to its all-clear state.

FR-7 — Self-service enrollment (required_inference) As a person beginning to use the application, I should be able to enroll myself, so that I can start using the application without an invitation or pre-provisioned account.

• Trigger/input: The person opens Sign Up from Landing and submits enrollment information, including their role.
• Observable result: An account is created and the person proceeds into the application with their role established.
• Access state: Anonymous; Sign Up is reachable without prior identity.
• Failure/recovery: Field-level validation errors render inline and entered values are retained; the person corrects and resubmits, or switches to Login.
• Continuation: The person lands in the surface appropriate to their role.

FR-8 — Returning verification (required_inference) As a returning person, I should verify my identity before protected item, device, status, and alert workflows, so that my durable records and reminders remain bound to me.

• Trigger/input: The person opens Login and submits credentials.
• Observable result: Identity is verified and the person lands in the surface appropriate to their role — Items for Item Owner, Alerts for Reminder Recipient / Caregiver.
• Access state: Anonymous entry; protected destinations remain unavailable until verification succeeds.
• Failure/recovery: Invalid credentials render a clear failure message without revealing which field was wrong; the person retries or switches to Sign Up.
• Continuation: The person resumes their own item, device, status, or alert state.

FR-9 — Role-aware authorization (required_inference) As the application, I should distinguish Item Owner control from Reminder Recipient / Caregiver alert access, so that each persona reaches the responsibilities that belong to them.

• Trigger/input: A verified person navigates the application.
• Observable result: Items, Add Item, and Device Setup are the Item Owner's surfaces; Alerts is the Reminder Recipient / Caregiver's surface; Landing, Sign Up, and Login are reachable without prior identity.
• Access state: Role is established at enrollment and carried through verification.
• Failure/recovery: A person attempting a surface outside their role is not granted that surface's state and is returned to the surface appropriate to their role.
• Continuation: Each persona continues in their own working context.

FR-10 — Background detection evaluation and reminder issuance (required_inference) As the application, I should evaluate detection status from incoming ESP32 RFID reads and issue a reminder when a registered tagged item is not detected, so that the owner's status view and the caregiver's alert review reflect real detection outcomes.

• Trigger/input: Incoming RFID reads from the connected ESP32 reader, evaluated against registered items and their tag associations.
• Observable result: Item detection status updates (detected / missing / stale) and a reminder is created for a not-detected registered tagged item.
• Access state: Runs as background automation in the first-party backend; it is not a human-facing capability on its own.
• Failure/recovery: If the reader link is down or reads cannot be evaluated, status is not presented as live and the device-link indicator reflects the disconnected state.
• Continuation: The owner sees updated status on Items; the caregiver sees the issued reminder on Alerts.

4. User Personas

Item Owner

Product context. The Item Owner is the person who tags their own belongings with RFID tags and connects an ESP32 reader so the application can detect their items. They are maker-adjacent and technically curious: they are comfortable wiring an ESP32 + RC522 reader, they understand what a tag ID and an RSSI reading are, and they expect the application to present dense status data precisely rather than to entertain them.

Primary goal. To keep their personal belongings accounted for — to know which tagged items are currently detected, to be told when one is missing, and to recover or avoid losing it.

Distinct accepted responsibilities. The Item Owner is the only persona who registers items and associates RFID tag identifiers with them (Add Item), the only persona who connects and maintains the ESP32 RFID reader (Device Setup), and the persona who monitors the resulting detection status across their registered items (Items). They also receive reminders about items they may have left behind.

Relevant inputs and decisions. They decide which belongings to tag, what to name each registered item, and which RFID tag identifier belongs to which item. They decide when to connect or reconnect the reader, and they judge from the status readout whether an item needs attention.

Interactions with other accepted participants. The Item Owner's registered items and their detection outcomes are what produce the reminders the Reminder Recipient / Caregiver acts on. The owner's tagging and reader setup are the prerequisite for the caregiver ever seeing a meaningful alert.

Observable success. The owner sees an accurate status sentence and item table on Items, with each item's status shown as a dot, a caps label, and a colour; the ESP32 link indicator in the left rail shows the reader is connected; and missing items surface as reminders that lead to recovery.

Reminder Recipient / Caregiver

Product context. The Reminder Recipient / Caregiver is a person who needs to be alerted when a tagged item is not detected — a family member or companion looking after someone's belongings. They are not the person who tags items or wires the reader, and they do not need the owner's dense instrument view. They see the same system at a lower density: one big status word and one action.

Primary goal. To act on a reminder notification so that a missing tagged item is located or returned, and the missing-item alert is resolved.

Distinct accepted responsibilities. The caregiver reviews reminders issued when a registered tagged item is not detected and acts on the missing-item alert (Alerts). Their successful outcome is a resolved missing-item alert — not item registration, tag association, or device connection, which are not their responsibilities.

Relevant inputs and decisions. They read which item is missing, its tag ID chip, and when it was last seen, and they decide when the item has been located or returned so the alert can be marked handled or resolved.

Interactions with other accepted participants. The caregiver depends on the Item Owner's registered items, tag associations, and connected reader for a reminder to exist at all. Their action closes the loop the owner's setup opened.

Observable success. Outstanding reminders render with the missing item's identity, tag chip, and last-seen time; acting on one updates its state; when no reminders remain, the surface shows a calm all-clear state.

5. Core User Flows

Flow A — Item Owner: first use, connect the reader, and register a tagged item

1. The Item Owner arrives at Landing without an identity and reads what the application does, who it is for, and that it connects to an ESP32 reader. The reader console panel shows illustrative monospace tag reads and a lime LINKED pill.
2. The owner selects Connect ESP32 (or proceeds via Sign Up), reaching Sign Up.
3. On Sign Up, the owner enters their enrollment information and selects the Item Owner role, then submits. The account is created and the owner proceeds into the application.
4. The owner opens Device Setup. The surface shows the ESP32 + RC522 wiring schematic (SCK/MISO/MOSI/SS/3V3/GND) and the connect control.
5. The owner connects the application to the ESP32 RFID reader. On success, the link indicator turns lime with its 2s breathing pulse and the device ID renders in 11px caps monospace. If the connection fails or drops, the indicator turns amber, a failure message appears, and the owner uses Reconnect — verifying the wiring against the schematic — until the link is restored.
6. The owner opens Add Item, enters the item's details, and captures or enters its RFID tag identifier, which renders as a monospace chip. They submit.
7. If a required field is missing or the tag identifier is already associated with another item, an inline error appears and the entered values are retained; the owner corrects the field or supplies a different tag and resubmits.
8. On success, the item is registered with its tag association and appears in Items with an evaluable detection status. The owner repeats steps 6–7 for each additional belonging.

Flow B — Item Owner: monitor status and respond to a missing item

1. The Item Owner opens Items. The surface leads with an oversized tabular status sentence — for example 3 ITEMS OUT OF RANGE with the numeral in tangerine — above a ruled table of item · tag ID · last seen · reader · status.
2. The owner scans the status tokens: lime DETECTED for items in range, tangerine MISSING for items not detected, muted STALE for items whose status is no longer fresh. Each token is a dot, an 11px caps label, and a colour, so status survives greyscale.
3. The owner opens a row to inspect the item's detail and current detection state, and can copy the item's tag ID chip.
4. If status data cannot be retrieved, the table shows the last known rows with an explicit unavailable note rather than a false all-clear; the owner retries, or checks Device Setup if the reader link is down.
5. When an item shows MISSING, the owner acts to recover it; the corresponding reminder is available to the Reminder Recipient / Caregiver on Alerts.
6. The owner continues monitoring, registering further items via Add Item as needed.

Flow C — Reminder Recipient / Caregiver: act on a missing-item reminder

1. A registered tagged item is not detected, and the application issues a reminder.
2. The Reminder Recipient / Caregiver opens Login and submits their credentials. On success they land on Alerts, the surface appropriate to their role. If credentials are invalid, a clear failure message appears without revealing which field was wrong, and they retry or switch to Sign Up.
3. On Alerts, the caregiver sees the outstanding reminder at low density: one big status word, the missing item's identity, its tag ID chip, and when it was last seen.
4. The caregiver acts on the missing-item alert — locating or returning the item — and marks the alert handled or resolved. The alert's state updates and it leaves the outstanding list.
5. If reminders cannot be retrieved, the surface shows an explicit unavailable message rather than a misleading all-clear, and the caregiver retries.
6. When no reminders remain, Alerts returns to its calm all-clear state with no action required.

Flow D — Returning Item Owner: resume monitoring

1. The Item Owner opens Login and submits their credentials.
2. On success they land on Items, resuming their own durable item records, device connection, and detection status. If credentials are invalid, a clear failure message appears and they retry or switch to Sign Up.
3. The owner confirms the ESP32 link indicator in the left rail. If it shows amber, they open Device Setup and use Reconnect until the link is restored.
4. The owner resumes monitoring on Items and continues from Flow B.

6. Visuals Colors and Theme

The creative direction is authoritative for this section. Muse: Rasmus Andersson. Headline: Instrument-panel product craft — graphite ground, hot tangerine signal, tabular numerals as ornament.

Mode. Dark mode throughout. Warm graphite #141517 is the page ground everywhere; #1C1E21 panels sit on it with 1px #2A2D31 hairlines and no shadows.

Colour tokens by role.

Tangerine #FF6A2B is the only action colour — primary buttons, focus rings, the active nav rule, and the MISSING status chip — used on roughly 4% of pixels and never as a fill for large blocks. Acid lime #C8F04A is reserved exclusively for DETECTED / IN RANGE live state and the ESP32 link LED, so green never means anything else. Muted #8A8F98 carries labels, timestamps, units, and secondary metadata. Status is encoded by colour plus a text label plus a glyph dot, never colour alone. Body text on #141517 and #1C1E21 clears 4.5:1; tangerine is used for text only at 18px+ or on button fills with #141517 text.

Typography. Headings: Space Grotesk 500/600, tight tracking (−0.02em to −0.03em), sentence case for headlines but ALL-CAPS at 11–12px with +0.14em tracking for every label, field name, table header, and unit. Headlines are large and confident but never light-weight; numbers inside headings always render tabular. Monospace voice: JetBrains Mono for RFID tag IDs (E7:3A:0C:9F), device IDs, hex, timestamps, and read counts — set as objects on their own chips, never inline in prose. Body: Inter Tight. Scale: 1.25 modular on a 4/8pt base — 12 / 14 / 16 / 20 / 25 / 40 / 64 / 96. Display headline clamp(40px, 9vw, 96px); section heads clamp(24px, 4vw, 40px); body 16px/1.55; data rows 14px tabular; micro-labels 11px caps +0.14em.

Shape language. Compact and machined: 6px radii on inputs and chips, 10px on panels, 999px only on status pills. 1px hairline borders (#2A2D31) do all the separating — no drop shadows, no glass, no blur. Every dimension lands on the 4/8pt scale. Icons are 16px, 1.5px stroke, geometric. A single 2px tangerine rule under the active nav item is the only decorative line in the system.

Layout. A fixed 240px left rail (wordmark RAVEN.RFID in caps, nav, ESP32 link indicator at the bottom with its lime/amber dot) against a fluid content column capped at 1200px, 32px gutters, 12-column grid. The dashboard is a dense ordered stack: an oversized status sentence at the top (3 items out of range), then a ruled item table with tabular columns (item · tag ID · last seen · reader · status), then the alert feed. Everything aligns to a shared column axis so the page reads like a well-set instrument readout. At 375px the rail collapses to a 56px bottom tab bar and the table becomes stacked label/value rows — never a horizontally clipped table.

Imagery style. The interface is the imagery: real tables, real tag IDs, schematic line diagrams of the ESP32 + RC522 wiring (SCK/MISO/MOSI/SS/3V3/GND as labelled hairlines), a small monospace serial-log window used as a decorative panel in the hero, and 1.5px-stroke line drawings of a bag/keys/wallet set as item glyphs. No stock photography, no 3D renders, no gradient blobs, no illustration of people.

Avoid. Blue/indigo primaries on white; Inter, Roboto, Arial, Helvetica, Open Sans, Lato, Poppins, or system-ui as the heading or body face; glassmorphism, frosted panels, gradient blobs, or any blurred surface; a grid of identical hover-lift cards as the dashboard; drop shadows, glow effects, or neon bloom on the accent colours; a centred hero with headline + subtext + blue button; status communicated by colour alone without a text label and dot; photography of people or lifestyle stock imagery anywhere in the product. The generic indigo/blue-on-white SaaS template is forbidden for this project.

7. Signature Design Concept

The reader console bleeding off the page. The public entry — Landing — is a split hero, not a centred one. The left 7 columns carry a 96px Space Grotesk headline YOUR THINGS, ACCOUNTED FOR. set flush-left in three stacked lines, with the words ACCOUNTED FOR in tangerine; beneath it one 16px line of copy and a tangerine primary button Connect ESP32 pinned left with a hairline-bordered secondary See a live demo. The right 5 columns carry a real, dark, bordered reader console panel: a monospace serial log scrolling tag reads (E7:3A:0C:9F · WALLET · RSSI -61 · 12:04:07), a lime LINKED pill with its breathing dot, and above it a small schematic of the ESP32 pinout. The panel is cropped off the right viewport edge at 1280px so it reads as a live instrument bleeding into the page. No gradient, no blob, no centred stack.

The concept is implementable with accepted content only: the console's log rows are illustrative tag reads of the kind the ESP32 produces, the LINKED pill reflects the accepted device link state, and the pinout schematic is the same wiring reference the owner uses on Device Setup. The two call-to-action controls lead to accepted destinations — Connect ESP32 toward device setup and identity, See a live demo toward the console behavior. Nothing here introduces a new page, capability, or behavior.

Signature moves carried through the product. RFID tag IDs are never plain text: every one is a JetBrains Mono chip on #1C1E21 with a 1px hairline and a copy-on-click affordance, so the tag becomes a tangible object in the UI. The Items page leads with an oversized tabular sentence — 3 ITEMS OUT OF RANGE at clamp(40px, 9vw, 96px) with the numeral in tangerine — instead of a row of KPI cards. Status is a three-part token everywhere: a 6px dot, an 11px caps label, and a colour — lime DETECTED, tangerine MISSING, muted STALE. The left rail's bottom edge carries a permanent ESP32 link indicator with the device ID in 11px caps monospace and a hairline-topped Reconnect control, so the hardware is always visible and never buried in settings.

8. Interaction Model & Motion Direction

Interaction Model: Static Motion Tempo: restrained Hero Dimensionality: flat

Landing Hero Motion Brief. The focal subject is the reader console panel on the right 5 columns — a dark, bordered instrument showing a monospace serial log of tag reads, a lime LINKED pill, and the ESP32 pinout schematic. The input→transformation→outcome thesis: incoming illustrative tag reads enter the console's serial log, the log advances as new reads arrive, and the LINKED pill's dot breathes on a 2s loop to signal that the reader is live — so the visitor sees the product's defining state (a reader watching tagged things) rather than being told about it. Motion vocabulary: fast and functional, 140ms cubic-bezier(0.2, 0, 0, 1) on hover, focus, row expansion, and status changes; no bounce, no float, no parallax; the only ambient motion is the ESP32 link pulse (a 2s lime opacity breathe while connected) and tabular numerals that count up over 300ms when a read count refreshes. Scroll reveal: none — content is simply there. The composed first frame shows the headline set flush-left in three stacked lines with ACCOUNTED FOR in tangerine, the single line of copy, both call-to-action controls pinned left, and the reader console panel already populated with log rows and the breathing LINKED pill, cropped off the right viewport edge. The reduced-motion state kills the pulse and the count-up, leaving static values: the LINKED pill renders solid lime with its dot at rest, the serial log shows its rows without advancing, and all readable text and controls remain whole and fully inside the viewport at 375px, 768px, and 1280px.

9. Non-Functional Requirements

NFR-1 — ESP32 connectivity constraint (explicit) The application must connect to an ESP32 device for RFID-based item detection. This is a hard constraint from the authoritative source: the ESP32 is the accepted hardware boundary for RFID reading, and the application does not substitute a different sensing technology for it.

NFR-2 — Durable state (required_inference) Item records, RFID tag associations, device connections, detection status, and reminders must persist durably so that a returning person resumes their own state rather than reconstructing it. Rationale: the accepted journeys require continuity across sessions and correct binding of records to the right persona.

NFR-3 — Identity and access continuity (required_inference) Protected item, device, status, and alert workflows must remain unavailable until identity is established, and each verified person must reach the surface appropriate to their role. Rationale: durable records and reminders must remain bound to the correct participant, and role-aware authorization distinguishes Item Owner control from Reminder Recipient / Caregiver alert access.

NFR-4 — Status legibility (explicit, from creative direction) Status must be encoded by colour plus a text label plus a glyph dot, never colour alone, so that status survives greyscale and colour-blindness. Body text on #141517 and #1C1E21 must clear 4.5:1; tangerine is used for text only at 18px+ or on button fills with #141517 text.

NFR-5 — Responsive integrity (explicit, from creative direction) Readable text and controls stay whole at every viewport: headlines, wordmarks, labels, numbers, cards' text, and controls stay entirely inside the viewport and their container at 375px, 768px, and 1280px, wrapping or scaling (for example font-size: clamp(...) with its mobile size) to fit, and no other element covers any part of them. At 375px the rail collapses to a 56px bottom tab bar and the item table becomes stacked label/value rows — never a horizontally clipped table.

NFR-6 — Reduced motion (explicit, from creative direction) prefers-reduced-motion kills the ESP32 link pulse and the tabular count-up, leaving static values, and provides a usable static arrangement in which every item can be brought fully into view.

NFR-7 — Honest failure states (required_inference) When detection status, reminders, or the reader link cannot be resolved, the application must show an explicit unavailable or disconnected state rather than a false all-clear. Rationale: a lost-item system that silently reports "all clear" when it cannot see is worse than one that admits it cannot see.

10. Tech Stack

• Frontend: React web application. The creative direction's layout, typography, and motion requirements (fixed 240px left rail collapsing to a 56px bottom tab bar at 375px, clamp() type scale, 140ms transitions, prefers-reduced-motion handling) are implemented in the frontend.
• Backend: Python / FastAPI. The first-party backend owns accounts, item records, RFID tag associations, ESP32 device connections, detection status, reminders, and the background detection evaluation and reminder issuance described in FR-10.
• Storage: A durable datastore appropriate to the backend, holding accounts, items, tag associations, device connections, detection status, and reminders.
• ESP32 device: External hardware actor, owned outside the application. The application connects to it and receives its RFID reads; it does not own the reader firmware or the physical tag hardware.
• Deployment: Docker / docker-compose for the application's runnable services. Kubernetes is not required by any accepted requirement and is not included.

11. Assumptions and Constraints

Assumptions

• A-1 (required_inference): The ESP32 reader is reachable from the application over a network connection the owner configures; the source does not specify the transport, so the connection mechanism is left to implementation within the accepted ESP32 boundary.
• A-2 (required_inference): A person's role (Item Owner or Reminder Recipient / Caregiver) is established at enrollment and carried through verification, since the accepted journeys require each persona to reach their own surface.
• A-3 (required_inference): Detection status is derived from incoming RFID reads evaluated against registered items and their tag associations; the source does not specify the evaluation interval or the threshold at which an item becomes MISSING versus STALE.
• A-4 (required_inference): The illustrative tag reads shown in the Landing reader console are representative of the kind of reads the ESP32 produces; they are presentation content, not live device data.

Constraints

• C-1 (explicit): The application must connect to an ESP32 device for RFID-based item detection. This is a hard constraint and is not relaxed anywhere in this document.
• C-2 (explicit, from creative direction): The generic indigo/blue-on-white SaaS template is forbidden for this project. The system is graphite-dark with one tangerine signal.
• C-3 (explicit, from creative direction): Blue/indigo primaries on white, glassmorphism, frosted panels, gradient blobs, blurred surfaces, drop shadows, glow effects, neon bloom on accent colours, a centred hero with headline + subtext + blue button, status communicated by colour alone, and photography of people or lifestyle stock imagery are all excluded.
• C-4 (explicit, from creative direction): Inter, Roboto, Arial, Helvetica, Open Sans, Lato, Poppins, and system-ui are excluded as the heading or body face.
• C-5 (scope): This document does not add adjacent capabilities such as inventory management, shopping, social sharing, geolocation tracking, or consumer-wellness features. No future-horizon capability is committed to here.

12. Glossary

• RFID tag identifier — The unique identifier of an RFID tag, rendered in the interface as a JetBrains Mono chip (for example E7:3A:0C:9F) with a copy-on-click affordance.
• ESP32 — The external microcontroller device that performs RFID reading of tagged personal items and to which the application connects. It is the accepted hardware boundary for detection.
• RC522 — The RFID reader module referenced by the wiring schematic on Device Setup, wired to the ESP32 over SCK/MISO/MOSI/SS/3V3/GND.
• Registered item — A personal belonging recorded in the application and associated with an RFID tag identifier so its detection status can be evaluated.
• Detection status — The current state of a registered item relative to the reader's reads: DETECTED (in range, lime), MISSING (not detected, tangerine), or STALE (status no longer fresh, muted). Always shown as a dot, an 11px caps label, and a colour.
• Reminder / alert — The notification issued when a registered tagged item is not detected, reviewed and acted on by the Reminder Recipient / Caregiver on Alerts.
• Link indicator — The permanent ESP32 connection indicator at the bottom of the left rail, showing the device ID in 11px caps monospace with a lime dot while connected and amber when the link is down, plus a hairline-topped Reconnect control.
• Item Owner — The accepted persona who tags belongings, connects the ESP32 reader, registers items with their tag identifiers, and monitors detection status.
• Reminder Recipient / Caregiver — The accepted persona who reviews reminders issued when a registered tagged item is not detected and acts on the missing-item alert.