System Requirements Document for smoking-vaping

1. Introduction

smoking-vaping is a personal nicotine-recovery app for one person who wants to stop smoking cigarettes and vaping, and to end their nicotine addiction. The product exists to support a single, private, physically uncomfortable behaviour change: putting down cigarettes and vapes, and staying off nicotine one day at a time.

The app's intent is deliberately narrow. It helps the user set up and maintain a quit plan covering both smoking and vaping, see honest progress toward being nicotine-free (time since quitting, money and cigarettes/vapes avoided), log cravings and slips and review that history to understand triggers, and find support and guidance for managing cravings and withdrawal. It is not a clinical tool, not a social or competitive product, and not a gamified scoreboard. Its emotional register is relief and dignity — space where the smoke used to be.

The audience is the individual quitter themselves. There is no coach, clinician, or administrator role in the current product.

2. System Overview

smoking-vaping is delivered as a first-party web application with application-owned identity and durable per-user state.

Current delivery. A React frontend presents the product surfaces. A shared FastAPI backend provides the application APIs and domain modules for quit plans, progress, and craving/slip history. A MariaDB database stores application-owned persistent data. The frontend, backend, and database run as the provisioned services in the project's docker-compose inventory.

Actors. The only active human actor is the Person quitting smoking and vaping. The application itself (backend processes computing progress, persisting records, and serving guidance content) is a non-persona system actor.

Accepted behavior. The app supports quitting both smoking and vaping as one nicotine-addiction recovery effort. It provides self-service enrollment and returning verification so the user's durable quit data is reachable across sessions. Signed-in surfaces cover: setting up and maintaining a quit plan (quit date and current nicotine use for both smoking and vaping); viewing progress toward being nicotine-free (time since quitting, money or cigarettes/vapes avoided); logging cravings and slips and reviewing that history to understand triggers; and reading support and guidance for managing cravings and withdrawal.

Ownership. All product surfaces are first-party application pages. Identity is application-owned. There is no provider-owned or external-destination surface in the current product.

Exclusions. The current product does not include social features, leaderboards, clinician or coach roles, medication prescribing, or diagnostic claims.

Removed from scope

• None. No concept was explicitly removed by the user.

2a. Product Interpretation and Delivery Boundary

The user asked for an app to stop smoking and vaping and get rid of nicotine addiction. That request is the whole product intent; everything in this document elaborates it rather than extending it.

The app is a private, first-party web application. Because the user's quit plan, progress, and craving history are durable and personal, the app owns identity: a person enrolls themselves on first use and verifies themselves on return so their own data follows them. The anonymous entry surface (Landing) explains the app's purpose before sign-in; Sign Up and Login establish and verify identity; Quit Plan, Progress, Cravings, and Support are available only after sign-in.

Everything the app does for the user happens inside these first-party pages. There is no third-party account, no external service the user must visit, and no provider-owned surface in the current product. Backend computation (elapsed time, money and cigarette/vape counts avoided, history aggregation) is supporting system work behind the user's own pages, not a separate destination.

Future ideas are not part of the current product and are not represented in any current page or acceptance criterion.

2c. Page Content and Component Coverage

Landing

• Purpose and information/state. Anonymous public entry. Explains, before sign-in, that the app helps a person stop smoking and vaping and end nicotine addiction. Shows the product's quiet, paper-white identity and a single clear path into the product.
• Primary actions. "Start your quit" (leads to Sign Up); a secondary text link to Login for returning users.
• Supporting actions. None beyond navigation into Sign Up or Login.
• Domain entities. None persisted; static product explanation only.
• Component responsibilities. Hero statement and micro-label; one still-life image with hairline caption; primary and secondary entry controls; top navigation rule with wordmark and text links.
• States. Loading: static content, no spinner required. Empty: not applicable. Success: navigation to Sign Up or Login. Error: if the app cannot be reached, a plain retry message. Recovery: retry navigation.

Sign Up

• Purpose and information/state. Anonymous self-service enrollment. Collects the minimum credentials needed to create the user's account and begin their quit journey.
• Primary actions. Submit enrollment to create the account and sign the user in.
• Supporting actions. Link to Login for people who already have an account; link back to Landing.
• Domain entities. User account (identity credential and account record).
• Component responsibilities. Enrollment form with validation; submit control; inline error region; link to Login.
• States. Loading: submit disabled with pending indication. Empty: blank form. Success: account created, user signed in, routed to Quit Plan. Error: invalid or already-used credentials shown inline without losing entered values. Recovery: correct and resubmit.

