System Requirements Document for money-currency

1. Introduction

money-currency is a first-party web product for launching and using a new digital currency called cash pull, in the style of Bitcoin. The requester, Jhovany Beltran (US), asked to start his own money currency like Bitcoin, named cash pull. This document is the System Requirements Document for that product.

The product intent is narrow and concrete: a Currency Creator starts cash pull and sets its name; the product shows the cash pull currency and its current supply; a Currency Holder holds a cash pull balance, sees it, sends cash pull to another user, receives cash pull from another user, and sees the record of cash pull transfers. Because holding, sending, and receiving currency are durable, actor-bound obligations, the product establishes application-owned identity: new users enroll through self-service Sign Up, returning users verify identity at Login, and protected cash pull state is reachable only after identity is established.

Audience: the Currency Creator who launches cash pull, and the Currency Holders who acquire, hold, send, and receive it.

Success Criteria

• A new visitor can understand what cash pull is from the anonymous Landing page and reach Sign Up.
• A Currency Creator can start cash pull with the name cash pull and see its current supply on Currency.
• A Currency Holder can see a balance on Wallet, send cash pull from Send, receive cash pull from Receive, and see the resulting transfer record.
• Supply and balances are displayed as exact tabular numerals; every transfer appears in the record with its amount and direction.

2. System Overview

2a. Product Interpretation and Delivery Boundary

money-currency is delivered as a first-party web application: a React frontend, a shared FastAPI backend process for all application APIs and domain modules, and a MariaDB database for application-owned persistent data. All currency state — the cash pull currency definition, its supply, holder balances, and the transfer record — is owned and persisted by the application.

Access is application-owned. Landing, Sign Up, and Login are anonymously reachable. Currency requires login. Create Currency is restricted to the Currency Creator role; Wallet, Send, and Receive are restricted to the Currency Holder role. Identity is established at Sign Up and verified at Login; a protected destination never establishes access to itself.

Current scope is exactly the accepted behavior in this document: starting cash pull, showing the currency and its supply, holding and viewing a balance, sending, receiving, and viewing the transfer record. Nothing beyond that — no trading, exchange, mining, staking, fiat on/off-ramp, or market pricing — is part of the current product.

2b. Source Content Inventory

Not applicable — no reference directive with content_source was supplied.

2c. Page Content and Component Coverage

Landing

• Information/state: anonymous public entry. Oversized cash pull wordmark, a one-line statement of what cash pull is, and a live current supply counter in JetBrains Mono with a tangerine rule beneath it.
• Primary action: solid tangerine Sign Up block, left-aligned. Supporting action: Login link for returning users.
• Domain entities: cash pull currency (name, current supply).
• Component responsibilities: hero wordmark (Space Grotesk, tight tracking, clamp(44px, 7vw, 104px)); supply counter (tabular figures, counts up once on load); primary CTA block; secondary login link.
• States: loading — supply counter shows a placeholder rule until supply resolves; empty — if supply is unavailable, show the wordmark and CTA with the counter omitted rather than a broken number; success — supply renders; error — supply fetch failure shows a muted "supply unavailable" note while the CTA stays usable; recovery — retry on next load.

Sign Up

• Information/state: anonymous enrollment form for a new user who will hold and control cash pull.
• Primary action: create the account and establish identity. Supporting action: link to Login for users who already have an account.
• Domain entities: user identity (name, email, password).
• Component responsibilities: labeled inputs with inline validation; submit control as solid tangerine block; error summary region.
• States: loading — submit disabled with progress indication; empty — pristine form; success — identity established and the user is taken into protected cash pull work; error — invalid or already-registered email shown inline with the field preserved; recovery — correct and resubmit.

Login

• Information/state: anonymous verification form for a returning user.
• Primary action: verify identity and reach protected cash pull state. Supporting action: link to Sign Up.
• Domain entities: user identity.
• Component responsibilities: email and password inputs; submit control; error region.
• States: loading — submit disabled; empty — pristine form; success — session established and the user continues to protected work; error — incorrect credentials shown without revealing which field failed; recovery — retry.

