System Requirements Document for chinese-cars-stories

1. Introduction

chinese-cars-stories is a personal storytelling and publishing workspace for Chinonso Udeh (NG), who writes real-life stories about his own Chinese cars and posts them to X. The product exists to help the author turn genuine experiences and achievements with his cars into well-crafted story posts that generate engagement on X.

The audience is the author himself — a single storyteller with a point of view, not a review site, dealership, or hype brand. The product's job is to give him a quiet, well-set writing surface: a place to draft a story, shape it into a post, preview it as it will appear on X, publish it to his connected X account, and then see how each story performed. Success is measured by audience response on X.

The tone and posture of the product follow a warm editorial storytelling direction: cream paper ground, readable measure, flat hand-drawn illustration, and restrained motion — the feeling of opening a well-set essay rather than a SaaS pitch.

2. System Overview

chinese-cars-stories is a web application with a custom first-party interface and a shared backend. It provides:

• A public Landing page that explains, before any sign-in, that the product helps the author tell real-life stories about his Chinese cars on X.
• Self-service Sign Up and returning Login so the author's drafts and publication history persist and remain bound to him.
• A protected Stories overview listing the author's drafted and published car story posts with their X publication status and engagement.
• A protected New Story workspace for drafting a real-life car story about an experience or achievement, previewing it as an X post, and publishing it to X.

The single active human actor is the Car Story Author. X is an external recipient and provider: the author's X account is connected so that story posts can be published there, and engagement (audience response) is observed on X.

Current scope covers: writing real-life stories about the author's own Chinese cars, covering personal experiences and achievements; aiming those posts at generating engagement on X; self-service enrollment and returning verification; connecting the author's X account; and publishing story posts to X.

Narrow exclusions (not part of current scope): the product is not a review site, dealership, or hype brand; it does not cover cars other than the author's own Chinese cars; it does not provide stock automotive photography, glossy 3D car renders, or a dense dashboard of KPI tiles; it does not offer blue/indigo accents, gradients, glassmorphism, or a centred SaaS hero. No adjacent capabilities (e.g., multi-author collaboration, analytics suites beyond per-story engagement, or content about other people's vehicles) are introduced.

2a. Product Interpretation and Delivery Boundary

The product is delivered as a first-party web application with its own identity: the author enrolls himself, returns to verify, and his drafts and published story records are privately his. The Landing page is anonymously reachable and explains the product before sign-in; Sign Up and Login are anonymously reachable entry surfaces; Stories and New Story require login because they hold the author's durable, author-specific state.

Publishing is owned jointly: the author composes and commits the story in the first-party New Story workspace, and the actual post appears on X through the author's connected X account — X remains the external recipient and the place where engagement is observed. The product does not own X's feed, audience, or engagement mechanics; it owns the drafting, preview, publication trigger, status tracking, and the record of what was published and how it performed.

Everything described in this document is current. No future-horizon features are committed.

2b. Source Content Inventory

No content_source reference directive was supplied; this section is intentionally omitted.

2c. Page Content and Component Coverage

Landing

• Purpose / information: Anonymous first impression explaining that the product helps the author tell real-life stories about his Chinese cars on X, before any sign-in.
• Information and state: A small rust overline label "CAR STORIES · POSTED TO X"; an oversized Fraunces headline set in three ragged lines ("The road, the car, and what actually happened."); a 62ch paragraph explaining the product; a rust pill CTA "Start your first story"; a plain text link "See how it works"; a flat hand-drawn illustration of a Chinese EV on a mustard horizon with rust hills, bled off the right viewport edge; a small ink arrow curving from the illustration toward the first story row; below the fold, a hairline-ruled table of contents of recent story themes.
• Primary actions: "Start your first story" (leads to Sign Up); "See how it works" (in-page explanatory anchor).
• Supporting actions: Navigate to Login for returning authors.
• Domain entities: Story theme (title, numeral, engagement line) as illustrative preview content.
• Component responsibilities: Hero spread (left 7-column stack, right illustration); overline; headline; paragraph; CTA pill; text link; illustration with sketched arrow; hairline-ruled story-theme index.
• States: Loading (hero renders final state immediately; illustration strokes in over 900ms unless reduced motion); empty (no recent story themes — the index shows a quiet placeholder line); success (full hero and index); error (illustration fails to load — text and CTA remain fully usable); recovery (retry or proceed to Sign Up regardless).

