System Requirements Document for nigeria-life-style

1. Introduction

Nigeria Life Style is a browser-based, multiplayer, Sims-style life simulation game set in a Nigerian megacity. It replicates the functions and mechanics of the reference game Lagos Life: players are dealt a birth-lottery origin (Nepo or Lapo), manage a set of decaying character needs, take up one of 33 careers, pay weekly rent while climbing a housing ladder from Mushin flats up to Lekki villas, and live alongside other players inside one shared, live city that includes governor elections and policy effects, daily hunts, chat, families, and squads.

The product intent is to deliver that same life-simulation experience under the name Nigeria Life Style, playable in any modern browser with no download, and hosted outside the current environment on external hosting.

Audience: young Nigerian and diaspora players who want hustle, humour, and street-corner energy — a loud, fast, proud, slightly chaotic city life they are randomly dealt and must hustle through. The audience is not a premium-calm or corporate-neutral one.

2. System Overview

Nigeria Life Style is a single shared-world web game. A Player enrolls with a self-service account, starts a new life, and receives a birth-lottery origin that sets starting resources and conditions. From there the Player manages six decaying needs (Hunger, Energy, Hygiene, Bladder, Fun, Social), selects one of 33 careers with differing pay scales, shifts, and promotions, and pays weekly rent while progressing through housing tiers from Mushin flats up to Lekki villas. All players inhabit one live city where they see each other and participate in shared events: governor elections and policy effects, daily hunts, chat, families, and squads.

Current actors:

• Player (human, active) — the sole accepted human persona.
• Game server / simulation engine (system) — decays needs, advances shifts and promotions, accrues and collects rent, runs the shared city simulation and events.
• Other players in the shared city (peer participants) — co-inhabitants of the live city whose presence, chat, elections, hunts, families, and squads the Player interacts with.

Delivery and ownership: the game is a first-party browser application with an application-owned backend that holds durable character and shared-city state. Identity is application-owned (self-service enrollment and returning verification) because a Player must privately own and resume durable character, needs, career, housing, and shared-city state. The application is deployed to external hosting outside the current environment.

Narrow exclusions: no native mobile app or download is required (browser-only); no third-party account provider is specified; no adjacent account-management capabilities (password reset flows, profile editing, billing) are in scope beyond what enrollment and returning verification require.

2a. Product Interpretation and Delivery Boundary

Nigeria Life Style is delivered as a hosted web game, not a downloadable client. A visitor first meets an anonymous Landing page that states the premise — the birth lottery, needs, 33 careers, the rent ladder, and the shared live city — and offers to start a life or log in. Starting a life requires a self-service account (Sign Up); returning players verify identity (Login) to resume their durable life and shared-city state. Once inside, the Player works across four recurring surfaces — New Life (birth-lottery start), Needs, Careers, Housing, and City — all protected behind login.

Everything described in this document is current scope. The game must be hosted outside the current environment; external hosting/deployment is a current delivery obligation, not a future idea. No future-horizon features are accepted in this thread.

2b. Source Content Inventory

The reference directives declare feature_reference and domain_context uses only (no content_source), so no content inventory is reproduced. The verified mechanics carried into this document are: browser-based play with no download; shared multiplayer live world; needs system (Hunger, Energy, Hygiene, Bladder, Fun, Social); birth lottery origins (Nepo Baby, LAPO Baby) determining starting resources and conditions; housing and weekly rent (e.g., every Saturday) across multiple tiers with different costs and permanence; dozens of careers (noted as 33) with different pay scales, shifts, and promotions; and shared city mechanics including governor elections and policy effects, daily hunts, chat, families, and squads. The second reference URL was unavailable and contributed no verified facts.

2c. Page Content and Component Coverage

Landing

