System Requirements Document for desa-tambi

1. Introduction

This document specifies the system requirements for desa-tambi, a website for the Survei Calon Kepala Desa Tambi Periode 2026–2034 (Village Head Candidate Survey for Desa Tambi, period 2026–2034). The product intent is to give the people of Desa Tambi a simple, trustworthy way to cast a survey vote for one of exactly three candidates — 1. Trisno, 2. Suyitno, and 3. Juri — by identifying themselves with their Nama (name) and No HP (phone number). A small committee (panitia) needs to monitor incoming votes and review the tally of each candidate's support as a basis for the 2026–2034 period.

The audience is twofold: warga Desa Tambi voting on phones and shared laptops, and the penyelenggara survei (panitia) who tally the results. The tone is neighbourly, earnest, and official — a real decision for a real village, presented with the dignity of a stamped ballot paper.

2. System Overview

desa-tambi is a custom web application with an application-owned identity layer. A voter arrives anonymously at a public Landing page, establishes identity through self-service Sign Up using their Nama and No HP, verifies again at Login, reviews the three candidates on the Candidates page, makes a single selection on the Vote page, confirms their Nama and No HP on the Voter Details page, and receives a recorded-vote confirmation. The committee (panitia) verifies at Login and reviews incoming votes and the tally on the Results page.

Current delivery is a first-party custom UI backed by a server-side application and persistent storage. The survey is bounded to exactly three candidates and a single choice per voter. Identity is captured as Nama and No HP.

2a. Product Interpretation and Delivery Boundary

The survey is delivered as a first-party website owned by the application. Anonymous visitors can read the Landing page and begin Sign Up. Protected survey work — viewing candidates, voting, submitting voter details, and committee results — requires an established identity. Voters establish identity themselves with Nama and No HP; the committee verifies through the same Login surface and reaches Results under its authorized role.

The current horizon covers only the survey described above: three fixed candidates, one choice per voter, identity by Nama and No HP, and a committee results view. No other election, candidate, or administrative capability is in scope. Future ideas are kept out of current pages and acceptance.

2b. Source Content Inventory

Not applicable — no reference directive declares content_source.

2c. Page Content and Component Coverage

Landing

• Information/state: Anonymous public entry. Explains the Survei Calon Kepala Desa Tambi Periode 2026–2034 and the three candidates (Trisno, Suyitno, Juri). Poster hero with the wordmark "DESA TAMBI", sub-line "SURVEI CALON KEPALA DESA · 2026–2034", a rotated circular ink stamp "PILIH · 1 DARI 3", a primary button "MULAI MEMILIH", and a muted all-caps line "Trisno · Suyitno · Juri".
• Primary actions: "MULAI MEMILIH" routes an anonymous visitor into Sign Up (or Login if already registered).
• Supporting actions: Navigate to Login for returning voters and committee.
• Domain entities: Survey (period 2026–2034), Candidate (Trisno, Suyitno, Juri).
• Component responsibilities: Hero poster block; ink-stamp motif; primary CTA; candidate name line; footer rule.
• States: Loading (hero badge ink-bleed reveal on load); Empty (n/a — static content); Success (CTA routes correctly); Error (route failure shows a retry affordance); Recovery (retry returns to Landing).

Sign Up

• Information/state: Anonymous self-service registration for warga using Nama and No HP.
• Primary actions: Submit Nama and No HP to establish a voter identity.
• Supporting actions: Link to Login for already-registered users.
• Domain entities: Voter identity (Nama, No HP).
• Component responsibilities: Index-card inputs for Nama and No HP with kraft label strips and hard 2px bottom rules; submit button; inline validation messages.
• States: Loading (submit in progress); Empty (blank form); Success (identity established, route to Candidates); Error (invalid or duplicate Nama/No HP shows inline message); Recovery (correct and resubmit).

Login

