System Requirements Document for frosty-client

1. Introduction

frosty-client is a SaaS product that helps a recruitment company manage its clients. The recruitment agency — its owner or manager and its recruiters — uses the product to keep client information in one organized place, so that the agency can serve its client companies consistently and find what it needs quickly.

The product is a working tool for a people-facing business: it holds the agency's client records, lets the agency create and maintain them as relationships change, and lets the agency remove records it no longer manages. It is not a job board, not an applicant tracking system, and not a candidate-facing product; its subject is the agency's client companies.

The audience is the recruitment agency itself: the owner or manager who sets up and oversees the client base, and the recruiters who work with client companies day to day.

2. System Overview

frosty-client is delivered as a first-party web application with application-owned identity. Anonymous visitors arrive at a public Landing page that explains what the product does. An agency owner or manager establishes first use through self-service Sign Up; returning owners/managers and recruiters verify themselves through Login. Once verified, users work inside the protected area of the product: a Clients list of the agency's client records, a New Client form for creating a record, a Client Details view for reviewing and editing an existing record, and a Client Removal flow that completes the owner/manager's removal of a client record the agency no longer manages.

The product's actors are the two accepted human personas — the Recruitment Agency Owner/Manager and the Recruitment Consultant/Recruiter — plus the application itself, which persists durable client records and their lifecycle operations. Client records are durable, agency-owned state: they survive sessions and are bound to the agency that created them, which is why identity continuity is required before any client record can be reached.

Narrow exclusions: the product does not manage candidates, job requisitions, placements as a separate tracked object, billing, or communications with client companies. It manages the agency's client records and the operations on those records described in this document.

2a. Product Interpretation and Delivery Boundary

Delivery ownership. frosty-client is a first-party custom application. All user-facing surfaces — Landing, Login, Sign Up, Clients, New Client, Client Details, and Client Removal — are owned and rendered by the application. There is no provider-owned or external-only surface in the current product, and no headless delivery boundary.

Identity and access ownership. Identity is application-owned. The Landing page is anonymously reachable and carries no client data. Login and Sign Up are themselves anonymously reachable entry surfaces: a person who has not yet verified cannot be required to verify in order to reach the interaction that verifies them. The Clients, New Client, and Client Details surfaces require a verified session. Client Removal is restricted to the owner/manager role, because removal authority is the one place where the accepted behavior distinguishes the owner/manager from the recruiter.

Current boundary. The current product covers: anonymous explanation of the product; self-service first-use enrollment for the agency owner or manager; returning verification for owners/managers and recruiters; role assignment distinguishing owner/manager removal authority from recruiter access; browsing, creating, reviewing, editing, and removing the agency's client records; and backend persistence for those durable records and their lifecycle operations.

Future boundary. Nothing beyond the above is committed. Any capability not listed in the current boundary — including candidate management, placement tracking as a separate object, reporting, billing, or client communication — is out of scope for this generation and must not be built into current pages or acceptance.

2b. Source Content Inventory

Not applicable. No reference directive in this project declares a content_source, so no source content inventory is included.

2c. Page Content and Component Coverage

Landing

• Information and state. Anonymous, no client data. States the product's purpose: a SaaS tool that helps a recruitment company organize and manage its clients. Presents the client lifecycle as the product's organizing logic: Prospect → Active → Placed → Archived.
• Primary actions. Go to Sign Up (start using the product). Go to Login (return to an existing account).
• Supporting actions. Read the lifecycle diagram and the numbered facts row; follow the primary call to action into Sign Up.
• Domain entities. None persisted. The lifecycle stages (Prospect, Active, Placed, Archived) are presented as product logic, not as live records.
• Component responsibilities. Full-width ruled hero diagram: left side carries the 48px flush-left headline with a 4px signal-red rule above it; right side carries the horizontal transit-style lifecycle schematic with coded coloured lines and station dots. Below the fold, a single row of three numbered facts in signal red, signal yellow, and signal green. Header with product name and Login / Sign Up entry points.
• States. Loading: static content, no loading state required. Empty: not applicable. Success: page renders; visitor proceeds to Sign Up or Login. Error: if the page fails to load, the visitor can retry by reloading; no partial state is shown. Recovery: the visitor can always reach Sign Up and Login from the header.