• Information/state: anonymous public entry. Full-viewport poster composition: the wordmark NIGERIA / LIFE / STYLE stacked in Anton, the third line inside a red block bleeding off the right edge; a single bone-coloured premise sentence; a red START A LIFE button and a yellow-outlined LOG IN button; a vertical yellow rule at the ninth column; a duotone-cut Lagos street photograph in the lower-right quadrant behind (never under) type.
• Primary actions: START A LIFE → Sign Up; LOG IN → Login.
• Supporting actions: none beyond navigation to the two access surfaces.
• Domain entities: none persisted; presents the birth-lottery premise, needs, 33 careers, housing ladder, and shared live city as copy.
• Component responsibilities: hero type stack, premise line, primary/secondary CTA pair, decorative rule and photograph.
• States: loading (static poster, no data fetch); empty/success/error not applicable; recovery = CTAs always available.

Sign Up

• Information/state: cream inverted surface form for self-service enrollment (credentials to establish an application-owned identity).
• Primary actions: submit enrollment → creates account and routes to New Life.
• Supporting actions: link to Login for existing players.
• Domain entities: Player account.
• Component responsibilities: form fields, validation messaging, submit control.
• States: loading (submitting); empty (blank form); success (account created → New Life); error (invalid/duplicate credentials, shown inline); recovery (correct and resubmit).

Login

• Information/state: cream inverted surface form for returning verification.
• Primary actions: submit credentials → resumes durable life and shared-city state.
• Supporting actions: link to Sign Up.
• Domain entities: Player account/session.
• Component responsibilities: credential fields, validation messaging, submit control.
• States: loading; empty; success (→ resumed game surface); error (invalid credentials, inline); recovery (retry).

New Life

• Information/state: protected. Focused owner for starting a life and receiving the birth-lottery outcome. Shows the birth-lottery reveal as a poster event: full-bleed colour wipe (yellow, then red) landing a stamped NEPO or LAPO card with the starting naira amount in Anton at 64px.
• Primary actions: start a new life → birth lottery assigns Nepo or Lapo origin and starting resources/conditions.
• Supporting actions: proceed into the game after the reveal.
• Domain entities: Character, Origin (Nepo/Lapo), starting naira balance.
• Component responsibilities: start control, colour-wipe reveal, stamped origin card, starting-amount display.
• States: loading (rolling the lottery); empty (no life yet — prompt to start); success (origin stamped, starting amount shown); error (start failed — retry); recovery (re-roll/retry start). Reduced motion: instant swap to the stamped card.

Needs

• Information/state: protected. Recurring owner for viewing and managing the character's needs. Six needs — Hunger, Energy, Hygiene, Bladder, Fun, Social — each as five hard segmented blocks (red critical, yellow low, bone healthy) with the numeric value in Archivo 600 uppercase beside it. Persistent top bar shows wordmark, naira balance, and needs pips.
• Primary actions: take actions that restore a need.
• Supporting actions: read current values and criticality.
• Domain entities: Character needs (six values), naira balance.
• Component responsibilities: segmented meters, numeric readouts, restore controls, top bar.
• States: loading (fetching needs); empty (no active life — route to New Life); success (values shown, decay reflected); error (fetch/action failed — retry); recovery (retry action).

Careers

• Information/state: protected. Owner for browsing the 33 careers and selecting one. Dense typographic poster index: all 33 careers as a three-column run of caps names with pay scale and shift, red background flip on hover/focus, keyboard-selectable.
• Primary actions: select a career for the character.
• Supporting actions: browse/filter the 33; keyboard navigation.
• Domain entities: Career (name, pay scale, shift, promotion path), Character employment.
• Component responsibilities: career index rows, pay/shift labels, selection control, keyboard focus handling.
• States: loading (fetching careers); empty (no active life — route to New Life); success (index shown, current career marked); error (fetch/select failed — retry); recovery (retry selection).

Housing

• Information/state: protected. Owner for paying weekly rent and progressing from Mushin flats up to Lekki villas. Vertical rent ladder: Mushin flat at the bottom in red, Lekki villa at the top in yellow, current rung stamped; weekly rent due (e.g., every Saturday) with tier costs and permanence.
• Primary actions: pay weekly rent; progress to the next housing tier.
• Supporting actions: view current tier, rent due date, and tier costs.
• Domain entities: Housing tier, rent obligation (amount, due date), naira balance.
• Component responsibilities: rent ladder, current-rung stamp, rent-due display, pay control.
• States: loading (fetching housing/rent); empty (no active life — route to New Life); success (rung stamped, rent status shown); error (payment failed — retry); recovery (retry payment).