Sign Up

• Purpose / information: Self-service enrollment establishing the author's account so durable story drafts and publication history are bound to him.
• Information and state: Fields for the author's identity (name, email, password); a short statement of what the account is for (drafting and publishing car stories to X); a link to Login for existing authors.
• Primary actions: Submit enrollment.
• Supporting actions: Navigate to Login.
• Domain entities: Author account.
• Component responsibilities: Form fields with labels and inline validation; submit button in rust; helper text in muted ink; link to Login.
• States: Loading (submit disabled with progress indication); empty (blank form); success (account created, author proceeds to connect X and reach Stories); error (invalid or already-used email, weak password — inline messages, form preserved); recovery (correct and resubmit; or go to Login if the account already exists).

Login

• Purpose / information: Returning verification so the author reaches his protected drafts and published story records.
• Information and state: Email and password fields; link to Sign Up.
• Primary actions: Submit credentials.
• Supporting actions: Navigate to Sign Up.
• Domain entities: Author account, session.
• Component responsibilities: Form fields; submit button; inline error region; link to Sign Up.
• States: Loading (submit disabled with progress indication); empty (blank form); success (author lands on Stories); error (incorrect credentials — inline message, no field cleared); recovery (retry; or use Sign Up if no account exists).

Stories

• Purpose / information: Recurring overview of the author's drafted and published car story posts with their X publication status and engagement.
• Information and state: A two-column index styled as a book's table of contents — a mustard two-digit story number in the left gutter, title and engagement line to the right, separated by hairline rules; each row carries a status chip pill ("Draft" in muted ink, "Published" in rust); a control to start a new story.
• Primary actions: Open a story row to continue drafting or review a published story; start a new story.
• Supporting actions: Read engagement metadata per published story.
• Domain entities: Story (number, title, status, engagement metadata, publication record).
• Component responsibilities: Story index rows with numeral, title, engagement line, status chip; hairline dividers; new-story control; empty-state message.
• States: Loading (rows skeleton or quiet placeholder); empty (no stories yet — a message inviting the author to start his first story); success (rows listed with statuses and engagement); error (list fails to load — retry control, no data loss); recovery (retry; published statuses remain accurate once loaded).

New Story

• Purpose / information: Focused workspace for drafting a real-life car story about an experience or achievement and publishing it to X.
• Information and state: A cream paper-sheet composer with title and body fields; a character counter pinned to the composer's lower-right corner; a live X-preview card beside the composer on desktop, stacked beneath on mobile, mirroring the post as it is typed; a status chip showing "Draft" until published; a publish action; a connection state for the author's X account.
• Primary actions: Write and edit the story; save as draft; publish to X.
• Supporting actions: Connect the X account when not yet connected; return to Stories.
• Domain entities: Story (title, body, status, character count), X account connection, publication record.
• Component responsibilities: Composer sheet; title and body inputs; pinned character counter; live X-preview card; status chip; publish button; X-connection prompt.
• States: Loading (existing draft loads into the composer); empty (blank composer with placeholder guidance about a real experience or achievement); success (draft saved; publish flips the status chip from Draft to Published with a 200ms crossfade and the story appears on X); error (X not connected — publish blocked with a prompt to connect; publish fails — story remains a draft with a clear message and retry); recovery (reconnect X or retry publish; the draft is never lost).

3. Functional Requirements

FR-1 — Write real-life stories about the author's Chinese cars. As a Car Story Author, I should be able to write stories about my own Chinese cars so that I can share them on X. (explicit)

