doom-scrolling-geopolitics

bysatyam dave

make me a app to avoid doom scrolling and instead learn about geopolitics

Landing
Landing

Comments (0)

No comments yet. Be the first!

System Requirements

System Requirements Document for Geopolitics

1. Introduction

Geopolitics is a web application built to help people stop doom scrolling and instead spend that time learning about geopolitics. The product replaces the reflexive, endless-feed habit with short, clear geopolitics reading sessions, and it keeps a personal record of what the learner has read so the time spent feels accounted for rather than lost.

The audience is a general learner — someone with no formal background in international affairs who wants to understand the world without being pulled into a scrolling feed. The app is deliberately calm and structured: it presents geopolitics content as discrete sessions with a beginning and an end, not as an infinite stream.

This document is the System Requirements Document for the project named Geopolitics (project identifier doom-scrolling-geopolitics).

Success Criteria

  • A new learner can move from the public entry page to a completed first geopolitics session without leaving the app.
  • A returning learner can verify identity and see the record of sessions they have finished.
  • Every learning session has a clear finish, so the learner's time is bounded rather than open-ended.
  • The interface reads as a reliable map of geopolitics, not as a feed.
Page 1 of 20

2. System Overview

Geopolitics is a React web front end backed by a shared FastAPI service and a MariaDB database. The application owns learner identity: a new learner enrolls with the app, and a returning learner verifies identity to reach saved session records. Learning content is geopolitics reading material presented one session at a time; the learner starts a session from a dashboard, reads it on a session surface, finishes it, and can review finished sessions on a progress surface.

The single active human actor is the Learner. The application itself owns identity, session records, and content delivery. There are no other human roles, no administrative surface, and no social or sharing surface.

Current delivery covers: a public landing page, self-service sign up, login, a dashboard to start sessions, a session reading surface with a finish action, and a progress surface listing finished sessions.

Removed from scope

  • Doom scrolling / infinite feed (also: doom-scroll, endless scroll, feed)
  • Social features, comments, sharing, and follower mechanics
  • Administrative or moderator surfaces
  • Notifications and push alerts
Page 2 of 20

2a. Product Interpretation and Delivery Boundary

The product's whole purpose is a deliberate alternative to doom scrolling. That intent shapes the delivery boundary: the app must present geopolitics learning as bounded sessions with a visible finish, and it must not reproduce the mechanics of an infinite feed. There is no endless stream, no autoplay of the next item, and no algorithmic "more" loop.

Access is application-owned. The Landing page is public and anonymous. Sign Up and Login are public identity-access surfaces. Dashboard, Session, and Progress require a verified learner identity, because each depends on durable, learner-specific session records that must remain bound to the correct person across visits.

All current work is first-party and delivered by the application. There are no provider-owned or external destinations in the current scope. Future ideas are kept out of current pages and acceptance (see Section 11).

2c. Page Content and Component Coverage

Page 3 of 20

Landing

  • Information/state: Product name "Geopolitics"; hero headline "Trade the scroll for the world"; subline "Read short, clear geopolitics sessions and keep a record of what you learn."; a colour-coded legend strip mapping red, yellow, and green to topic groups; a flat red schematic world-map diagram.
  • Primary action: "Start learning" — a solid red square button with uppercase label, leading to Sign Up.
  • Supporting actions: A link to Login for returning learners.
  • Domain entities: None persisted; static product framing only.
  • Component responsibilities: Hero poster block (headline spanning the left 8 columns, map diagram in the right 4 columns bleeding off the right edge, yellow rule under the headline); legend strip; primary CTA; secondary login link.
  • States: Static success state only. No loading, empty, or error states — the page has no data dependency. If the learner is already verified, the CTA may route to Dashboard instead of Sign Up.
Page 4 of 20