Login

• Purpose and information/state. Anonymous returning verification so the user reaches their own durable quit plan, progress, and craving history.
• Primary actions. Submit credentials to sign in.
• Supporting actions. Link to Sign Up; link back to Landing.
• Domain entities. User account.
• Component responsibilities. Credential form; submit control; inline error region; links to Sign Up and Landing.
• States. Loading: submit disabled with pending indication. Empty: blank form. Success: signed in, routed to Quit Plan. Error: incorrect credentials shown inline without revealing which field was wrong. Recovery: correct and resubmit.

Quit Plan

• Purpose and information/state. Signed-in home for setting up and maintaining the quit plan: the quit date and the user's current nicotine use for both smoking and vaping. Presents the plan as a hairline-ruled label/value ledger.
• Primary actions. Set or update the quit date; record current smoking use and current vaping use; save the plan.
• Supporting actions. Navigate to Progress, Cravings, and Support.
• Domain entities. Quit plan (quit date, smoking-use entry, vaping-use entry, last-updated timestamp) owned by the signed-in user.
• Component responsibilities. Quit-date input; smoking-use and vaping-use fields; save control; ledger display of the saved plan; navigation rule.
• States. Loading: plan fetch pending. Empty: no plan yet — prompt to set a quit date and current use. Success: saved plan shown in the ledger with confirmation. Error: save or fetch failure shown inline with retry. Recovery: retry save without losing entered values.

Progress

• Purpose and information/state. Signed-in view of progress toward being nicotine-free: time since quitting, and money or cigarettes/vapes avoided. Numerals are the display voice.
• Primary actions. View current progress; refresh.
• Supporting actions. Navigate to Quit Plan, Cravings, and Support.
• Domain entities. Derived progress (elapsed time since quit date, money avoided, cigarettes/vapes avoided) computed from the user's quit plan.
• Component responsibilities. Large numeral displays; ledger of supporting label/value pairs; navigation rule.
• States. Loading: progress computation pending. Empty: no quit date set — prompt to complete the Quit Plan. Success: numerals and ledger shown. Error: computation or fetch failure with retry. Recovery: retry, or navigate to Quit Plan to complete missing input.

Cravings

• Purpose and information/state. Signed-in logging of cravings and slips, and review of that history to understand triggers.
• Primary actions. Log a craving; log a slip; view craving and slip history.
• Supporting actions. Navigate to Quit Plan, Progress, and Support.
• Domain entities. Craving entry (timestamp, optional trigger/note); slip entry (timestamp, optional note); history list owned by the signed-in user.
• Component responsibilities. Log-craving control; log-slip control; history list as hairline-ruled rows; navigation rule.
• States. Loading: history fetch pending. Empty: no entries yet — prompt to log the first craving. Success: new entry appears in history with confirmation. Error: log or fetch failure with retry. Recovery: retry without duplicating the entry.

Support

• Purpose and information/state. Signed-in support and guidance for managing cravings and withdrawal while quitting.
• Primary actions. Read guidance on managing cravings and withdrawal.
• Supporting actions. Navigate to Quit Plan, Progress, and Cravings.
• Domain entities. Guidance content served by the application.
• Component responsibilities. Guidance sections in the ruled, micro-caps-over-statement rhythm; navigation rule.
• States. Loading: content fetch pending. Empty: not applicable (content is provided). Success: guidance displayed. Error: content fetch failure with retry. Recovery: retry.

3. Functional Requirements

FR-1 — Quit both smoking and vaping as one effort (explicit) As a person quitting smoking and vaping, I should be able to use the app to stop both cigarettes and vaping as part of one nicotine-addiction recovery effort, so that my quit is treated as a single goal rather than two separate ones.

• Trigger/input: the user opens the app and begins their quit.
• Observable result: the app frames and supports quitting both smoking and vaping together.
• Access: anonymous on Landing; signed-in on product surfaces.
• Failure/recovery: if the app is unreachable, a plain retry message is shown.
• Continuation: the user proceeds to enroll or sign in and set up their quit plan.