Login

• Information and state. Anonymous entry surface. Collects the returning user's credentials and verifies them. No client data is shown before verification succeeds.
• Primary actions. Submit credentials to verify and enter the protected area.
• Supporting actions. Navigate to Sign Up if the visitor does not yet have an account.
• Domain entities. User identity (email and password credential), session.
• Component responsibilities. Credential form with email and password fields, submit control, inline validation messaging, and a link to Sign Up.
• States. Loading: submit control shows a pending state while verification is in flight. Empty: form fields start empty. Success: verification succeeds and the user lands in the protected area at Clients. Error: invalid credentials produce an inline error and the form remains filled so the user can correct it; repeated failure keeps the user on Login. Recovery: the user can retry, or navigate to Sign Up.

Sign Up

• Information and state. Anonymous entry surface for the agency owner or manager establishing first use. Collects the information needed to create the agency's account and its first owner/manager identity. No client data is shown before the account exists.
• Primary actions. Submit the enrollment form to create the account and the owner/manager identity.
• Supporting actions. Navigate to Login if the visitor already has an account.
• Domain entities. Agency account, owner/manager user identity with the owner/manager role, session.
• Component responsibilities. Enrollment form with the required identity fields, submit control, inline validation messaging, and a link to Login.
• States. Loading: submit control shows a pending state while the account is being created. Empty: form fields start empty. Success: the account and owner/manager identity are created, the user is verified, and lands in the protected area at Clients. Error: validation failures are shown inline per field; a submission failure (for example, an already-registered identity) is shown as an inline error and the form remains filled. Recovery: the user can correct the form and resubmit, or navigate to Login.

Clients

• Information and state. Protected. The agency's client records as a ruled table with columns for company, contact, status, last activity, and owner. Each row carries a visible left-edge colour bar coding client status. Records needing attention carry a gently pulsing status indicator dot.
• Primary actions. Open an individual client record (go to Client Details). Start creating a new client record (go to New Client).
• Supporting actions. Scan and compare records by company, contact, status, last activity, and owner; read status from the left-edge colour bar and the status dot.
• Domain entities. Client record (company name, contact, status, last activity, owner), agency, user.
• Component responsibilities. Ruled table with a header row using 11px uppercase micro-labels; per-row left-edge status colour bar; per-row status indicator dot; row hover highlight with a 2px left signal-red border; a control to create a new client; empty-state block when the agency has no client records.
• States. Loading: the table area shows a loading state while records are fetched. Empty: when the agency has no client records, an empty state explains that no clients have been added yet and offers the action to create the first one. Success: records render in the table; opening a row leads to Client Details. Error: if records fail to load, an error state explains the failure and offers retry; the create action remains available. Recovery: retry reloads the list; a failed open returns the user to the list with the error surfaced.

New Client

• Information and state. Protected. A form for creating a client record with identifying and contact details. Starts empty.
• Primary actions. Submit the form to create the client record.
• Supporting actions. Cancel and return to Clients without creating a record.
• Domain entities. Client record (company name, contact details, status, owner), agency, user.
• Component responsibilities. Client form with the identifying and contact fields, submit control, cancel control, inline per-field validation messaging.
• States. Loading: submit control shows a pending state while the record is being created. Empty: all fields start empty. Success: the record is created and the user is taken to the new record's Client Details view. Error: per-field validation errors are shown inline; a submission failure is shown as an inline error and the entered values are preserved. Recovery: the user can correct the form and resubmit, or cancel back to Clients.

Client Details

• Information and state. Protected. The full record for one client: identifying and contact details, status, owner, and the record's activity timeline. Two-column layout — record content in the wide column, metadata and activity timeline in the narrow column.
• Primary actions. Edit the client record's details and save the changes.
• Supporting actions. Review the record's metadata and activity timeline; return to Clients; for the owner/manager, proceed to remove the record (go to Client Removal).
• Domain entities. Client record (company name, contact details, status, owner, last activity), activity entries, agency, user.
• Component responsibilities. Record content block with editable fields and a save control; metadata block; activity timeline; numbered section micro-labels with full-width rules; a removal entry point visible only to the owner/manager.
• States. Loading: the record area shows a loading state while the record is fetched. Empty: not applicable for the record itself; if the activity timeline has no entries, the timeline shows an empty state rather than a blank column. Success: the record renders; edits save and the updated values are shown. Error: if the record fails to load, an error state explains the failure and offers retry or a return to Clients; if a save fails, an inline error is shown and the user's edits are preserved. Recovery: retry reloads the record; a failed save can be retried without re-entering the changes.