Sign Up

  • Information/state: Enrollment form for a new learner; explanation that an account keeps session records.
  • Primary action: Submit enrollment to create the learner's account.
  • Supporting actions: Link to Login for learners who already have an account; link back to Landing.
  • Domain entities: Learner account (identity, credential).
  • Component responsibilities: Form fields for identity and credential; submit control; inline validation messaging; link to Login.
  • States:
    • Loading: submit control shows a pending state while the account is created.
    • Empty: blank form on first arrival.
    • Success: account created; learner proceeds to Dashboard.
    • Error: invalid or incomplete input shows inline field errors; an already-registered identity shows a message directing the learner to Login.
    • Recovery: the learner corrects the field and resubmits without losing other entered values.
Page 5 of 20

Login

  • Information/state: Verification form for a returning learner.
  • Primary action: Submit credentials to verify identity.
  • Supporting actions: Link to Sign Up for learners without an account; link back to Landing.
  • Domain entities: Learner account (identity, credential).
  • Component responsibilities: Form fields for identity and credential; submit control; inline error messaging; link to Sign Up.
  • States:
    • Loading: submit control shows a pending state during verification.
    • Empty: blank form on first arrival.
    • Success: identity verified; learner proceeds to Dashboard.
    • Error: incorrect credentials show a clear, non-revealing error and keep the form usable.
    • Recovery: the learner retries; repeated failure leaves the form available and does not lock the learner out of retrying.
Page 6 of 20

Dashboard

  • Information/state: The learner's starting point for a geopolitics session; a start-session control; a summary of how many sessions the learner has finished.
  • Primary action: Start a geopolitics session — a solid red square control with uppercase label — leading to Session.
  • Supporting actions: Navigate to Progress to review finished sessions.
  • Domain entities: Learner; learning session (started/finished state); geopolitics content item.
  • Component responsibilities: Start-session control; finished-session count summary; navigation to Progress.
  • States:
    • Loading: placeholder while the learner's session summary is fetched.
    • Empty: a learner with no finished sessions sees a zero count and an invitation to start the first session.
    • Success: summary shows the finished-session count and the start control is available.
    • Error: if the summary cannot load, the start control remains usable and the summary shows a retry affordance.
    • Recovery: retry reloads the summary without losing the learner's place.
Page 7 of 20

Session

  • Information/state: The geopolitics reading content for the current session, with a visible indication that this is a bounded session.
  • Primary action: Finish the session, recording it as completed.
  • Supporting actions: Read through the content; return to Dashboard without finishing.
  • Domain entities: Learning session; geopolitics content item; completion record.
  • Component responsibilities: Content reading area; finish control; exit control.
  • States:
    • Loading: content placeholder while the session content is fetched.
    • Empty: if no content is available for a session, a clear message with a return to Dashboard.
    • Success: content is readable and the finish control records completion, then offers Progress or Dashboard as the next step.
    • Error: if content fails to load, an error message with retry and a return to Dashboard.
    • Recovery: retry reloads the same session; exiting without finishing does not record a completion.
Page 8 of 20

Progress

  • Information/state: The learner's record of finished sessions, listed with enough detail to recognize each one.
  • Primary action: Return to learning via Dashboard.
  • Supporting actions: Review the list of finished sessions.
  • Domain entities: Learning session; completion record; geopolitics content item.
  • Component responsibilities: Finished-session list; empty-state message; navigation back to Dashboard.
  • States:
    • Loading: placeholder while the record is fetched.
    • Empty: a learner with no finished sessions sees a clear message and a control to start a session on Dashboard.
    • Success: finished sessions are listed.
    • Error: a load failure shows a message with retry.
    • Recovery: retry reloads the record.
Page 9 of 20

3. Functional Requirements

FR-1 — Avoid doom scrolling (explicit) As a Learner, I should be able to spend my time in the app on bounded geopolitics sessions rather than an endless feed, so that I stop doom scrolling.

  • Trigger: the learner opens the app.
  • Observable result: the app presents discrete sessions with a visible finish, and offers no infinite stream or autoplay of further items.
  • Access: Landing is public; Dashboard, Session, and Progress require a verified learner.
  • Failure/recovery: if content cannot load, the learner is returned to Dashboard rather than left in an open-ended state.
  • Continuation: after finishing, the learner chooses Progress or Dashboard.