FR-2 — Self-service enrollment (required_inference) As a person quitting smoking and vaping, I should be able to create my own account on first use, so that my quit data is mine and can be resumed later.

• Trigger/input: the user chooses to start their quit from Landing and submits enrollment credentials on Sign Up.
• Observable result: an account is created and the user is signed in.
• Access: anonymous entry on Sign Up.
• Failure/recovery: invalid or already-used credentials are shown inline without losing entered values; the user corrects and resubmits.
• Continuation: the user is routed to Quit Plan.

FR-3 — Returning verification (required_inference) As a person quitting smoking and vaping, I should be able to sign back in, so that I can reach my own durable quit plan, progress, and craving history.

• Trigger/input: the user submits credentials on Login.
• Observable result: the user is signed in and routed to Quit Plan.
• Access: anonymous entry on Login; protected surfaces available after sign-in.
• Failure/recovery: incorrect credentials are shown inline without revealing which field was wrong; the user corrects and resubmits.
• Continuation: the user resumes their quit work.

FR-4 — Set up and maintain the quit plan (required_inference) As a person quitting smoking and vaping, I should be able to set my quit date and record my current nicotine use for both smoking and vaping, and update them later, so that the app reflects my actual quit.

• Trigger/input: the user enters or edits the quit date and current smoking and vaping use on Quit Plan and saves.
• Observable result: the saved plan is shown in the ledger with confirmation.
• Access: signed-in.
• Failure/recovery: save or fetch failure is shown inline with retry; entered values are preserved.
• Continuation: the user moves to Progress or Cravings.

FR-5 — View progress toward being nicotine-free (required_inference) As a person quitting smoking and vaping, I should be able to see time since quitting and money or cigarettes/vapes avoided, so that I have honest evidence of progress.

• Trigger/input: the user opens Progress.
• Observable result: elapsed time since the quit date and money or cigarettes/vapes avoided are displayed as numerals with a supporting ledger.
• Access: signed-in.
• Failure/recovery: if no quit date is set, the user is prompted to complete the Quit Plan; computation or fetch failure offers retry.
• Continuation: the user returns to Quit Plan, Cravings, or Support.

FR-6 — Log cravings and slips (required_inference) As a person quitting smoking and vaping, I should be able to log a craving and log a slip, so that I record what is actually happening.

• Trigger/input: the user activates log-craving or log-slip on Cravings.
• Observable result: the new entry appears in the history with confirmation.
• Access: signed-in.
• Failure/recovery: log failure offers retry without duplicating the entry.
• Continuation: the user reviews history or moves to Support.

FR-7 — Review craving and slip history to understand triggers (required_inference) As a person quitting smoking and vaping, I should be able to review my craving and slip history, so that I can understand my triggers.

• Trigger/input: the user opens Cravings.
• Observable result: the history is listed as hairline-ruled rows.
• Access: signed-in.
• Failure/recovery: fetch failure offers retry.
• Continuation: the user adjusts their plan or reads Support.

FR-8 — Support and guidance for cravings and withdrawal (required_inference) As a person quitting smoking and vaping, I should be able to read support and guidance for managing cravings and withdrawal, so that I can get through difficult moments while quitting.

• Trigger/input: the user opens Support.
• Observable result: guidance is displayed.
• Access: signed-in.
• Failure/recovery: content fetch failure offers retry.
• Continuation: the user returns to Cravings or Progress.

4. User Personas

Person quitting smoking and vaping

• Product context. An adult in Pakistan ending nicotine addiction across both cigarettes and vaping. The struggle is private, often shame-tinged, and physically uncomfortable. They want calm, dignity, and small honest wins — not hype, alarm, or a scoreboard.
• Primary goal. Stop smoking and vaping and stay nicotine-free, one day at a time.
• Distinct accepted responsibilities. Enroll themselves and sign in on return; set and maintain a quit plan covering quit date and current nicotine use for both smoking and vaping; view progress toward being nicotine-free including time since quitting and money or cigarettes/vapes avoided; log cravings and slips and review that history to understand triggers; read support and guidance for managing cravings and withdrawal.
• Relevant inputs or decisions. Their quit date; their current smoking and vaping use; when to log a craving or a slip; whether to update their plan.
• Interactions with other accepted participants. None — this is a single-person product. The application itself computes progress and serves guidance.
• Observable success. A saved quit plan, visible progress numerals, a growing craving/slip history they can review, and guidance they can reach when a craving hits.