• Trigger/input: the author opens New Story and enters a title and body.
• Observable result: the story is held as a draft bound to the author's account.
• Access: login required.
• Failure/recovery: if saving fails, the composer retains the text and offers retry.
• Continuation: the author can keep editing, save, or proceed to publish.

FR-2 — Stories cover personal experiences and achievements. As a Car Story Author, I should be able to write stories that cover my personal experiences and achievements with the cars so that the posts are genuinely real-life. (explicit)

• Trigger/input: the author writes narrative content describing an experience or achievement.
• Observable result: the story body carries that narrative and is previewed as an X post.
• Access: login required.
• Failure/recovery: none specific beyond FR-1's save failure handling.
• Continuation: the author refines the story and publishes.

FR-3 — Publish story posts to X. As a Car Story Author, I should be able to publish a finished story as a post to X so that it reaches my audience. (explicit)

• Trigger/input: the author selects publish on a story in New Story.
• Observable result: the story is posted to X through the author's connected X account, and its status chip flips from Draft to Published with a 200ms crossfade.
• Access: login required; X account connection required.
• Failure/recovery: if X is not connected, publish is blocked with a prompt to connect; if publishing fails, the story remains a draft with a clear message and retry.
• Continuation: the author returns to Stories and sees the story listed as Published.

FR-4 — Aim posts at generating engagement on X. As a Car Story Author, I should be able to see the engagement each published story generated on X so that I can judge which real-life stories resonate. (explicit)

• Trigger/input: the author opens Stories after publishing.
• Observable result: each published story row shows its engagement line alongside its title and status.
• Access: login required.
• Failure/recovery: if engagement cannot be retrieved, the row still shows the story and status with a muted unavailable indicator.
• Continuation: the author uses that signal when writing the next story.

FR-5 — Self-service enrollment. As a Car Story Author, I should be able to create my own account so that my drafts and publication history are durably mine. (required_inference)

• Trigger/input: the author submits the Sign Up form.
• Observable result: an account is created and the author proceeds toward protected work.
• Access: anonymous entry.
• Failure/recovery: invalid or already-used email or weak password shows inline errors with the form preserved; the author corrects and resubmits or goes to Login.
• Continuation: the author connects X and reaches Stories.

FR-6 — Returning verification. As a Car Story Author, I should be able to log back in so that I can reach my protected drafts and published story records. (required_inference)

• Trigger/input: the author submits credentials on Login.
• Observable result: the author lands on Stories with his own stories visible.
• Access: anonymous entry to Login; protected state only after verification.
• Failure/recovery: incorrect credentials show an inline message without clearing fields; the author retries or uses Sign Up.
• Continuation: the author opens a draft or starts a new story.

FR-7 — Connect the author's X account. As a Car Story Author, I should be able to connect my X account so that story posts can be published to X. (required_inference)

• Trigger/input: the author initiates the X connection from the New Story workspace when prompted.
• Observable result: the connection is established and bound to the author's account, and publish becomes available.
• Access: login required.
• Failure/recovery: if the connection is declined or fails, the prompt remains and the story stays a draft.
• Continuation: the author publishes the story.

FR-8 — Review drafted and published stories. As a Car Story Author, I should be able to see all my drafted and published stories with their X publication status so that I know what is still in progress and what is live. (required_inference)

• Trigger/input: the author opens Stories.
• Observable result: a table-of-contents index lists each story with a mustard numeral, title, engagement line, and a status chip (Draft in muted ink, Published in rust).
• Access: login required.
• Failure/recovery: if the list fails to load, a retry control appears and no data is lost.
• Continuation: the author opens a row to continue drafting or review a published story.

4. User Personas

Car Story Author

Product context. The Car Story Author is Chinonso Udeh (NG), a person with a point of view who owns Chinese cars and wants to tell the world what actually happened with them. He is not a review site, dealership, or hype brand — he is a storyteller building an audience on X through real experiences and achievements.

Primary goal. To turn genuine real-life stories about his Chinese cars into well-crafted posts on X that generate engagement.

Distinct accepted responsibilities.