FR-2 — Learn geopolitics instead of scrolling (explicit) As a Learner, I should be able to read clear geopolitics content in a session and finish it with new knowledge, so that the time I would have spent scrolling becomes learning.

  • Trigger: the learner starts a session from Dashboard.
  • Input: the learner's start action.
  • Observable result: geopolitics content is displayed on Session; finishing records the session as completed.
  • Access: requires a verified learner.
  • Failure/recovery: a content load failure shows an error with retry and a return to Dashboard; exiting without finishing records no completion.
  • Continuation: the learner returns to Dashboard or reviews Progress.
Page 10 of 20

FR-3 — Self-service enrollment (required_inference) As a new Learner, I should be able to create an account with the app myself, so that my session records are kept and bound to me.

  • Trigger: the learner selects "Start learning" on Landing.
  • Input: identity and credential entered on Sign Up.
  • Observable result: an account is created and the learner reaches Dashboard.
  • Access: Sign Up is public and anonymous.
  • Failure/recovery: invalid input shows inline errors; an already-registered identity directs the learner to Login; entered values are preserved for correction.
  • Continuation: the learner starts a first session from Dashboard.

FR-4 — Returning verification (required_inference) As a returning Learner, I should be able to verify my identity, so that I can reach my saved session records.

  • Trigger: the learner selects Login from Landing or Sign Up.
  • Input: identity and credential entered on Login.
  • Observable result: identity is verified and the learner reaches Dashboard with their saved records available.
  • Access: Login is public and anonymous.
  • Failure/recovery: incorrect credentials show a clear, non-revealing error and the form remains usable for retry.
  • Continuation: the learner reviews Progress or starts a new session.
Page 11 of 20

FR-5 — Start a session (required_inference) As a Learner, I should be able to start a geopolitics session from Dashboard, so that I have a defined piece of learning to do.

  • Trigger: the learner activates the start-session control.
  • Observable result: Session opens with geopolitics content for that session.
  • Access: requires a verified learner.
  • Failure/recovery: if the session cannot be started, the control remains available and an error is shown.
  • Continuation: the learner reads the content.

FR-6 — Finish a session (required_inference) As a Learner, I should be able to finish a session, so that it is recorded as completed and my time is accounted for.

  • Trigger: the learner activates the finish control on Session.
  • Observable result: the session is recorded as completed for that learner and the learner is offered Progress or Dashboard.
  • Access: requires a verified learner.
  • Failure/recovery: if recording fails, the learner sees an error and can retry finishing; the content remains readable.
  • Continuation: the learner reviews Progress or starts another session.

FR-7 — Review finished sessions (required_inference) As a Learner, I should be able to review the sessions I have finished, so that I can see what I have learned and return to learning.

  • Trigger: the learner navigates to Progress.
  • Observable result: finished sessions are listed for that learner; an empty record shows a clear message and a route back to Dashboard.
  • Access: requires a verified learner.
  • Failure/recovery: a load failure shows a message with retry.
  • Continuation: the learner returns to Dashboard to start another session.
Page 12 of 20

4. User Personas

Learner

  • Product context: A general reader who wants to understand geopolitics but finds themselves doom scrolling instead. They are not a specialist; they want clear, digestible material and a sense that their time produced something.
  • Primary goal: Replace scrolling time with bounded geopolitics learning and keep a record of what they have read.
  • Distinct accepted responsibilities: Enrolls with the app (Sign Up); verifies identity on return (Login); starts a session (Dashboard); reads and finishes a session (Session); reviews finished sessions (Progress).
  • Relevant inputs or decisions: Whether to start a session now; when a session is finished; whether to review progress or start another session.
  • Interactions with other accepted participants: None — the Learner is the only active human actor; the application owns identity, content, and records.
  • Observable success: A completed session appears in Progress, and the learner can see a growing record of finished geopolitics sessions.
  • Constraints: The learner's records are private to them and require verified identity to reach.

5. Core User Flows

Page 13 of 20