5. Core User Flows

Flow A — First use: enroll and set up the quit plan

1. The person opens the app anonymously and lands on Landing, which explains that the app helps them stop smoking and vaping and end nicotine addiction.
2. They choose Start your quit and arrive at Sign Up.
3. They enter enrollment credentials and submit. On success they are signed in and routed to Quit Plan; on invalid or already-used credentials they see an inline error, correct it, and resubmit.
4. On Quit Plan they set their quit date and record current smoking use and current vaping use, then save.
5. The saved plan appears in the ledger with confirmation. They continue to Progress or Cravings.

Flow B — Returning: sign in and resume

1. The person opens the app and chooses Login from Landing.
2. They submit credentials. On success they are routed to Quit Plan; on incorrect credentials they see an inline error without learning which field was wrong, correct it, and resubmit.
3. They resume their quit work from Quit Plan.

Flow C — Check progress

1. From a signed-in surface the person opens Progress.
2. If no quit date is set, they are prompted to complete the Quit Plan; otherwise they see time since quitting and money or cigarettes/vapes avoided as numerals with a supporting ledger.
3. If computation or fetch fails, they retry. They continue to Cravings or Support.

Flow D — Log a craving or slip and review history

1. The person opens Cravings.
2. They activate log-craving or log-slip. The new entry appears in the history with confirmation; on failure they retry without duplicating the entry.
3. They review the history to understand their triggers.
4. They continue to Support or Progress.

Flow E — Get support through a craving or withdrawal

1. The person opens Support.
2. They read guidance on managing cravings and withdrawal.
3. If content fails to load, they retry. They return to Cravings or Progress.

6. Visuals Colors and Theme

The creative direction is authoritative: Emptiness as content — a quiet white room for the hardest thing you'll ever stop doing. Muse: Kenya Hara. Headline idea: "Put it down. Keep the air."

Color tokens (light mode).

• Background (paper field): #F4F1EA
• Surface (cards, half-shade lighter): #FBF9F4
• Text (charcoal ink): #23231F
• Primary (moss-charcoal action): #3E4A3F
• Accent (ember, one per screen): #C2542A
• Muted (labels, micro-caps, rules): #8C877B
• Hairline rule: #DCD6C9

Proportion: ~80% paper, 15% ink/greys, 5% ember. No gradients, no glass, no blue, no indigo.

Typography. Headings and body: Zen Kaku Gothic New. Headings Light 300 at very large sizes, tracking 0.02em, leading 1.15, sentence case only. Body 17px/1.7. Micro-labels 11px, 600 weight, 0.18em letterspacing, uppercase, muted — the only caps in the system. Numerals are the display voice: clamp(48px, 9vw, 120px), weight 200, tabular figures. Scale 1.5 modular: 12 / 14 / 17 / 24 / 36 / 56 / 88. Display headline clamp(40px, 7vw, 88px) light 300; page title clamp(28px, 4vw, 44px).

Shape language. Square and near-square: 2px radii on inputs and buttons, 0px on panels and images. Hairline 1px rules in #DCD6C9 divide everything. Buttons are full-width rectangles with a 1px ink border and transparent fill, filling solid moss only on the primary. Nothing pill-shaped, nothing floating, no shadows anywhere — depth comes from tone and rule.

Layout. Centred single-column composition with enormous margins: content measure max 560px on a 1280px canvas, 24px gutters at 375px. Vertical rhythm 96–160px between sections on desktop, 56–72px on mobile. Each screen opens with one micro-label, one whisper-large statement, then a single primary action; everything else is a ruled list of label/value pairs aligned on a shared baseline. Navigation is a thin top rule with wordmark left and four text links right; on mobile it collapses to a bottom rule with the four words, no icons. Progress and Cravings are lists of thin horizontal rules, never cards in a grid.