Create Currency

• Information/state: role-restricted to the Currency Creator. Form to start cash pull, with the currency name fixed to cash pull.
• Primary action: start cash pull. Supporting action: return to Currency once created.
• Domain entities: cash pull currency (name, initial supply, creator).
• Component responsibilities: name field (pre-filled and locked to "cash pull"); initial supply input in tabular numerals; submit block; confirmation state.
• States: loading — submit disabled; empty — pristine form; success — currency created, confirmation shown, and the creator is routed to Currency; error — validation or duplicate-creation error shown inline; recovery — correct and resubmit. If cash pull already exists, the form is replaced by a link to Currency.

Currency

• Information/state: login-required. Shows the cash pull currency and its current supply as a large tabular numeral with a thin tangerine underline.
• Primary actions: none beyond navigation. Supporting actions: links to Wallet, Send, Receive for holders; Create Currency for the creator when cash pull does not yet exist.
• Domain entities: cash pull currency, current supply.
• Component responsibilities: currency header; supply figure (JetBrains Mono, tabular); hairline-ruled summary rows.
• States: loading — supply skeleton with the rule in place; empty — if cash pull has not been started, show a muted note and, for the creator, the Create Currency action; success — supply renders; error — supply fetch failure with retry; recovery — retry.

Wallet

• Information/state: role-restricted to the Currency Holder. Shows the holder's cash pull balance as a large tabular numeral and the record of cash pull transfers as hairline-ruled rows with right-aligned amounts and a small green gain tag on incoming transfers.
• Primary actions: Send and Receive entry controls. Supporting action: link to Currency.
• Domain entities: balance, transfer record entries (direction, counterparty, amount, timestamp).
• Component responsibilities: balance figure (counts up once on load); ledger table with right-aligned tabular amounts; gain tags; row rules.
• States: loading — balance skeleton and ruled row placeholders; empty — zero balance and an empty ledger message with Send/Receive still available; success — balance and rows render; error — fetch failure with retry; recovery — retry.

Send

• Information/state: role-restricted to the Currency Holder. Form to send cash pull to another user, showing the sender's available balance.
• Primary action: send the amount. Supporting action: cancel back to Wallet.
• Domain entities: transfer (sender, recipient, amount, timestamp, status).
• Component responsibilities: recipient identifier input; amount input in tabular numerals; available-balance readout; submit block; result region.
• States: loading — submit disabled; empty — pristine form; success — confirmation with the new balance and a link to Wallet; error — insufficient balance, unknown recipient, or invalid amount shown inline; recovery — correct and resubmit.

Receive

• Information/state: role-restricted to the Currency Holder. Shows the holder's receiving identifier and the incoming cash pull that has arrived, with the updated balance.
• Primary action: share the receiving identifier. Supporting action: link to Wallet.
• Domain entities: receiving identifier, incoming transfers, balance.
• Component responsibilities: identifier display with copy control; incoming transfer list with right-aligned amounts and green gain tags; balance readout.
• States: loading — identifier and list skeletons; empty — no incoming transfers yet, with the identifier still shown; success — incoming transfers and balance render; error — fetch failure with retry; recovery — retry.

3. Functional Requirements

FR-1 — Start cash pull. As a Currency Creator, I should start a new digital currency named cash pull, in the style of Bitcoin, so that holders can use it. (explicit)

• Trigger: the creator submits the Create Currency form. Input: currency name fixed to "cash pull", initial supply. Observable result: the cash pull currency exists with its supply and creator. Access: login required, Currency Creator role. Failure: validation error or cash pull already exists — shown inline, no duplicate created. Continuation: routed to Currency.

FR-2 — Show the currency and its current supply. As a Currency Creator or Currency Holder, I should see the cash pull currency and its current supply, so that I know how much exists. (explicit)

• Trigger: opening Currency. Observable result: the currency name and current supply render as tabular numerals. Access: login required. Failure: supply fetch failure shows a retry. Continuation: navigate to Wallet, Send, or Receive.