City

• Information/state: protected. Owner for seeing and interacting within the shared live city alongside other players. Running city ticker across the top (chat, elections, daily hunts) as a thin marquee band; teal used only as the third category colour on the City board; shared events including governor elections and policy effects, daily hunts, chat, families, and squads.
• Primary actions: participate in shared city activity (chat, elections, hunts, families, squads).
• Supporting actions: read the ticker and shared events.
• Domain entities: City, players present, chat messages, elections/policies, hunts, families, squads.
• Component responsibilities: ticker band, city board, event/chat panels, participation controls.
• States: loading (fetching city state); empty (no active life — route to New Life); success (live city shown, ticker running); error (fetch/action failed — retry); recovery (retry). Reduced motion: ticker becomes a static wrapped list.

3. Functional Requirements

FR-1 — Browser-based play, no download (explicit) As a Player I should play Nigeria Life Style in any modern browser with no download required, so that I can start immediately.

• Trigger: opening the game URL in a modern browser. Observable result: the game loads and is playable in-browser. Access: Landing is anonymous; game surfaces require login. Failure/recovery: if the page fails to load, reload. Continuation: proceed to start or resume a life.

FR-2 — Self-service account enrollment (required_inference) As a Player I should create my own account before starting a new life, so that my character and shared-city state are durably mine.

• Trigger: choosing START A LIFE on Landing. Input: enrollment credentials. Observable result: an application-owned account is created and the Player is routed to New Life. Access: Sign Up is anonymous. Failure/recovery: invalid or duplicate credentials show inline errors; correct and resubmit. Continuation: start a new life.

FR-3 — Returning identity verification (required_inference) As a returning Player I should log in to resume my durable character and shared-city state, so that my life continues where I left it.

• Trigger: choosing LOG IN on Landing. Input: credentials. Observable result: session established; the Player's life and city state are resumed. Access: Login is anonymous. Failure/recovery: invalid credentials show inline errors; retry. Continuation: resume play.

FR-4 — Start a new life with birth lottery (explicit) As a Player I should start a new life and receive a birth-lottery origin of either Nepo or Lapo, so that my starting resources and conditions are dealt to me.

• Trigger: starting a life on New Life. Observable result: the lottery assigns Nepo or Lapo and sets starting resources/conditions, revealed as a stamped card with the starting naira amount. Access: login required. Failure/recovery: if the start fails, retry. Continuation: proceed into the game.

FR-5 — Manage character needs (explicit) As a Player I should view and manage my character's decaying needs — Hunger, Energy, Hygiene, Bladder, Fun, and Social — so that I keep my character functioning.

• Trigger: needs decay over time; Player opens Needs. Observable result: each need shows a segmented meter and numeric value; Player actions restore needs. Access: login required. Failure/recovery: failed fetch/action shows error and can be retried. Continuation: continue managing needs.

FR-6 — Take one of 33 careers (explicit) As a Player I should browse the 33 careers and select one for my character, so that I earn income with a chosen pay scale and shift.

• Trigger: opening Careers. Observable result: the 33-career index is shown with pay scale and shift; selecting a career assigns it to the character. Access: login required. Failure/recovery: failed fetch/selection shows error and can be retried. Continuation: work shifts and pursue promotions.

FR-7 — Pay weekly rent and climb the housing ladder (explicit) As a Player I should pay weekly rent and progress from Mushin flats up to Lekki villas, so that I advance my housing status.

• Trigger: weekly rent due (e.g., every Saturday); Player opens Housing. Observable result: current rung is stamped on the ladder; paying rent satisfies the obligation and enables progression to the next tier. Access: login required. Failure/recovery: failed payment shows error and can be retried. Continuation: continue climbing tiers.