• Information/state: Verification surface for both Warga Pemilih (Voter) and Penyelenggara Survei (Panitia) before entering protected areas.
• Primary actions: Submit Nama and No HP to verify identity and route by role.
• Supporting actions: Link to Sign Up for new voters.
• Domain entities: Voter identity, committee role.
• Component responsibilities: Index-card inputs; submit button; role-aware routing; inline error region.
• States: Loading (verification in progress); Empty (blank form); Success (voter → Candidates; panitia → Results); Error (unrecognized Nama/No HP shows inline message); Recovery (correct and resubmit).

Candidates

• Information/state: Role-restricted (voter). Displays the three candidates as tall badge-cards: numbered circular monogram stamps (1/T, 2/S, 3/J), 4px black outlines, halftone kraft texture behind each name.
• Primary actions: Select a candidate to proceed to Vote.
• Supporting actions: Return to Landing; navigate to Vote.
• Domain entities: Candidate (Trisno, Suyitno, Juri).
• Component responsibilities: Candidate badge-card grid (three across at 1280px, stacked at 375px); selection affordance; section rule with all-caps label.
• States: Loading (cards render with ink-bleed reveal); Empty (n/a — three fixed candidates); Success (selection routes to Vote); Error (load failure shows retry); Recovery (retry reloads candidates).

Vote

• Information/state: Role-restricted (voter). Presents the three candidates as large tappable ballot-slip panels; the selected panel receives a thick orange ring.
• Primary actions: Choose exactly one of the three candidates and confirm the selection.
• Supporting actions: Change selection before confirming; return to Candidates.
• Domain entities: Candidate, Vote (single choice).
• Component responsibilities: Ballot-slip panels; selection ring; confirm control; instant state change on selection.
• States: Loading (panels render); Empty (no selection yet — confirm disabled); Success (selection confirmed, route to Voter Details); Error (submit failure shows retry); Recovery (reselect and retry).

Voter Details

• Information/state: Role-restricted (voter). Collects Nama and No HP before the vote is submitted; shows the currently selected candidate for confirmation.
• Primary actions: Enter Nama and No HP and submit the vote.
• Supporting actions: Return to Vote to change the selection.
• Domain entities: Voter identity (Nama, No HP), Vote.
• Component responsibilities: Index-card inputs (kraft label strip, hard 2px bottom rule, Oswald 600 input text); selected-candidate summary; submit button; confirmation seal "SUARA TERCATAT" on success.
• States: Loading (submission in progress); Empty (blank fields); Success (vote recorded, "SUARA TERCATAT" seal shown); Error (invalid Nama/No HP or submission failure shows inline message); Recovery (correct and resubmit).

Results

• Information/state: Role-restricted (panitia). Ruled tally board showing each candidate's row with stacked tick marks, a burnt-orange bar, and the raw count in large Oswald numerals; includes the Nama and No HP of voters who submitted.
• Primary actions: Review the tally and the list of submitted votes with voter identity.
• Supporting actions: Refresh to see newly arrived votes.
• Domain entities: Candidate, Vote, Voter identity (Nama, No HP).
• Component responsibilities: Tally rows per candidate; bar rendering; voter list with Nama and No HP; section rule with all-caps label.
• States: Loading (bars grow to final width on load); Empty (no votes yet — zeroed rows); Success (tally and voter list render); Error (load failure shows retry); Recovery (retry reloads results).

3. Functional Requirements

1. As a Warga Pemilih (Voter), I should be able to open the public Landing page and read what the Survei Calon Kepala Desa Tambi Periode 2026–2034 is about, so that I understand the survey before participating. (explicit)

   • Trigger: anonymous visit to Landing.
   • Observable result: Landing renders the survey description, the period 2026–2034, and the three candidate names.
   • Access state: anonymous.
   • Failure/recovery: load failure shows retry; retry reloads Landing.
   • Continuation: CTA "MULAI MEMILIH" routes to Sign Up.