FR-3 — Hold and see a balance. As a Currency Holder, I should hold a cash pull balance and see it, so that I know what I can send. (explicit)

• Trigger: opening Wallet. Observable result: the holder's balance renders as a tabular numeral and updates after sends and receives. Access: login required, Currency Holder role. Failure: fetch failure with retry. Continuation: proceed to Send or Receive.

FR-4 — Send cash pull. As a Currency Holder, I should send cash pull to another user, so that value moves to them. (explicit)

• Trigger: submitting the Send form with recipient and amount. Observable result: the sender's balance decreases, the recipient's balance increases, and a transfer entry is recorded. Access: login required, Currency Holder role. Failure: insufficient balance, unknown recipient, or invalid amount — shown inline, no transfer recorded. Continuation: confirmation with the new balance and a link to Wallet.

FR-5 — Receive cash pull. As a Currency Holder, I should receive cash pull from another user, so that my balance grows. (explicit)

• Trigger: another holder sends cash pull to my receiving identifier. Observable result: my balance increases and the incoming transfer appears on Receive and in my Wallet record. Access: login required, Currency Holder role. Failure: a send to an unknown identifier does not create a transfer and the sender sees an error. Continuation: the holder sees the updated balance and can send onward.

FR-6 — Show the record of transfers. As a Currency Holder, I should see the record of cash pull transfers, so that I can verify what moved. (explicit)

• Trigger: opening Wallet or Receive. Observable result: hairline-ruled rows with direction, counterparty, right-aligned amount, and timestamp; incoming rows carry a green gain tag. Access: login required, Currency Holder role. Failure: fetch failure with retry. Continuation: rows remain available on revisit.

FR-7 — Self-service enrollment. As a new user, I should complete self-service enrollment before protected cash pull work, so that I can hold and control cash pull. (required_inference)

• Trigger: submitting Sign Up. Input: name, email, password. Observable result: identity established and the user enters protected work. Access: anonymous. Failure: invalid or already-registered email shown inline with input preserved. Continuation: proceed to protected cash pull work.

FR-8 — Returning verification. As a returning user, I should verify identity at Login, so that I can reach my protected cash pull state. (required_inference)

• Trigger: submitting Login. Observable result: session established and the user continues to protected work. Access: anonymous. Failure: incorrect credentials shown without revealing which field failed. Continuation: retry or use Sign Up.

FR-9 — Start cash pull before holders use it. As a Currency Creator, I should start cash pull before holders use it, so that there is a currency to hold. (required_inference)

• Trigger: the creator completes Create Currency. Observable result: cash pull exists and is available to holders. Access: login required, Currency Creator role. Failure: duplicate creation blocked with a link to Currency. Continuation: the creator monitors supply on Currency.

4. User Personas

Currency Creator

• Product context: the person who launches cash pull. They arrive at Landing, enroll at Sign Up, and use Create Currency to start the currency with its name fixed to cash pull and an initial supply.
• Primary goal: establish cash pull and follow its supply and use.
• Distinct responsibilities: starting the currency (FR-1, FR-9); reading the current supply on Currency (FR-2).
• Inputs and decisions: the initial supply; confirming the fixed name "cash pull"; deciding when to start.
• Interactions with other participants: the creator's act of starting cash pull is the prerequisite for every Currency Holder's balance, send, and receive. The creator observes supply as holders move value.
• Observable success: cash pull exists, Currency shows its current supply, and the creator can see the currency in use.

Currency Holder

• Product context: a user who acquires and holds cash pull. They enroll at Sign Up or verify at Login, then work in Wallet, Send, and Receive.
• Primary goal: hold cash pull, move it to and from other holders, and verify the record.
• Distinct responsibilities: holding and seeing a balance (FR-3); sending (FR-4); receiving (FR-5); reading the transfer record (FR-6); reading the currency and supply (FR-2).
• Inputs and decisions: recipient identifier and amount when sending; whether to share their receiving identifier; reading the ledger to confirm movement.
• Interactions with other participants: every send has a receiving holder whose balance and record change; every receive originates from another holder's send. The holder also depends on the Currency Creator having started cash pull.
• Observable success: the balance reflects sends and receives, incoming transfers carry a green gain tag, and the record matches what moved.