FR-8 — Share one live city with other players (explicit) As a Player I should see and interact with other players in one shared live city, so that I participate in shared events.

• Trigger: opening City. Observable result: the live city board and running ticker show other players and shared events. Access: login required. Failure/recovery: failed fetch/action shows error and can be retried. Continuation: keep participating.

FR-9 — Shared city mechanics: elections, policies, hunts, chat, families, squads (explicit) As a Player I should take part in governor elections and policy effects, daily hunts, chat, families, and squads within the shared city, so that I engage with the world alongside others.

• Trigger: participating in a city activity on City. Observable result: the Player's participation is reflected in shared city state and visible to other players. Access: login required. Failure/recovery: failed action shows error and can be retried. Continuation: continue participating.

FR-10 — External hosting (explicit) As the product owner I should have the game hosted outside the current environment, so that players reach it on external hosting.

• Trigger: deployment. Observable result: the game is served from external hosting. Failure/recovery: redeploy on failure. Continuation: players access the hosted game.

4. User Personas

Player

The Player is the sole active human persona. Their product context is a shared, live Nigerian megacity they enter through a birth lottery: they are dealt either a Nepo or Lapo origin, which sets their starting resources and conditions, and from there they hustle.

• Primary goal: build a life and advance housing status within the shared world — from Mushin flats up to Lekki villas.
• Distinct accepted responsibilities: start a life and receive the birth-lottery outcome; manage six decaying needs; choose among 33 careers with differing pay scales, shifts, and promotions; pay weekly rent and climb the housing ladder; share and interact within one live city including elections, policies, daily hunts, chat, families, and squads.
• Relevant inputs/decisions: which career to take; when and how to restore needs; when to pay rent and push to the next tier; how to engage in city events.
• Interactions with other participants: co-inhabits the live city with other players, participating in shared events and chat; the game server decays needs, advances shifts/promotions, and accrues rent.
• Observable success: a durable character with a stamped origin, managed needs, an active career, rent paid and housing advanced, and visible participation in the shared city.

What makes the Player's work distinct is that it is a life under random dealing and ongoing decay — every decision is about hustling a dealt hand forward inside a world shared with others, not a single transactional task.

5. Core User Flows

Flow A — First-time Player starts a life

1. Player opens the game URL in a modern browser and lands on Landing (anonymous), seeing the NIGERIA / LIFE / STYLE poster and the premise.
2. Player chooses START A LIFE → Sign Up.
3. Player submits enrollment credentials; on success an account is created and they are routed to New Life. (On invalid/duplicate credentials, inline errors appear; Player corrects and resubmits.)
4. On New Life, Player starts a life; the birth-lottery colour wipe runs and lands a stamped NEPO or LAPO card with the starting naira amount.
5. Player proceeds into the game with their dealt origin and starting resources.

Flow B — Returning Player resumes

1. Player opens the game and chooses LOG IN on Landing → Login.
2. Player submits credentials; on success their durable character and shared-city state resume. (On invalid credentials, inline error; retry.)
3. Player continues on their current game surface.

Flow C — Managing needs

1. On Needs, Player sees six segmented meters (Hunger, Energy, Hygiene, Bladder, Fun, Social) with numeric values; decay is reflected.
2. Player takes an action to restore a need; the meter and value update. (On failure, error shown; retry.)
3. Player continues managing needs.

Flow D — Choosing a career

1. On Careers, Player browses the 33-career poster index with pay scale and shift (keyboard-selectable).
2. Player selects a career; it is assigned to the character and marked as current. (On failure, error; retry.)
3. Player works shifts and pursues promotions.

Flow E — Paying rent and climbing housing

1. On Housing, Player sees the vertical rent ladder with the current rung stamped and the weekly rent due (e.g., every Saturday).
2. Player pays the weekly rent; the obligation is satisfied. (On failure, error; retry.)
3. Player progresses to the next tier, climbing from Mushin flats toward Lekki villas.

Flow F — Living in the shared city