Client Removal

• Information and state. Protected and restricted to the owner/manager. Presents the client record that is about to be removed and the consequence of removal, so the owner/manager can confirm or abandon the action.
• Primary actions. Confirm removal of the client record.
• Supporting actions. Abandon the removal and return to the client record unchanged.
• Domain entities. Client record, agency, user, owner/manager role.
• Component responsibilities. Record summary of the client being removed; explicit confirmation control; abandon control; role-gated entry (recruiters do not reach this surface).
• States. Loading: the confirmation area shows a loading state while the record is fetched. Empty: not applicable. Success: the record is removed and the user returns to Clients, where the record no longer appears. Error: if the record fails to load, an error state explains the failure and offers retry or a return to the record; if removal fails, an inline error is shown and the record remains intact. Recovery: retry reloads the confirmation; a failed removal can be retried or abandoned.

3. Functional Requirements

FR-1 — SaaS client management for a recruitment company (explicit) As a recruitment agency, I should have a SaaS product that lets the agency manage its clients, so that client information lives in one organized place.

• Trigger/input: the agency uses the product.
• Observable result: the agency's client records are held and managed inside the product.
• Access state: the product is reachable; client records require a verified session.
• Failure/recovery: if the product is unreachable, the agency retries; no client data is lost.
• Continuation: the agency continues working with its client records in the product.

FR-2 — Keep and manage client information for the clients the agency serves (explicit) As a recruitment agency, I should be able to keep and manage client information for the clients the agency serves, so that the agency can serve those clients consistently.

• Trigger/input: the agency has client companies it serves.
• Observable result: each client the agency serves has a durable record in the product holding its information.
• Access state: verified session.
• Failure/recovery: if a record cannot be saved or loaded, the user is told and can retry without losing entered information.
• Continuation: the record remains available for later review and editing.

FR-3 — Self-service enrollment for the agency owner or manager (required_inference) As a recruitment agency owner or manager, I should be able to enroll myself in the product without an invitation or provisioning step, so that I can start managing the agency's clients.

• Trigger/input: the owner/manager has no existing account and chooses to start.
• Observable result: an agency account and an owner/manager identity with the owner/manager role exist, and the owner/manager is verified into the protected area.
• Access state: the enrollment interaction is anonymously reachable; protected client state remains unavailable until enrollment succeeds.
• Failure/recovery: validation and submission failures are shown inline with the entered values preserved; the owner/manager can correct and resubmit, or go to Login.
• Continuation: the owner/manager lands on Clients and can begin adding client records.

FR-4 — Returning verification for owners/managers and recruiters (required_inference) As a returning recruitment agency owner/manager or recruiter, I should be able to verify myself and re-enter the product, so that I can resume work on the agency's client records.

• Trigger/input: a returning user submits their credentials.
• Observable result: the user is verified and reaches the protected area at Clients.
• Access state: the verification interaction is anonymously reachable; protected client state remains unavailable until verification succeeds.
• Failure/recovery: invalid credentials produce an inline error and the user remains on Login and can retry.
• Continuation: the user resumes work on the agency's client records.

FR-5 — Role assignment distinguishing owner/manager removal authority from recruiter access (required_inference) As a recruitment agency owner or manager, I should be assigned the owner/manager role, and recruiters should be assigned the recruiter role, so that removal authority is held by the owner/manager while recruiters retain access to client records.

• Trigger/input: an identity is created (through enrollment or as a recruiter identity within the agency).
• Observable result: the identity carries a role; the owner/manager can reach Client Removal and recruiters cannot.
• Access state: verified session; Client Removal is role-restricted to the owner/manager.
• Failure/recovery: a recruiter who attempts to reach removal does not reach the removal surface and remains on the client record.
• Continuation: the owner/manager can complete removals; recruiters continue working with client records.