Flow A — New learner enrolls and completes a first session

  1. The Learner arrives anonymously at Landing and reads the headline "Trade the scroll for the world" and the subline explaining short geopolitics sessions with a record of learning.
  2. The Learner selects Start learning and is taken to Sign Up.
  3. On Sign Up, the Learner enters identity and credential and submits. The submit control shows a pending state.
  4. On success, the account is created and the Learner arrives at Dashboard, which shows a zero finished-session count and an invitation to start.
  5. The Learner activates the red start-session control; Session opens with geopolitics content.
  6. The Learner reads the content and activates the finish control. The session is recorded as completed.
  7. The Learner is offered Progress or Dashboard; choosing Progress shows the first finished session in the record.
  8. Failure/recovery: if enrollment input is invalid, inline errors appear and entered values are preserved for correction; if the identity is already registered, the Learner is directed to Login. If session content fails to load, an error with retry and a return to Dashboard is shown.
Page 14 of 20

Flow B — Returning learner verifies and reviews progress

  1. The returning Learner arrives at Landing and selects the Login link.
  2. On Login, the Learner enters identity and credential and submits; the control shows a pending state.
  3. On success, the Learner arrives at Dashboard with their saved records available.
  4. The Learner navigates to Progress and reviews the list of finished sessions.
  5. The Learner returns to Dashboard to start another session, continuing at Flow A step 5.
  6. Failure/recovery: incorrect credentials show a clear, non-revealing error and the form stays usable for retry. If Progress fails to load, a message with retry is shown.

Flow C — Learner exits a session without finishing

  1. From Session, the Learner chooses to return to Dashboard without activating finish.
  2. No completion is recorded; the session does not appear in Progress.
  3. The Learner may start a session again from Dashboard.
Page 15 of 20

6. Visuals Colors and Theme

Authoritative creative direction: Systematic clarity after Massimo Vignelli. The app must feel like a reliable map, not a feed.

Colour tokens (light mode)

RoleHex
Background#F4F1EA
Surface#FFFFFF
Text#111111
Primary#D7261E
Accent#F2B705
Muted#6E6A62
Region/topic green#1F7A4D

Colour is sparse and coded, not decorative: signal red marks the primary action; yellow and green code regions and topics.

Typography

  • Headings: Archivo, Heavy 800, flush left, tight tracking, sentence case for headlines, uppercase for labels.
  • Body: Archivo.
  • Scale: 1.333 modular with a 1.5 display jump — 96 / 64 / 40 / 28 / 18 / 16 px. Mobile display 40px; desktop display 96px. Use clamp() so headlines stay whole at 375px, 768px, and 1280px.

Shape language

  • Hard edges only. 2px black rules. Square colour chips. No radii, no shadows.
Page 16 of 20

Layout

  • Visible 12-column grid with strong horizontal rules. Asymmetric poster blocks. Colour-coded topic rows align label and value in tabular columns.

Imagery

  • Flat schematic maps, region diagrams, and colour-coded pictograms. No photography.

Avoid: rounded cards and soft shadows; gradient blobs and glass panels; decorative photography; playful bounce animation; generic blue accent on white.

7. Signature Design Concept

The public entry is a full-width poster. A stacked headline in 96px black Archivo fills the left 8 columns: "Trade the scroll for the world". A flat red schematic world-map diagram sits in the right 4 columns and bleeds off the right edge. A yellow rule runs under the headline, and the CTA sits as a solid red square button with uppercase label text below the rule: "Start learning". A colour-coded legend strip under the hero maps red, yellow, and green to topic groups. Section headers sit on a full-width 2px black rule with a numbered label in the left margin. The start-session control on Dashboard is the same solid red square with uppercase label text, carrying the poster language into the working surfaces. Readable text and controls stay whole at every viewport; the map diagram carries the bleed gesture instead.

Page 17 of 20

8. Interaction Model & Motion Direction

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