2. As a Warga Pemilih (Voter), I should be able to register myself using my Nama and No HP, so that I can participate in the survey. (required_inference)

   • Trigger: submit Nama and No HP on Sign Up.
   • Observable result: voter identity is established and the voter is routed to Candidates.
   • Access state: anonymous entry; protected state becomes available after identity is established.
   • Failure/recovery: invalid or duplicate Nama/No HP shows an inline message; correct and resubmit.
   • Continuation: proceed to Candidates.

3. As a Warga Pemilih (Voter), I should be able to verify again with my Nama and No HP at Login, so that I can resume my survey participation. (required_inference)

   • Trigger: submit Nama and No HP on Login.
   • Observable result: identity verified; voter routed to Candidates.
   • Access state: anonymous entry to Login; protected state available after verification.
   • Failure/recovery: unrecognized Nama/No HP shows an inline message; correct and resubmit.
   • Continuation: proceed to Candidates.

4. As a Warga Pemilih (Voter), I should see the three candidates Trisno, Suyitno, and Juri on the Candidates page, so that I know who I can vote for. (explicit)

   • Trigger: navigate to Candidates after verification.
   • Observable result: three candidate badge-cards render with numbered monogram stamps (1/T, 2/S, 3/J).
   • Access state: role-restricted to voter.
   • Failure/recovery: load failure shows retry; retry reloads candidates.
   • Continuation: select a candidate to proceed to Vote.

5. As a Warga Pemilih (Voter), I should be able to choose exactly one of the three candidates on the Vote page, so that my single choice is recorded. (explicit)

   • Trigger: tap a candidate panel on Vote.
   • Observable result: the selected panel receives a thick orange ring; only one candidate can be selected at a time.
   • Access state: role-restricted to voter.
   • Failure/recovery: submit failure shows retry; reselect and retry.
   • Continuation: proceed to Voter Details to submit.

6. As a Warga Pemilih (Voter), I should be able to enter my Nama and No HP on the Voter Details page before my vote is submitted, so that my vote is tied to my identity. (explicit)

   • Trigger: enter Nama and No HP and submit on Voter Details.
   • Observable result: the vote is recorded with the voter's Nama and No HP; a "SUARA TERCATAT" confirmation seal is shown.
   • Access state: role-restricted to voter.
   • Failure/recovery: invalid Nama/No HP or submission failure shows an inline message; correct and resubmit.
   • Continuation: confirmation is displayed; voter may return to Landing.

7. As a Penyelenggara Survei (Panitia), I should be able to verify at Login with my Nama and No HP, so that I can reach the committee results area. (required_inference)

   • Trigger: submit Nama and No HP on Login.
   • Observable result: identity verified; panitia routed to Results.
   • Access state: anonymous entry to Login; protected state available after verification.
   • Failure/recovery: unrecognized Nama/No HP shows an inline message; correct and resubmit.
   • Continuation: proceed to Results.

8. As a Penyelenggara Survei (Panitia), I should be able to review the tally of votes for Trisno, Suyitno, and Juri on the Results page, so that I know each candidate's support. (required_inference)

   • Trigger: open Results after verification.
   • Observable result: a ruled tally board renders each candidate's row with tick marks, a burnt-orange bar, and the raw count.
   • Access state: role-restricted to panitia.
   • Failure/recovery: load failure shows retry; retry reloads results.
   • Continuation: refresh to see newly arrived votes.

9. As a Penyelenggara Survei (Panitia), I should be able to see the Nama and No HP of voters who submitted, so that I can monitor incoming votes with their identity. (required_inference)

   • Trigger: open Results after verification.
   • Observable result: the voter list renders each submitted vote with the voter's Nama and No HP.
   • Access state: role-restricted to panitia.
   • Failure/recovery: load failure shows retry; retry reloads the list.
   • Continuation: continue monitoring as new votes arrive.

4. User Personas

Warga Pemilih (Voter)