5. Core User Flows

Flow A — Currency Creator starts cash pull

1. The creator opens Landing anonymously and reads the cash pull wordmark and current supply counter.
2. The creator selects the tangerine Sign Up block and completes enrollment on Sign Up; identity is established and the creator enters protected work.
3. The creator opens Create Currency (Currency Creator role). The name field is fixed to cash pull; the creator enters an initial supply.
4. The creator submits. On success, cash pull exists and the creator is routed to Currency, which shows the current supply as a tabular numeral.
5. If cash pull already exists, the form is replaced by a link to Currency; the creator continues there.
6. Continuation: the creator revisits Currency to follow supply as holders move value.

Flow B — Currency Holder enrolls and views balance

1. The holder opens Landing anonymously and selects Sign Up.
2. The holder completes Sign Up; identity is established.
3. The holder opens Wallet (Currency Holder role). The balance renders as a tabular numeral and counts up once on load; the ledger shows hairline-ruled rows.
4. If the balance is zero, the ledger shows an empty message with Send and Receive still available.
5. Continuation: the holder proceeds to Send or Receive.

Flow C — Currency Holder sends cash pull

1. From Wallet, the holder selects Send.
2. The holder enters the recipient identifier and the amount, seeing the available balance.
3. The holder submits. On success, the sender's balance decreases, the recipient's balance increases, and a transfer entry is recorded; the confirmation shows the new balance.
4. Failure: insufficient balance, unknown recipient, or invalid amount is shown inline and no transfer is recorded; the holder corrects and resubmits.
5. Continuation: the holder returns to Wallet, where the new outgoing row appears in the record.

Flow D — Currency Holder receives cash pull

1. The holder opens Receive and shares their receiving identifier with another holder.
2. The other holder sends cash pull to that identifier from Send.
3. The receiving holder's balance increases; the incoming transfer appears on Receive and in the Wallet record with a green gain tag and a right-aligned amount.
4. Failure: a send to an unknown identifier creates no transfer and the sender sees an error; the receiving holder sees no change.
5. Continuation: the holder can send the received cash pull onward from Send.

Flow E — Currency Holder reviews the transfer record

1. The holder opens Wallet (or Receive).
2. The ledger renders hairline-ruled rows with direction, counterparty, right-aligned tabular amount, and timestamp; incoming rows carry a green gain tag.
3. If the fetch fails, a retry is offered; on retry the rows render.
4. Continuation: the holder uses the record to confirm a send or receive, then returns to Send or Receive as needed.

Flow F — Returning user verifies identity

1. The returning user opens Landing and selects Login.
2. The user submits credentials on Login. On success, a session is established and the user continues to protected cash pull work.
3. Failure: incorrect credentials are shown without revealing which field failed; the user retries or uses Sign Up.
4. Continuation: the user proceeds to Currency, Wallet, Send, or Receive according to role.

6. Visuals Colors and Theme

Authoritative creative direction: Systematic product craft with a hot accent, muse Rasmus Andersson.

• Mode: dark.
• Colors by role: background #141517; surface #1D1F22; text #F6F3EE; primary #FF5C1A (tangerine — primary actions and the cash pull mark); accent #C6F24E (acid green — gains and confirmations only); muted #8A8F98; hairline borders #2A2D31.
• Typography: headings Space Grotesk, tight tracking, medium weight, sentence case; body Inter Tight; numerals JetBrains Mono with tabular figures for supply and balances. Modular scale 1.25: 44/32/24/18/15, with clamp(44px, 7vw, 104px) for the hero line.
• Shape language: 4/8-pt spacing scale; 10px control radii; hairline 1px borders in #2A2D31; no shadows.
• Layout: compact left-aligned grid with a wide data column; rules separate rows; numerals align right in tabular columns.
• Imagery: the interface is the image — ledger rows, supply counters, schematic coin diagrams, code samples.
• Avoid: blue or indigo accents on white; gradient blobs or glass panels; identical hover-lift card grids; centred SaaS hero with subtext and a blue button; rounded pill buttons with soft shadows.