• Drafting real-life stories about his own Chinese cars, covering personal experiences and achievements (FR-1, FR-2).
• Shaping each story into a post, previewing it as it will appear on X, and publishing it to his connected X account (FR-3, FR-7).
• Reviewing his drafted and published stories with their X publication status and engagement (FR-4, FR-8).
• Enrolling himself and returning to verify so his drafts and history remain his (FR-5, FR-6).

Relevant inputs and decisions. The narrative content of each story (title, body); the decision of when a story is ready to publish; the decision to connect his X account; the judgment of which stories resonated based on engagement.

Interactions with other accepted participants. The author is the sole active human actor. His counterparty is X — the external recipient where his posts appear and where his audience responds. He hands his finished story to X through his connected account and observes the audience's response there.

Observable success. A story he wrote appears as a post on X, its status chip reads Published, and its engagement line in Stories shows the audience response it generated.

Constraints. Story content is about his own Chinese cars and his real-life experiences and achievements with them.

5. Core User Flows

Flow A — First visit and enrollment

1. The Car Story Author arrives at the anonymous Landing page. He sees the rust overline "CAR STORIES · POSTED TO X", the oversized Fraunces headline "The road, the car, and what actually happened.", a paragraph explaining the product, the rust pill CTA "Start your first story", the plain text link "See how it works", and the hand-drawn Chinese EV illustration bleeding off the right edge with an ink arrow pointing into the page.
2. He selects "Start your first story" and is taken to Sign Up.
3. On Sign Up he enters his name, email, and password and submits.
4. On success his account is created and bound to him; he proceeds to connect his X account (Flow C) and then reaches Stories.
5. If enrollment fails (invalid or already-used email, weak password), inline errors appear with the form preserved; he corrects and resubmits, or follows the link to Login if he already has an account.

Flow B — Returning verification

1. The Car Story Author opens Login and enters his email and password.
2. On success he lands on Stories, where his own drafts and published stories are listed.
3. If credentials are incorrect, an inline message appears without clearing the fields; he retries, or uses the link to Sign Up if he has no account.

Flow C — Connecting the X account

1. From the protected New Story workspace, when the author attempts to publish without a connection, the product prompts him to connect his X account.
2. He initiates the connection and completes it with X.
3. The connection is established and bound to his account; publish becomes available.
4. If the connection is declined or fails, the prompt remains and his story stays a draft; he can retry the connection later without losing the draft.

Flow D — Writing and publishing a real-life story

1. From Stories, the Car Story Author selects the control to start a new story and lands on New Story.
2. He writes a title and body describing a real experience or achievement with one of his Chinese cars. The composer is a cream paper sheet; the character counter is pinned to its lower-right corner; the live X-preview card beside it (stacked beneath on mobile) mirrors the post as he types.
3. He refines the story until the preview reads the way he wants. The status chip reads Draft in muted ink.
4. He selects publish. The story is posted to X through his connected X account, and the status chip flips from Draft to Published with a 200ms crossfade.
5. If publishing fails, the story remains a draft with a clear message and a retry; his text is never lost. If X is not connected, publish is blocked with the prompt from Flow C.
6. He returns to Stories, where the story now appears as Published.

Flow E — Reviewing stories and engagement

1. The Car Story Author opens Stories. The page reads as a book's table of contents: a mustard two-digit numeral in the left gutter, title and engagement line to the right, separated by hairline rules, each row carrying a status chip.
2. He scans his drafts (muted "Draft" chips) and published stories (rust "Published" chips).
3. For a published story, he reads its engagement line to see the audience response it generated on X.
4. He opens a draft row to continue writing in New Story, or opens a published row to review it.
5. If the list fails to load, a retry control appears and no data is lost; once loaded, statuses remain accurate.
6. He uses what resonated to shape his next story, returning to Flow D.

6. Visuals, Colors and Theme

Muse and headline. Warm editorial storytelling after Frank Chimero — essays as interfaces. The register is human, reflective, and proud without being boastful. The landing page must feel like opening a well-set essay, not a SaaS pitch.