• Product context: A resident of Desa Tambi who wants to take part in the Survei Calon Kepala Desa Tambi Periode 2026–2034, typically on a phone or a shared laptop.
• Primary goal: Cast a single vote for one of the three candidates — Trisno, Suyitno, or Juri — and have it recorded and confirmed.
• Distinct accepted responsibilities: Register with Nama and No HP; verify again at Login; review the three candidates; select exactly one; enter Nama and No HP to submit; receive the "SUARA TERCATAT" confirmation.
• Relevant inputs or decisions: Which of the three candidates to choose; their own Nama and No HP.
• Interactions with other accepted participants: The voter's submitted vote and identity become visible to the Penyelenggara Survei (Panitia) on Results.
• Observable success: The vote is recorded and the confirmation seal is shown after Nama and No HP are submitted.

Penyelenggara Survei (Panitia)

• Product context: The party organizing the survey who needs the results of the residents' votes to know each candidate's support.
• Primary goal: See the tally of votes for Trisno, Suyitno, and Juri and review the incoming votes with voter identity.
• Distinct accepted responsibilities: Verify at Login; monitor incoming votes with Nama and No HP; review the tally per candidate.
• Relevant inputs or decisions: Their own Nama and No HP for verification; interpretation of the tally as a basis for the 2026–2034 period.
• Interactions with other accepted participants: Reviews the votes and identities submitted by Warga Pemilih (Voter).
• Observable success: The tally and voter list are available and reviewable.

5. Core User Flows

Flow A — Warga Pemilih (Voter) casts a vote

1. The voter opens the Landing page anonymously and reads the survey description for the 2026–2034 period and the three candidate names.
2. The voter presses "MULAI MEMILIH" and is routed to Sign Up.
3. On Sign Up, the voter enters their Nama and No HP and submits; their identity is established.
4. The voter is routed to Candidates and sees the three badge-cards: 1/T Trisno, 2/S Suyitno, 3/J Juri.
5. The voter selects a candidate and proceeds to Vote.
6. On Vote, the voter taps one of the three ballot-slip panels; the selected panel receives a thick orange ring. Only one candidate can be selected.
7. The voter proceeds to Voter Details, confirms the selected candidate, enters Nama and No HP, and submits.
8. The vote is recorded and the "SUARA TERCATAT" confirmation seal is shown. The voter may return to Landing.
9. Failure/recovery: If Nama or No HP is invalid or submission fails, an inline message is shown; the voter corrects the fields and resubmits. If the voter wants a different candidate, they return to Vote and reselect.

Flow B — Warga Pemilih (Voter) returns to verify again

1. The voter opens Login and enters their Nama and No HP.
2. Identity is verified and the voter is routed to Candidates.
3. Failure/recovery: If the Nama/No HP is unrecognized, an inline message is shown; the voter corrects and resubmits, or uses Sign Up if not yet registered.

Flow C — Penyelenggara Survei (Panitia) reviews results

1. The panitia opens Login and enters their Nama and No HP.
2. Identity is verified and the panitia is routed to Results.
3. On Results, the panitia reviews the ruled tally board: each candidate's row shows tick marks, a burnt-orange bar, and the raw count for Trisno, Suyitno, and Juri.
4. The panitia reviews the list of submitted votes with each voter's Nama and No HP.
5. The panitia refreshes to see newly arrived votes.
6. Failure/recovery: If Results fails to load, a retry affordance is shown; retry reloads the tally and voter list.

6. Visuals Colors and Theme

Muse: Aaron Draplin. Headline: Hand-built civic ballots — official without being cold, legible at arm's length on a cheap Android phone, carrying the dignity of a stamped document.

Palette (light mode):

• Background (kraft-paper ground): #EDE4D3
• Surface (index-card panels): #FBF7EE
• Text (ink): #1C1917
• Primary (burnt orange — stamp, primary CTA, selected ring, leading tally bar): #C2410C
• Accent (forest green — confirmed/success states, committee role badge): #1F4D3A
• Muted (labels, metadata, rules): #6B5D4F