Imagery. Still-life only, softly lit on plain paper grounds: an empty ashtray, a vape pen laid down and out of frame, a folded hand, a bowl of water, a match unlit, morning light on a windowsill. Monochrome or near-monochrome with one warm ember tone. Images sit full-bleed to one column edge, cropped square or 4:5, always with a hairline rule beneath and a caption in micro-caps. No stock people smiling, no lungs diagrams, no before/after bodies, no illustration.

Accessibility. Readable text and controls stay whole at 375px, 768px, and 1280px, wrapping or scaling to fit; imagery and decoration may bleed off edges but never cover text or controls.

7. Signature Design Concept

The public entry (Landing) is a single tall paper-white column, off-centre left on desktop (max 560px starting at 18% from the left). Above the headline sits an 11px tracked micro-label: SMOKING · VAPING · NICOTINE. The headline "Put it down. Keep the air." is set in charcoal at clamp(40px, 7vw, 88px), light 300, stacked across three lines with wide leading. Beneath a thin rule, one line of 17px muted body copy, then a full-width 2px-bordered rectangle button "Start your quit" with an ember dot at its right edge.

The entire right half of the viewport is empty paper except one square 4:5 still-life photograph — an empty ashtray in morning light — bleeding off the right edge, sitting low, with a hairline caption in micro-caps. No gradient, no blob, no illustration, no centred stack. The emptiness is the message and the layout: space where the smoke used to be.

8. Interaction Model & Motion Direction

Interaction Model: Static (direction) Motion Tempo: still Hero Dimensionality: flat

Landing Hero Motion Brief. Focal subject: the empty ashtray still-life in morning light, bleeding off the right edge. Input→transformation→outcome thesis: the page arrives as a composed still frame; on arrival the headline and body fade in once over 400ms on the paper ground, and the ember dot beside "Start your quit" fades in once over 200ms — nothing else moves. Motion vocabulary: single opacity fades, no bounce, no parallax, no looping animation, no timer-driven motion. Composed first frame: micro-label, three-line headline, hairline rule, muted body line, bordered button with ember dot, and the still-life photograph low on the right. Reduced-motion state: all fades become instant cuts; the composed frame renders final.

9. Non-Functional Requirements

• Durable per-user state (required_inference). Quit plan, craving/slip history, and derived progress persist in the application database and are bound to the signed-in user, so returning verification restores them. Rationale: the accepted journeys require resuming the user's own quit data.
• Identity continuity (required_inference). Sign Up and Login are anonymously reachable; Quit Plan, Progress, Cravings, and Support require sign-in. Rationale: durable actor-specific state must remain bound to the correct participant.
• Calm motion (explicit, creative direction). No motion that could read as pressure; prefers-reduced-motion renders instant cuts and final values.
• Readability at all viewports (explicit, creative direction). Text and controls remain whole and uncovered at 375px, 768px, and 1280px.
• No clinical claims (basic_default). The app presents guidance and progress, not diagnosis or prescribing.

10. Tech Stack

• Frontend: React application UI.
• Backend: shared FastAPI process for application APIs and domain modules (quit plan, progress computation, craving/slip history, guidance content).
• Database: MariaDB for application-owned persistent data.
• Deployment: docker-compose with the provisioned frontend, backend, and database services. No additional services are required for the current workflows.

11. Assumptions and Constraints

• A-1 (required_inference). The product serves a single human actor; no coach, clinician, or administrator role exists in the current product.
• A-2 (required_inference). Identity is application-owned and self-service; there is no invitation or provisioning flow.
• A-3 (basic_default). Guidance content on Support is provided by the application; no external content provider is integrated.
• A-4 (basic_default). Money avoided on Progress is derived from the user's recorded use and quit date; the exact currency and per-unit cost inputs are unspecified by the user and are filled as a coherent default within the quit plan.
• A-5 (explicit). No social, competitive, or gamified features are included.

12. Glossary

• Quit plan — The user's saved quit date and current nicotine use for both smoking and vaping.
• Craving — A logged moment of urge to smoke or vape.
• Slip — A logged instance of smoking or vaping after the quit date.
• Nicotine-free progress — Elapsed time since the quit date plus money and cigarettes/vapes avoided, derived from the quit plan.
• Micro-caps — 11px uppercase labels at 0.18em letterspacing in muted tone, the only caps in the design system.
• Ember accent — The single #C2542A hot accent used at most once per screen on the live action.