FR-6 — Backend persistence for durable client records and their lifecycle operations (required_inference) As the product, I should persist client records and their lifecycle operations durably, so that the agency's client information survives sessions and remains bound to the agency that created it.

• Trigger/input: a client record is created, edited, or removed.
• Observable result: the change is durably stored and is visible on the next read of the record.
• Access state: persistence is reached only through verified, agency-bound sessions.
• Failure/recovery: a failed write is reported to the user, who can retry; the previous stored state remains intact.
• Continuation: the stored record remains available for later reads and edits.

FR-7 — Browse the agency's client records (required_inference) As a recruitment agency owner/manager or recruiter, I should be able to browse the agency's client records in a list, so that I can see the state of the client base and find a specific client.

• Trigger/input: the user opens Clients.
• Observable result: the agency's client records are listed with company, contact, status, last activity, and owner.
• Access state: verified session.
• Failure/recovery: if the list fails to load, an error state offers retry.
• Continuation: the user opens a record or starts creating a new one.

FR-8 — Open an individual client record (required_inference) As a recruitment agency owner/manager or recruiter, I should be able to open an individual client record from the list, so that I can review that client's details.

• Trigger/input: the user selects a row in Clients.
• Observable result: the selected client's Client Details view is shown.
• Access state: verified session.
• Failure/recovery: if the record fails to load, an error state offers retry or a return to Clients.
• Continuation: the user reviews, edits, or (as owner/manager) proceeds to removal.

FR-9 — Create a client record with identifying and contact details (required_inference) As a recruitment agency owner/manager or recruiter, I should be able to create a client record with identifying and contact details, so that a new client the agency serves is captured in the product.

• Trigger/input: the user starts a new client from Clients and fills in the identifying and contact fields.
• Observable result: a new client record exists for the agency and is shown in its Client Details view.
• Access state: verified session.
• Failure/recovery: per-field validation errors are shown inline and entered values are preserved; the user can correct and resubmit or cancel back to Clients.
• Continuation: the new record appears in Clients and can be reviewed and edited.

FR-10 — Review and edit an existing client's details as the relationship changes (required_inference) As a recruitment agency owner/manager or recruiter, I should be able to review and edit the details of an existing client as the relationship changes, so that the agency's client information stays accurate.

• Trigger/input: the user opens a client record and changes one or more of its details.
• Observable result: the saved changes are reflected in the record and in the Clients list.
• Access state: verified session.
• Failure/recovery: if a save fails, an inline error is shown and the user's edits are preserved for retry.
• Continuation: the updated record remains available for later review.

FR-11 — Remove a client record the agency no longer manages (required_inference) As a recruitment agency owner or manager, I should be able to remove a client record that the agency no longer manages, so that the client base reflects only the clients the agency currently serves.

• Trigger/input: the owner/manager proceeds to removal from the client record and confirms.
• Observable result: the client record is removed and no longer appears in Clients.
• Access state: verified session with the owner/manager role; recruiters do not reach the removal surface.
• Failure/recovery: if removal fails, an inline error is shown and the record remains intact; the owner/manager can retry or abandon.
• Continuation: the owner/manager returns to Clients, which reflects the removal.

4. User Personas

Recruitment Agency Owner/Manager

Product context. The owner or manager runs the recruitment agency and is the person behind the request to manage the agency's clients. They are the one who brings the agency onto the product in the first place, and they are accountable for the state of the client base as a whole.

Primary goal. To have the agency's client information organized and trustworthy, so the agency can serve its clients consistently and the owner/manager can see what the agency is actually managing.

Distinct accepted responsibilities. The owner/manager is the only persona who establishes first use through self-service enrollment (FR-3), and the only persona who holds removal authority (FR-5, FR-11). They also browse, create, review, and edit client records like a recruiter does (FR-7, FR-8, FR-9, FR-10), but their distinguishing work is setting up the agency's account and deciding when a client record should leave the client base.

Relevant inputs and decisions. Their identity details at enrollment; the decision to remove a client record the agency no longer manages; the same client identifying and contact details any user enters or edits.

Interactions with other accepted participants. The owner/manager creates the agency account that recruiters work inside, and their role assignment is what separates removal authority from recruiter access. Recruiters depend on the client records the owner/manager helps keep accurate.