No blue anywhere; no gradients. Colour is used as ink and paint, never as glow.

Typography:

• Headings: Alfa Slab One, heavy slab weight, all-caps for the wordmark and candidate names, tight tracking (-0.01em), with a thick orange underline rule beneath section titles.
• Body: Oswald at 400/500 with 1.6 line-height.
• Numerals: Oswald 600 for tallies.
• Labels: small all-caps Oswald 500 at 0.14em letterspacing (e.g. "NAMA", "NO HP").
• Scale: 1.25 modular — 20/25/31/39/49/61px body-to-display; hero wordmark clamp(48px, 11vw, 132px); candidate name clamp(28px, 5vw, 44px); section title clamp(24px, 4vw, 36px); body 17px mobile / 18px desktop; labels 12px.

Shape language: Chunky 2px-to-4px ink outlines around every card and panel; hard 0px corners on panels and buttons; badge shapes with a notched or stamped edge for status chips; thick horizontal rules dividing sections; halftone dot texture in the kraft ground; a circular wax-seal-style stamp motif for the "SUARA TERCATAT" confirmation. Nothing rounded, nothing soft, nothing glassy.

Layout: A ruled poster grid — full-bleed kraft ground, a 12-column grid at 1280px collapsing to a single column at 375px, sections separated by thick black rules with all-caps section labels in the left margin. Candidates appear as three tall badge-cards in a row that stack vertically on mobile; the vote screen shows the three candidates as large tappable panels with a physical ballot-slip feel; results render as a ruled tally board with horizontal bar rows, not a chart library. Every readable element sits inside its container with 16px minimum gutters at 375px.

Imagery: Thick-line vector icons drawn as if cut from rubber — a ballot box, a hand, a stamp, a rice stalk for Desa Tambi. Halftone-dot photographed textures of kraft paper and ink. Each candidate gets a large hand-built monogram badge (T, S, J) inside a circular stamp with their number, plus a thick-line pictogram representing their stated focus. Maps of the village drawn as thick-line diagrams. No stock photography, no 3D renders, no gradient blobs.

7. Signature Design Concept

The public entry is a full-bleed kraft-paper poster. The left two-thirds carries the wordmark "DESA TAMBI" set in Alfa Slab One at clamp(48px, 11vw, 132px), stacked on three lines, spanning the viewport width and slightly bled off the right edge on desktop, with the sub-line "SURVEI CALON KEPALA DESA · 2026–2034" in all-caps Oswald beneath a thick black rule. The right one-third holds a large circular ink stamp reading "PILIH · 1 DARI 3" rotated -8 degrees, overlapping the wordmark's last letter. Beneath the rule, a single burnt-orange button "MULAI MEMILIH" is pinned flush-left with a hard black outline, and a small all-caps line "Trisno · Suyitno · Juri" sits in muted ink. No centred stack, no subtext paragraph, no gradient, no floating cards.

The signature moves carry through the whole product: the rotated circular ink stamp ("PILIH · 1 DARI 3", then "SUARA TERCATAT") that overlaps the oversized wordmark and re-appears as the confirmation seal after a vote is submitted; candidate cards built as physical ballot badges with a numbered circular monogram stamp (1/T, 2/S, 3/J), a 4px black outline, a thick orange ring on the selected card, and a halftone kraft texture behind the name; section transitions marked by full-width 4px black rules with the section name in all-caps Oswald set in the left margin; the results board as a ruled tally sheet with stacked tick marks and a single burnt-orange bar per candidate; and form fields in the voter-details step rendered as index-card inputs with a kraft label strip above each field, a hard 2px bottom rule, and Oswald 600 input text.

8. Interaction Model & Motion Direction

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

Landing Hero Motion Brief