Palette (light mode).

• Background (cream paper ground, ~70% of every screen): #F5EFE4
• Surface (raised writing surface for cards and the composer): #FBF7EE
• Text (ink, all body and headings): #221E1A
• Primary (rust — the single action colour: primary buttons, links, active nav underline, ~8% of the page): #A6402A
• Accent (mustard — secondary mark only: story-index numerals, pull-quote rules, illustration fills): #C98A2E
• Muted (metadata, timestamps, helper text): #6E6459
• No blue anywhere; no gradients.

Typography.

• Headings: Fraunces at 500–600 with its soft "wonk" axis on for display sizes, tight leading (0.98–1.05), slight negative tracking on the biggest lines; sentence case, never all-caps. Headlines read like essay titles.
• UI labels and buttons: Work Sans at 500.
• Body: Source Serif 4.
• Scale: 1.333 modular on a 17px reading base — display clamp(44px, 8vw, 112px); section head clamp(30px, 4.4vw, 56px); story title 26px; body 17–19px with 1.65 line-height and a 62ch measure; metadata 13px letterspaced 0.04em.

Shape language. Soft but not bubbly: 10px radii on cards and inputs; 999px pills only for status chips (Draft / Published). Hairline 1px rules in a warm ink tint divide sections instead of shadows. Illustration is flat and hand-drawn — a car drawn as a confident single-weight outline with a mustard sun and rust hills, spot art in the margins, a hand-drawn arrow pointing from the hero into the story list.

Layout. Single-column editorial measure (max 680px) for prose, set off-centre on a 12-column page with a wide left margin so the page feels like a book. The Stories page breaks into a two-column index: a mustard story number in the left gutter, title and engagement line to the right, separated by hairlines — like a table of contents. The New Story composer is a paper sheet on the cream ground with the character counter pinned to its lower-right corner and a live X-preview card beside it on desktop, stacked beneath on mobile.

Imagery. Warm flat illustration drawn in the muse's hand: Chinese sedans and SUVs as clean single-weight outlines, road-trip vignettes (a charging cable, a mountain pass, a family in the back seat), rust and mustard fills on cream. No stock photography, no glossy car renders, no 3D. Author photos, when they appear, are small circular crops treated warm and desaturated.

Readability 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 (e.g., font-size: clamp(...) with its mobile size) to fit; no other element covers any part of them. Imagery and decoration may be cropped, bled off an edge, rotated, or overlapped as the direction asks, as long as they cover no readable text or control.

7. Signature Design Concept

The editorial spread. The first screen of the Landing page is not a centred SaaS hero but a two-part editorial spread on cream. On the left, a 7-column stack: a small rust overline "CAR STORIES · POSTED TO X"; an oversized Fraunces headline set in three ragged lines — "The road, the car, and what actually happened." — spanning most of the viewport width; a 62ch paragraph; a rust pill CTA "Start your first story" with a plain text link "See how it works" beside it. On the right, a flat hand-drawn illustration of a Chinese EV on a mustard horizon with rust hills, bled off the right edge of the viewport, with a small ink arrow curving from the illustration down toward the first story row. Below the fold, the page continues as a hairline-ruled table of contents of recent story themes. The whole hero is flat — no shadows, no gradient, no glass.

The concept recomposes only accepted content and controls: the product explanation, the CTA into Sign Up, the link to how it works, and the story-theme index. It introduces no new behaviour, page, or destination.

8. Interaction Model & Motion Direction

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

Landing Hero Motion Brief.