1. On City, Player sees the live city board and the running ticker of chat, elections, and daily hunts.
2. Player participates in shared activity — chat, governor elections and policy effects, daily hunts, families, squads — and their participation is reflected to other players. (On failure, error; retry.)
3. Player continues participating in the shared world.

6. Visuals Colors and Theme

Muse: Paula Scher — typography as architecture, Lagos loudness as a life sim. The register is loud, fast, proud, and a little chaotic; not premium-calm, not corporate-neutral.

Headline: "NIGERIA LIFE STYLE" — a city that shouts in type at architectural scale.

Palette (dark mode):

• Background #111111 (poster wall, ~55%)
• Surface #F2EDE3 (cream inverted surface for forms and needs panel, ~20%)
• Text #F7F2E8 (bone, full contrast on black)
• Primary #E63A26 (signal red — rent due, critical needs, CTA, ~15%)
• Accent #F5C518 (yellow — birth-lottery reveal, career chips, ~7%)
• Muted #8C887F (never for readable text under 18px)
• Teal #1F7A6B (only as third category colour on the City board, ~3%)

Typography:

• Headings: Anton, uppercase, tracking −0.01em, leading 0.86; landing statement clamp(56px, 12vw, 176px), page titles clamp(40px, 6vw, 96px), section heads clamp(28px, 4vw, 48px); occasional single word rotated 90° or outlined.
• Body: Archivo 400/500, 17–19px, leading 1.55, sentence case for careful reading.
• Scale: 176/96/64/48/32/24/19/17/14 (1.5 modular display, 1.25 UI).
• Labels: Archivo 600 uppercase 12px, 0.14em tracking.
• Naira amounts: Anton 32–64px so money reads as a headline.

Shape language: hard edges, zero radius on type blocks and colour fields; sharp rectangles, full-bleed bands, 4°-skewed divider strips, 3px rules, colour blocks butted with no gap. Buttons are solid rectangles with a 2px offset hard shadow (no blur) that shifts 4px on press. Needs meters are five hard segmented blocks, never a smooth gradient.

Layout: 12-column poster grid, content often spanning 9 columns with an intentional 3-column gutter. In-game surfaces use a persistent top bar (wordmark left, naira balance and needs pips right) and a left rail of stacked-caps section tabs. Each of Needs, Careers, Housing, City opens with an oversized page title bleeding to the viewport edge and a coloured category band beneath. Careers is a dense three-column poster index; Housing is a vertical rent ladder (Mushin red at bottom, Lekki yellow at top, current rung stamped). At 375px every multi-column block collapses to one column, display type drops to its clamp minimum, and no headline, label, number, or control is clipped.

Imagery: typography is the imagery — giant stacked words, numbers as ornament, colour blocks as scenes. Photography, where used, is high-contrast duotone-cut (black plus one spot colour) Lagos street photography (danfo buses, market awnings, compound gates), cropped hard to the grid, always behind or beside type, never over it. No 3D, no illustration of people, no gradient blobs.

7. Signature Design Concept

The public entry is a full-viewport black poster: the words NIGERIA / LIFE / STYLE set in Anton at clamp(56px, 12vw, 176px), stacked on three lines, flush left, filling roughly 80% of the viewport width on desktop and the full width at 375px. The third line, STYLE, sits inside a solid red block that bleeds off the right edge. Beneath the stack, a single bone-coloured line states the premise in one sentence, with a red rectangular START A LIFE button pinned directly under it at the left margin and a smaller yellow-outlined LOG IN beside it. A vertical yellow rule runs the full height at the ninth column, and a duotone-cut Lagos street photograph fills the lower-right quadrant behind the type but never under it. No centred layout, no sub-headline paragraph, no gradient. The composition recomposes only accepted content — the wordmark, the premise, and the two access CTAs.

8. Interaction Model & Motion Direction

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

Landing Hero Motion Brief