7. Signature Design Concept

The public entry is a graphite full-width field holding an oversized cash pull wordmark in Space Grotesk with tight tracking at clamp(44px, 7vw, 104px). Directly beneath it sits a live supply counter in JetBrains Mono with tabular figures, separated from the wordmark by a thin tangerine rule. The Sign Up control is a solid tangerine block with a 10px radius and no shadow, left-aligned — never centred. A muted Login link sits beside it. The supply counter counts up once on load; under prefers-reduced-motion it renders its final value statically. All readable text and controls stay whole inside the viewport at 375px, 768px, and 1280px, wrapping or scaling to fit.

8. Interaction Model & Motion Direction

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

Landing Hero Motion Brief

• Focal subject: the oversized cash pull wordmark and the live supply counter beneath it.
• Input → transformation → outcome thesis: on load, the supply counter resolves from a placeholder rule to the current supply, counting up once; the wordmark and tangerine Sign Up block are present from the first frame. The outcome is a readable, trustworthy statement of what cash pull is and how much exists.
• Motion vocabulary: fast 120–200ms functional transitions; a single count-up on load; no decoration.
• Composed first frame: graphite field, wordmark spanning the width, tangerine rule, supply counter mid-count, solid tangerine Sign Up block left-aligned.
• Reduced-motion state: the counter renders its final value immediately; no count-up; all content and controls remain fully visible and usable.

9. Non-Functional Requirements

• NFR-1 — Durable currency state. Currency definition, supply, balances, and the transfer record persist in application-owned storage (MariaDB) so that balances and records survive sessions and revisits. (required_inference — durable_state_required)
• NFR-2 — Identity continuity. Protected cash pull state is bound to the correct participant; a session established at Sign Up or Login is required to reach Currency, Create Currency, Wallet, Send, and Receive. (required_inference)
• NFR-3 — Transfer integrity. A send either records a transfer and adjusts both balances, or records nothing; no partial transfer is observable. (required_inference)
• NFR-4 — Numeric legibility. Supply and balances use tabular figures so digits align in columns and remain readable at every viewport. (explicit — creative direction)
• NFR-5 — Readable text and controls. Headlines, wordmarks, labels, numbers, and controls stay entirely inside the viewport and their container at 375px, 768px, and 1280px. (explicit — creative direction)
• NFR-6 — Reduced motion. With prefers-reduced-motion, the count-up is suppressed and a usable static arrangement is provided. (explicit — creative direction)

10. Tech Stack

• Frontend: React application UI.
• Backend: shared FastAPI process for application APIs and domain modules (currency, supply, balances, transfers, identity).
• Database: MariaDB for application-owned persistent data.
• Infrastructure: docker-compose with the frontend, backend, and database services; the backend is reused for all feature APIs rather than adding separate services.

11. Assumptions and Constraints

• Constraint: the currency name is cash pull. (explicit)
• Constraint: cash pull is in the style of Bitcoin — a digital currency with a supply and peer-to-peer transfers between holders. (explicit)
• Assumption: the Currency Creator is the first user to start cash pull; holders depend on that act. (required_inference)
• Assumption: a holder is identified for receiving by an application-issued receiving identifier shown on Receive. (required_inference)
• Assumption: identity is application-owned and self-service; no invitation or provisioning flow is required. (required_inference)
• Out of scope: trading, exchange, mining, staking, fiat on/off-ramp, and market pricing are not part of the current product.

12. Glossary

• cash pull — the digital currency this product launches and uses; its name is fixed.
• Currency Creator — the user who starts cash pull and follows its supply.
• Currency Holder — a user who holds, sends, and receives cash pull.
• Supply — the total amount of cash pull that exists, shown on Currency.
• Balance — a holder's own cash pull amount, shown on Wallet.
• Transfer — a movement of cash pull from one holder to another, recorded in the transfer record.
• Receiving identifier — the application-issued identifier a holder shares so others can send them cash pull.