Landing Hero Motion Brief

  • Focal subject: the flat red schematic world-map diagram in the right 4 columns, bleeding off the right edge.
  • Input → transformation → outcome thesis: on hover of the primary CTA, an instant colour wipe changes the button fill; on activation, the learner moves immediately to Sign Up. No easing, no flourish.
  • Motion vocabulary: one instant colour wipe on hover; instant state change. No easing flourishes.
  • Composed first frame: 96px black Archivo headline stacked across the left 8 columns, yellow rule beneath, red schematic map at right, black square CTA below the rule, legend strip beneath the hero.
  • Reduced-motion state: identical static composition; hover wipe is replaced by an instant state change with no transition.
Page 18 of 20

9. Non-Functional Requirements

  • NFR-1 — Bounded sessions (explicit): The app must not present an infinite feed or autoplay of further content; every session has a visible finish.
  • NFR-2 — Identity continuity (required_inference): Session records must remain bound to the correct learner across visits; Dashboard, Session, and Progress require verified identity.
  • NFR-3 — Anonymous entry (required_inference): Landing, Sign Up, and Login must be reachable without a verified identity.
  • NFR-4 — Readability at every viewport (explicit, from creative direction): Headlines, wordmarks, labels, numbers, cards' text, and controls stay entirely inside the viewport and their container at 375px, 768px, and 1280px, wrapping or scaling to fit; no other element covers any part of them.
  • NFR-5 — Reduced motion (explicit, from creative direction): With prefers-reduced-motion, provide a usable static arrangement; the direction is already almost still.
  • NFR-6 — Durable persistence (required_inference): Learner accounts and completion records persist in the application database.

10. Tech Stack

  • Frontend: React application UI.
  • Backend: Shared FastAPI process for application APIs and domain modules (identity, sessions, content, progress).
  • Database: MariaDB for application-owned persistent data (learner accounts, session records, content).
  • Infrastructure: docker-compose.yml with frontend, backend, and database services. No additional services are required for the current workflows.
Page 19 of 20

11. Assumptions and Constraints

  • A-1 (assumption): Geopolitics content is supplied by the application; the source does not specify an external content provider, so content is application-owned.
  • A-2 (assumption): A "session" is a single bounded reading unit with a finish action; the source does not specify length or format beyond "short, clear geopolitics sessions".
  • A-3 (constraint): The app must not reproduce doom-scrolling mechanics — no infinite feed, no autoplay, no algorithmic "more" loop.
  • A-4 (constraint): The single active human persona is the Learner; no administrative, social, or moderator roles exist in current scope.
  • A-5 (future, out of current scope): Topic browsing beyond the legend strip, spaced repetition, streaks, and sharing are not current requirements and must not appear in current pages or acceptance.

12. Glossary

  • Learner: The single active human actor; a general reader using the app to learn geopolitics instead of doom scrolling.
  • Session: A bounded geopolitics reading unit with a start and a finish.
  • Completion record: The stored fact that a given learner finished a given session.
  • Doom scrolling: The reflexive, endless-feed habit the app is designed to replace.
  • Progress: The learner's record of finished sessions.
Page 20 of 20
Live
Landing design preview

Landing: Read hero and legend

Sign Up: Enter identity and credential

Sign Up: Correct inline field errors

Sign Up: Submit enrollment

Login: Sign in with existing identity

Login: Enter returning credentials

Login: Retry after credential error

Dashboard: View zero finished count

Dashboard: 1. Start geopolitics session

Session: 2. Read session content

Session: 3. Retry content load

Session: 4. Finish session

Session: 5. Retry recording completion

Session: 6. Exit without finishing

Progress: 7. Review finished sessions

Progress: 8. Retry progress load

Progress: 9. See empty record message

Dashboard: 10. Return to learning

Live
Landing design preview

Landing: Read hero and legend

Sign Up: Enter identity and credential

Sign Up: Correct inline field errors

Sign Up: Submit enrollment

Login: Sign in with existing identity

Login: Enter returning credentials

Login: Retry after credential error

Dashboard: View zero finished count

Dashboard: 1. Start geopolitics session

Session: 2. Read session content

Session: 3. Retry content load

Session: 4. Finish session

Session: 5. Retry recording completion

Session: 6. Exit without finishing

Progress: 7. Review finished sessions

Progress: 8. Retry progress load

Progress: 9. See empty record message

Dashboard: 10. Return to learning