• Focal subject: the flat hand-drawn Chinese EV on a mustard horizon with rust hills, bleeding off the right viewport edge, with a sketched ink arrow curving toward the first story row.
• Input → transformation → outcome thesis: on load, the hero headline reveals line-by-line with a 60ms stagger and a soft 400ms ease-out, and the hand-drawn illustration strokes in left-to-right over 900ms — the page assembles like an essay being set, then settles into its final state, inviting the author to "Start your first story".
• Motion vocabulary: line-by-line headline reveal (60ms stagger, 400ms ease-out); left-to-right illustration stroke (900ms); hover on story rows slides the mustard numeral 4px left and underlines the title; publishing a story flips its status chip from Draft to Published with a 200ms crossfade.
• Composed first frame: cream ground; rust overline; oversized Fraunces headline in three ragged lines; 62ch paragraph; rust pill CTA and plain text link; illustration mid-stroke on the right with the ink arrow; hairline-ruled story-theme index below the fold.
• Reduced-motion state: with prefers-reduced-motion, everything renders in its final state — headline fully set, illustration fully stroked, no stagger, no slide, no crossfade animation (status changes apply instantly).

9. Non-Functional Requirements

• Durable author state. The author's drafts, published story records, and X account connection must persist across sessions and remain bound to his account. (required_inference — durable_state_required)
• Access control. Stories and New Story require login; Landing, Sign Up, and Login are anonymously reachable. Protected state is unavailable until identity is established. (required_inference — authentication_required)
• External publication integrity. A story must not be marked Published unless it was actually posted to X through the author's connected account; on failure it remains a Draft. (required_inference)
• Readability and accessibility. Readable text and controls stay whole at 375px, 768px, and 1280px; prefers-reduced-motion yields a usable static arrangement. (explicit — creative direction)
• Visual constraints. No blue or indigo accents, no gradients, no glassmorphism, no all-caps display type, no Inter/Roboto/Poppins, no glossy 3D car renders or stock automotive photography, no dense dashboard chrome, sidebars, or KPI tiles. (explicit — creative direction)
• Tone. Human, reflective, proud without being boastful; the product is not a review site, dealership, or hype brand. (explicit)

10. Tech Stack

• Frontend: React web application with the custom first-party pages described above.
• Backend: Python/FastAPI shared backend serving the application's routes and domain modules (author accounts, stories, X connection, publication records), reusing one process and port.
• Storage: Persistent storage for author accounts, stories (title, body, status), X account connections, and publication records.
• External integration: X API for connecting the author's account and publishing story posts; engagement data retrieved from X for published stories.
• Deployment: Docker / docker-compose for the frontend and backend services.

(Technology choices beyond the source are labeled defaults where unspecified; the source does not name a stack, so the above is a coherent minimal default consistent with the delivery shape.) [Default — not specified by user]

11. Assumptions and Constraints

• Constraint (explicit): Story content is about the author's own Chinese cars and his real-life experiences and achievements with them.
• Constraint (explicit): Posts are aimed at generating engagement on X.
• Assumption: The author has (or will create) an X account and is willing to connect it to the product for publishing.
• Assumption: Engagement data for published stories is available from X and can be displayed per story; if unavailable, the story and status still display with a muted indicator.
• Assumption: The product serves a single author (Chinonso Udeh); no multi-author collaboration or shared workspaces are in scope.
• Boundary: X owns the feed, audience, and engagement mechanics; the product owns drafting, preview, publication trigger, status tracking, and the record of published stories and their engagement.
• Boundary: No future-horizon features are committed in this document.

12. Glossary

• Car Story Author — The single active human user of the product: Chinonso Udeh, who writes real-life stories about his Chinese cars and posts them to X.
• Story — A real-life narrative about the author's Chinese cars covering a personal experience or achievement, drafted in the product and published as a post to X.
• Draft — A story saved but not yet published to X; shown with a muted "Draft" status chip.
• Published — A story that has been posted to X through the author's connected account; shown with a rust "Published" status chip.
• X account connection — The link between the author's product account and his X account that enables publishing story posts to X.
• Engagement — The audience response a published story generates on X, shown as an engagement line in the Stories index.
• Stories — The protected overview page listing the author's drafted and published stories with status and engagement, styled as a book's table of contents.
• New Story — The protected workspace where the author drafts, previews, and publishes a story to X.
• Live X-preview card — A card in New Story that mirrors the post as the author types, beside the composer on desktop and stacked beneath on mobile.