Observable success. The agency account exists, the owner/manager is verified into the product, client records are present and accurate in Clients, and a client the agency no longer manages is gone from the list after the owner/manager confirms its removal.

Recruitment Consultant/Recruiter

Product context. Recruiters at the agency are the day-to-day users who work with client companies. They live inside the client list and the individual client records rather than in account setup.

Primary goal. To find a client's information quickly and keep it accurate as engagements progress, so that the agency's client relationships stay usable across the team.

Distinct accepted responsibilities. Recruiters browse the agency's client records (FR-7), open individual records (FR-8), create new client records with identifying and contact details (FR-9), and review and edit existing client details as the relationship changes (FR-10). They verify themselves on return (FR-4). They do not hold removal authority (FR-5, FR-11).

Relevant inputs and decisions. Client identifying and contact details when adding or updating a record; which client to look up; what changed in a relationship that needs to be reflected in the record.

Interactions with other accepted participants. Recruiters work inside the agency account the owner/manager established, and they rely on the owner/manager for the removal decisions that are outside their authority. Their edits are what keep the shared client base accurate for the owner/manager.

Observable success. A client record is found and opened, a new client is captured, or an existing client's details are updated and saved — and the change is visible in the shared client list.

5. Core User Flows

Flow 1 — Agency owner/manager establishes first use and starts the client base

1. The owner/manager, who has no account, arrives at the anonymously reachable Landing page and reads what the product does: a SaaS tool that helps a recruitment company organize and manage its clients.
2. They follow the primary call to action to Sign Up.
3. On Sign Up, they enter the required identity information for the agency account and its owner/manager identity.
4. They submit. The account and the owner/manager identity are created with the owner/manager role, and the owner/manager is verified into the protected area.
5. They land on Clients, which is empty because the agency has no client records yet. The empty state explains this and offers the action to create the first client.
6. They choose to create a client and go to New Client.
7. On New Client, they enter the client's identifying and contact details and submit. The record is created and they are taken to its Client Details view.
8. They return to Clients, where the new record now appears in the ruled table with its company, contact, status, last activity, and owner.
9. Failure/recovery: if enrollment validation fails, errors are shown inline on Sign Up with their entries preserved, and they correct and resubmit. If the client record fails to save, an inline error is shown on New Client with their entries preserved, and they retry or cancel back to Clients.
10. Continuation: the owner/manager now has an agency account with a client base they can keep managing.

Flow 2 — Returning owner/manager or recruiter verifies and resumes work

1. A returning user arrives at the anonymously reachable Login page, either directly or from Landing.
2. They enter their credentials and submit.
3. Verification succeeds and they land on Clients, where the agency's client records are listed.
4. Failure/recovery: if the credentials are invalid, an inline error is shown and they remain on Login with the form filled so they can correct it and retry, or navigate to Sign Up if they do not have an account.
5. Continuation: the user resumes work on the agency's client records.

Flow 3 — Recruiter finds a client and reviews its record

1. A verified recruiter opens Clients.
2. They scan the ruled table by company, contact, status, last activity, and owner, reading status from each row's left-edge colour bar and noting any record whose status dot is pulsing because it needs attention.
3. They select the row for the client they need.
4. The client's Client Details view opens, showing the record content alongside its metadata and activity timeline.
5. Failure/recovery: if the list fails to load, an error state on Clients offers retry. If the selected record fails to load, an error state offers retry or a return to Clients.
6. Continuation: the recruiter has the client's information and can act on it or move on to another record.

Flow 4 — Recruiter captures a new client

1. A verified recruiter opens Clients and chooses to create a new client.
2. On New Client, they enter the client's identifying and contact details.
3. They submit. The record is created and they are taken to its Client Details view.
4. Failure/recovery: per-field validation errors are shown inline and their entries are preserved; they correct and resubmit, or cancel back to Clients without creating a record. If the submission fails, an inline error is shown and their entries are preserved for retry.
5. Continuation: the new client appears in Clients and is available to the whole agency.

Flow 5 — Recruiter updates a client's details as the relationship changes

1. A verified recruiter opens Clients and selects the client whose details have changed.
2. On Client Details, they review the current record content, metadata, and activity timeline.
3. They edit the details that have changed and save.
4. The saved changes are reflected in the record and in the Clients list.
5. *Failure