• Focal subject: the stacked NIGERIA / LIFE / STYLE wordmark with STYLE in the bleeding red block, plus the duotone Lagos street photograph in the lower-right quadrant.
• Thesis: on load, the three type lines stagger in from the left in 60ms steps (input → transformation → outcome), locking together like wood type; the premise line and CTA pair settle beneath; the photograph holds behind the type. The outcome is a composed poster, not a moving scene.
• Motion vocabulary: poster-mechanical — left-stagger type blocks, instant 120ms colour flips on hover/focus, hard offset-shadow press shift; no easing theatrics.
• Composed first frame: black ground, wordmark stacked flush left with STYLE in the red block bleeding right, yellow vertical rule at column nine, duotone photograph lower-right, premise line and red START A LIFE / yellow-outlined LOG IN beneath.
• Reduced-motion state: all staggering and wiping removed; the poster appears fully composed instantly; every state change is an instant colour swap.

Across in-game surfaces: the birth-lottery reveal runs a full-bleed colour wipe (yellow, then red) before the NEPO/LAPO stamp lands (instant swap under reduced motion); the City ticker is a thin marquee band that becomes a static wrapped list under reduced motion; career rows flip to red on hover/focus in 120ms.

9. Non-Functional Requirements

• NFR-1 — External hosting (explicit): the game must be deployed to external hosting outside the current environment. Rationale: explicit user constraint.
• NFR-2 — Browser-only delivery (explicit): playable in any modern browser with no download. Rationale: replicated reference mechanic.
• NFR-3 — Durable state (required_inference): character, needs, career, housing, and shared-city state must persist across sessions so a returning Player resumes their life. Rationale: indispensable for the accepted resume journey.
• NFR-4 — Shared live world (explicit): one shared city where players see each other and participate in shared events. Rationale: replicated reference mechanic.
• NFR-5 — Readability at all viewports (explicit design constraint): headlines, wordmarks, labels, numbers, and controls stay entirely inside the viewport and their container at 375px, 768px, and 1280px; imagery/decoration may bleed but never cover readable text or controls. Rationale: explicit design constraint.
• NFR-6 — Reduced motion (explicit design constraint): under prefers-reduced-motion, staggering and wiping are removed, the ticker becomes a static wrapped list, and state changes are instant colour swaps. Rationale: explicit design constraint.

10. Tech Stack

• Frontend: React (browser web app), styled to the poster design system (Anton/Archivo, hard-edged colour blocks).
• Backend: Python/FastAPI serving game APIs (character, needs, careers, housing/rent, city, chat, elections, hunts, families, squads) and the shared-city simulation.
• Storage: durable persistent storage for accounts, characters, and shared-city state.
• Real-time: a shared live-city channel (e.g., WebSocket) for presence, chat, and events.
• Deployment: Docker/docker-compose for local packaging; deployed to external hosting outside the current environment (NFR-1).

11. Assumptions and Constraints

• Hard constraints: the game is named Nigeria Life Style; it replicates all the same functions as Lagos Life; it is hosted outside the current environment.
• Assumption: application-owned identity (self-service Sign Up, returning Login) is required so a Player durably owns and resumes their life — labeled required_inference.
• Assumption: the 33 careers, six needs, weekly rent cadence (e.g., every Saturday), and housing tiers (Mushin flats → Lekki villas) follow the verified reference mechanics; exact pay scales, shift times, and tier costs are game-balance values to be defined in implementation.
• Constraint: no native app or download; browser-only.
• Constraint: the second reference URL was unavailable and contributes no verified facts.

12. Glossary

• Birth lottery: the random assignment of a starting origin (Nepo or Lapo) that sets a character's starting resources and conditions.
• Nepo / Lapo: the two birth-lottery origins.
• Needs: the six decaying character stats — Hunger, Energy, Hygiene, Bladder, Fun, Social.
• Career: one of 33 jobs with its own pay scale, shift, and promotion path.
• Housing ladder / rent ladder: the tiered housing progression from Mushin flats up to Lekki villas, with weekly rent due.
• Shared city: the single live multiplayer world where all players coexist and participate in shared events.
• Daily hunt: a recurring shared city activity.
• Squad / Family: player groupings within the shared city.
• Governor election / policy effects: shared city governance mechanics whose outcomes affect the world.