• Focal subject: The oversized "DESA TAMBI" wordmark and the rotated circular ink stamp "PILIH · 1 DARI 3".
• Input → transformation → outcome thesis: On load, the hero badge performs a one-time ink-bleed reveal; the stamp settles into its -8 degree rotation with a slight overshoot, as if a rubber stamp has just landed. The outcome is a composed, official poster frame with the "MULAI MEMILIH" button ready.
• Motion vocabulary: 120–180ms snap transitions; slight overshoot on the stamp; one-time ink-bleed reveal on the hero badge; instant state change on candidate selection. No parallax, no floating, no bouncy easing.
• Composed first frame: Kraft ground #EDE4D3, wordmark in Alfa Slab One, thick black rule, sub-line in all-caps Oswald, stamp at -8 degrees, burnt-orange "MULAI MEMILIH" button flush-left, muted "Trisno · Suyitno · Juri" line.
• Reduced-motion state: With prefers-reduced-motion, everything appears immediately and the tally bars render at final width.

9. Non-Functional Requirements

1. Legibility on low-cost devices: Body copy in Oswald at 1.6 line-height and 17px mobile / 18px desktop must read cleanly on a phone in daylight. (source-backed: creative direction)
2. Readable text and controls stay whole: At 375px, 768px, and 1280px, headlines, wordmarks, labels, numbers, card text, and controls stay entirely inside the viewport and their container, wrapping or scaling to fit; no other element covers any part of them. (source-backed: creative direction)
3. Reduced motion: With prefers-reduced-motion, all motion appears immediately and tally bars render at final width. (source-backed: creative direction)
4. No blue or indigo: The palette must not contain blue or indigo (no #2563EB, #4F46E5, #6366F1 or neighbours); the kraft #EDE4D3 ground must always be visible. (source-backed: creative direction)
5. No rounded or glassy surfaces: No rounded corners, pill buttons, soft drop shadows, or glassmorphism. (source-backed: creative direction)
6. No chart libraries: Tallies are drawn as ruled marks and bars, not charts or speedometer gauges. (source-backed: creative direction)
7. Backend integration: The survey requires server-side persistence of votes with voter Nama and No HP, and role-aware access for voters and panitia. (required_inference)

10. Tech Stack

• Frontend: React (custom UI, single-page application).
• Backend: Python / FastAPI.
• Storage: Appropriate persistent storage for votes and voter identity (Nama, No HP).
• Containerization: Docker / docker-compose for local and deployment packaging.
• Kubernetes: Not required for the current deployment scope.

11. Assumptions and Constraints

• Hard constraints (explicit): The survey covers only three candidates — Trisno, Suyitno, and Juri. A voter may choose only one of the three. Voter identity uses Nama and No HP.
• Assumption: Application-owned identity is used, with self-service Sign Up for voters and verification at Login for both voters and panitia. (required_inference)
• Assumption: The panitia role is authorized to view Results; voters are not. (required_inference)
• Assumption: The survey period label is 2026–2034 as stated by the user.
• Constraint: No blue or indigo in the palette; no gradients; no rounded corners; no chart libraries.
• Constraint: Readable text and controls must remain whole at 375px, 768px, and 1280px.
• Out of scope (current): Any additional candidates, elections, or administrative capabilities beyond the survey described above.

12. Glossary

• Survei Calon Kepala Desa Tambi Periode 2026–2034: The village head candidate survey for Desa Tambi covering the 2026–2034 period.
• Warga Pemilih (Voter): A resident of Desa Tambi who casts a survey vote.
• Penyelenggara Survei (Panitia): The committee organizing the survey and reviewing results.
• Nama: The voter's name, used as part of identity.
• No HP: The voter's phone number, used as part of identity.
• SUARA TERCATAT: The confirmation seal shown after a vote is recorded.
• PILIH · 1 DARI 3: The instruction stamp indicating a single choice among three candidates.