System Requirements Document for guru-pkn

1. Introduction

guru-pkn is a web application for Indonesian secondary-school civic education (PKN — Pendidikan Kewarganegaraan). It exists so that a PKN teacher can run the three core jobs of the subject — preparing learning materials, building a bank of questions and exercises, and assessing student work — inside a single tool, and so that students can read the materials their teacher prepared and work through the exercises assigned to them.

The product intent is deliberately narrow and institutional: it is a classroom instrument, not a general-purpose learning platform. Its audience is two active human roles — Guru PKN (the teacher, who authors and grades) and Siswa (the student, who reads and answers). Both roles share one application, one identity system, and one visual language, but they see different workspaces and different controls.

The design register is civic signage rather than commercial software: warm paper ground, ink text, signal colours used sparingly as curriculum wayfinding, and a numbered left rail that maps the PKN syllabus the way a transit map maps a city.

2. System Overview

guru-pkn is delivered as a first-party custom web application with application-owned identity. It has a public entry surface, a shared identity boundary (self-service enrollment and returning verification), a teacher workspace covering materials, questions, and grading, and a student workspace covering materials and exercises.

Actors

Accepted behavior in scope

• A bank of questions and exercises, authored and maintained by the teacher.
• Learning materials, authored and maintained by the teacher.
• Assessment (penilaian): reviewing student work and recording results.
• Student access to prepared materials and completion of prepared exercises.
• Self-service enrollment and returning verification for both roles, with role-aware routing to the correct workspace.

Narrow exclusions

• No third-party LMS, SSO provider, or external content marketplace is part of the current delivery.
• No parent, administrator, or school-management persona exists in the accepted catalog.
• No live/real-time collaborative authoring, no video conferencing, and no messaging between teacher and student is accepted.
• No native mobile application is accepted; delivery is a responsive web application.

2a. Product Interpretation and Delivery Boundary

Delivery ownership. The application is first-party and custom-built. Every page in the current information architecture is owned by the application itself; there is no provider-owned or external-destination surface in the accepted scope. The backend is application-owned and persists all durable state: materials, questions, exercises, student submissions, and recorded assessment results.

Access ownership. Identity is application-owned. Both personas establish their own access through self-service enrollment on Sign Up, and both return through Login. Because the two roles receive materially different workspaces and controls, enrollment captures the role so that the application can route each person to the correct protected workspace. The public entry surface (Landing) and the two identity surfaces (Login, Sign Up) are reachable without an established identity; every other destination requires an established identity and is scoped to the role that owns it.

Current vs. future. Everything described in Sections 2c, 3, and 5 is current. There is no accepted future horizon in the authoritative requirement thread; Section 11 records this explicitly rather than inventing a roadmap.

Boundary discipline. The application does not grade automatically, does not generate content, does not import from external curricula, and does not manage school rosters. Assessment is a teacher action: the teacher reviews submitted work and records the result.

2b. Source Content Inventory

Not applicable. No reference directive in this project declares content_source authority, so no source content inventory is produced.

2c. Page Content and Component Coverage

The page inventory below is the closed, ordered page contract for this project. Each page appears exactly once.

Landing

• Information and state. Anonymous public entry. Presents the application's purpose: a PKN learning application for teachers and students covering materials, exercises, and assessment. No personalized or protected state is shown.
• Primary actions. Enter as teacher (primary signal CTA), enter as student (plain text link beside it). Both lead to the identity boundary.
• Supporting actions. Navigate to Login for returning users; navigate to Sign Up for first-time users.
• Domain entities. None persisted. The page describes the four PKN curriculum strands as wayfinding legend rows: 01 Pancasila, 02 UUD 1945, 03 Bhinneka Tunggal Ika, 04 NKRI.
• Component responsibilities.
  • Civic-signage hero band: oversized flush-left headline "Pendidikan Kewarganegaraan" broken across three ragged lines, occupying the left seven of twelve columns.
  • Wayfinding legend column: four numbered strand rows, each with a 1px rule, a strand colour, and a small pictogram.
  • CTA block: solid signal-red square block labelled "Masuk sebagai Guru", with a plain text link "Masuk sebagai Siswa" beside it.
  • Full-viewport-width amber rule at the base of the band.
  • Subtle topographic/wayfinding line texture on the band ground.
• States. Loading: static content, no data fetch; the band renders immediately. Empty: not applicable. Success: not applicable. Error: not applicable. Recovery: not applicable.

Login

• Information and state. Anonymous returning-verification surface shared by both personas. Collects the credentials that identify a returning account and its role.
• Primary actions. Submit credentials to establish a session and be routed to the correct protected workspace.
• Supporting actions. Navigate to Sign Up when the visitor has no account; return to Landing.
• Domain entities. Account identity (email/identifier and credential), role (Guru PKN or Siswa).
• Component responsibilities.
  • Numbered page header band with section number badge, page title, and strand tag.
  • Credential form with labelled inputs and a single submit control.
  • Inline validation messaging region.
  • Link to Sign Up.
• States. Loading: submit control shows a pending state while verification is in flight; inputs are held. Empty: form renders with empty fields and no error. Success: session established; the person is routed to Materials (Guru PKN) or Student Materials (Siswa). Error: unrecognized credentials or failed verification produce an inline, non-destructive error message; the form retains the entered identifier so the person can correct the credential and resubmit. Recovery: repeated failure keeps the person on Login with the form usable; no lockout is imposed.

Sign Up

• Information and state. Anonymous self-service enrollment surface shared by both personas. Collects the information needed to create an account and to determine which protected workspace the person will receive.
• Primary actions. Create an account and establish a session.
• Supporting actions. Navigate to Login for people who already have an account; return to Landing.
• Domain entities. Account identity (name, email/identifier, credential), role selection (Guru PKN or Siswa).
• Component responsibilities.
  • Numbered page header band with section number badge, page title, and strand tag.
  • Enrollment form with labelled inputs, including an explicit role selection between Guru PKN and Siswa.
  • Inline validation messaging region.
  • Link to Login.
• States. Loading: submit control shows a pending state while the account is being created. Empty: form renders with empty fields and no error. Success: account created and session established; the person is routed to Materials (Guru PKN) or Student Materials (Siswa). Error: invalid or incomplete input, or an identifier already in use, produces an inline error naming the field; entered values are preserved so the person can correct and resubmit. Recovery: the person remains on Sign Up with the form usable and can alternatively move to Login.

Materials

• Information and state. Teacher workspace listing the PKN learning materials the teacher has authored, with strand coding and metadata. This is the teacher's landing workspace after verification.
• Primary actions. Open an existing material for editing; start a new material.
• Supporting actions. Filter or scan the list by strand; read material metadata (title, strand, last-updated).
• Domain entities. Material (title, body content, strand assignment, author, timestamps).
• Component responsibilities.
  • Numbered page header band (section 01 Materi) with strand tag.
  • Persistent numbered left rail (01 Materi, 02 Bank Soal, 03 Penilaian, 04 Siswa), collapsing to a numbered tab bar below 768px.
  • Two-pane layout: list column of ruled material rows plus detail pane.
  • Ruled list rows with hairline separators, 4px strand left borders, and aligned label/value pairs.
  • Sticky action bar for the primary create/open actions.
• States. Loading: list column shows a pending state while materials are fetched. Empty: no materials yet — the list column shows an explicit empty message with a direct action to create the first material. Success: rows render with strand coding and metadata. Error: a failed fetch shows an inline retry affordance in the list column without discarding the page. Recovery: retry re-requests the list; the teacher can also navigate away and return.

Material Editor

• Information and state. Focused authoring workspace for a single PKN learning material. Holds the material's title, strand assignment, and body content.
• Primary actions. Save the material; publish/save changes so students can read it.
• Supporting actions. Assign or change the strand; return to Materials without saving.
• Domain entities. Material (title, body content, strand assignment, author, timestamps).
• Component responsibilities.
  • Numbered page header band with section number badge, page title, and strand tag.
  • Title input and strand selector.
  • Body content editing region sized to a 68ch reading measure.
  • Sticky action bar holding save and cancel.
  • Unsaved-change indicator.
• States. Loading: editor shows a pending state while an existing material is fetched. Empty: a new material opens with empty title and body and no error. Success: save confirms visibly and the material appears in Materials with updated metadata. Error: a failed save shows an inline error and preserves the in-editor content so nothing is lost. Recovery: the teacher can retry the save; unsaved content remains in the editor until the save succeeds or the teacher explicitly discards it.

Question Bank

• Information and state. Teacher workspace listing the PKN questions and exercises the teacher has authored, with strand coding, question type, and metadata.
• Primary actions. Open an existing question for editing; start a new question.
• Supporting actions. Filter or scan by strand; read question metadata.
• Domain entities. Question/exercise (prompt, answer options, correct answer, strand assignment, author, timestamps).
• Component responsibilities.
  • Numbered page header band (section 02 Bank Soal) with strand tag.
  • Persistent numbered left rail, collapsing to a numbered tab bar below 768px.
  • Two-pane layout: list column of ruled question rows plus detail pane.
  • Ruled list rows with hairline separators, 4px strand left borders, and tabular figures for aligned metadata.
  • Sticky action bar for the primary create/open actions.
• States. Loading: list column shows a pending state while questions are fetched. Empty: no questions yet — explicit empty message with a direct action to create the first question. Success: rows render with strand coding and metadata. Error: a failed fetch shows an inline retry affordance without discarding the page. Recovery: retry re-requests the list.

Question Editor

• Information and state. Focused authoring workspace for a single PKN question or exercise. Holds the prompt, the answer options, the correct answer, and the strand assignment.
• Primary actions. Save the question; make it available for student exercises.
• Supporting actions. Assign or change the strand; add or remove answer options; return to Question Bank without saving.
• Domain entities. Question/exercise (prompt, answer options, correct answer, strand assignment, author, timestamps).
• Component responsibilities.
  • Numbered page header band with section number badge, page title, and strand tag.
  • Prompt input region.
  • Answer option rows with honest 4px-radius controls and a correct-answer marker.
  • Strand selector.
  • Sticky action bar holding save and cancel.
  • Unsaved-change indicator.
• States. Loading: editor shows a pending state while an existing question is fetched. Empty: a new question opens with an empty prompt and no error. Success: save confirms visibly and the question appears in Question Bank with updated metadata. Error: a failed save shows an inline error and preserves the in-editor content. Recovery: the teacher can retry the save; unsaved content remains until the save succeeds or the teacher explicitly discards it.

Grading

• Information and state. Teacher workspace for reviewing student submissions and recording assessment results. Lists submissions with the submitting student, the exercise, the strand, and the current assessment state.
• Primary actions. Open a submission, review the student's answers, and record the assessment result.
• Supporting actions. Scan and filter submissions by strand or state; revisit previously recorded results.
• Domain entities. Submission (student, exercise, answers, submitted timestamp), assessment result (score/outcome, teacher, recorded timestamp).
• Component responsibilities.
  • Numbered page header band (section 03 Penilaian) with strand tag.
  • Persistent numbered left rail, collapsing to a numbered tab bar below 768px.
  • Two-pane layout: list column of ruled submission rows plus detail pane showing the student's answers.
  • Ruled rows with hairline separators, 4px strand left borders, and tabular figures.
  • Result entry control and a sticky action bar holding the record action.
• States. Loading: list column shows a pending state while submissions are fetched. Empty: no submissions yet — explicit empty message explaining that submissions appear once students complete exercises. Success: a recorded result is confirmed visibly and the row reflects the new assessment state. Error: a failed fetch or a failed result save shows an inline error; a failed save preserves the entered result so it can be retried. Recovery: retry re-requests the list or re-attempts the save; the teacher can move to another submission and return.

Student Materials

• Information and state. Student-facing destination listing the learning materials the teacher has prepared, with strand coding. This is the student's landing workspace after verification.
• Primary actions. Open a material and read it.
• Supporting actions. Scan or filter the list by strand.
• Domain entities. Material (title, body content, strand assignment, author, timestamps) — read-only for the student.
• Component responsibilities.
  • Numbered page header band (section 04 Siswa) with strand tag.
  • Persistent numbered left rail, collapsing to a numbered tab bar below 768px.
  • Single reading column capped at 68ch with strand-coded headers.
  • Ruled list rows with hairline separators and 4px strand left borders.
• States. Loading: list shows a pending state while materials are fetched. Empty: no materials available yet — explicit empty message stating that materials will appear once the teacher publishes them. Success: materials render with strand coding. Error: a failed fetch shows an inline retry affordance. Recovery: retry re-requests the list.

Exercises

• Information and state. Student-facing destination for completing and submitting prepared PKN exercises. Presents one question per ruled panel with the strand colour on the left edge, and tracks progress through the exercise.
• Primary actions. Select an answer for each question and submit the completed exercise.
• Supporting actions. Move between questions; see progress as "Soal 3 dari 10" in tabular numerals.
• Domain entities. Exercise (set of questions), Question (prompt, answer options, strand), Submission (student, exercise, answers, submitted timestamp).
• Component responsibilities.
  • Numbered page header band with section number badge, page title, and strand tag.
  • Single-sheet exercise form: one question per ruled panel, strand colour on the left edge.
  • Answer options as radio rows with honest 4px-radius controls.
  • Sticky bottom bar showing progress in tabular numerals and holding the submit control.
• States. Loading: the exercise shows a pending state while questions are fetched. Empty: no exercises available yet — explicit empty message stating that exercises will appear once the teacher publishes them. Success: submission is confirmed visibly and the exercise is marked as submitted. Error: a failed submission shows an inline error and preserves the selected answers so the student can retry without re-answering. Recovery: retry re-attempts the submission with the preserved answers.

3. Functional Requirements

Identity and Access

FR-01 — Self-service enrollment (provenance: required_inference) As a prospective Guru PKN or Siswa, I should be able to create my own account on Sign Up by providing my identity details and selecting my role, so that I can begin using the application without an invitation or administrator.

• Trigger/input: Anonymous visitor submits the enrollment form with name, identifier, credential, and an explicit role selection (Guru PKN or Siswa).
• Observable result: An account is created, a session is established, and the person is routed to the protected workspace for the selected role.
• Access state: Anonymous entry; no identity required to reach Sign Up.
• Failure/recovery: Invalid or incomplete input, or an identifier already in use, produces an inline field-level error; entered values are preserved and the form remains usable. The person may instead move to Login.
• Continuation: On success, Guru PKN lands on Materials; Siswa lands on Student Materials.

FR-02 — Returning verification (provenance: required_inference) As a returning Guru PKN or Siswa, I should be able to verify my identity on Login so that I can resume my protected work.

• Trigger/input: Anonymous visitor submits credentials on Login.
• Observable result: A session is established and the person is routed to the workspace matching their role.
• Access state: Anonymous entry; no identity required to reach Login.
• Failure/recovery: Unrecognized credentials or failed verification produce an inline, non-destructive error; the identifier is retained so the person can correct the credential and resubmit. No lockout is imposed.
• Continuation: On success, Guru PKN lands on Materials; Siswa lands on Student Materials.

FR-03 — Role-aware workspace routing (provenance: required_inference) As an authenticated Guru PKN or Siswa, I should receive the workspace and controls appropriate to my role, so that I see only the work that belongs to me.

• Trigger/input: Successful verification or enrollment, and any subsequent navigation.
• Observable result: Guru PKN reaches Materials, Material Editor, Question Bank, Question Editor, and Grading; Siswa reaches Student Materials and Exercises. A person cannot reach the other role's destinations.
• Access state: Requires an established identity; destinations are role-scoped.
• Failure/recovery: An attempt to reach a destination outside one's role returns the person to their own workspace rather than exposing the other role's state.
• Continuation: The person continues within their own workspace.

Materials

FR-04 — Author a learning material (provenance: explicit) As a Guru PKN, I should be able to create a PKN learning material with a title, a strand assignment, and body content, so that my students have material to read.

• Trigger/input: From Materials, the teacher starts a new material and completes the title, strand, and body in Material Editor.
• Observable result: The material is saved and appears in Materials with its strand coding and updated metadata.
• Access state: Requires an established Guru PKN identity.
• Failure/recovery: A failed save shows an inline error and preserves the in-editor content; the teacher can retry without losing work.
• Continuation: The teacher returns to Materials or continues editing.

FR-05 — Manage the material library (provenance: explicit) As a Guru PKN, I should be able to revisit, scan, and edit the materials I have authored, so that my teaching content stays current.

• Trigger/input: The teacher opens Materials and selects an existing row.
• Observable result: The list renders with strand coding and metadata; the selected material opens in Material Editor for revision.
• Access state: Requires an established Guru PKN identity.
• Failure/recovery: A failed list fetch shows an inline retry affordance without discarding the page.
• Continuation: The teacher edits and saves, or returns to the list.

FR-06 — Read prepared materials (provenance: explicit) As a Siswa, I should be able to read the PKN learning materials my teacher has prepared, so that I can study the subject.

• Trigger/input: The student opens Student Materials and selects a material.
• Observable result: The material's content is displayed in a single reading column with strand-coded headers.
• Access state: Requires an established Siswa identity.
• Failure/recovery: A failed fetch shows an inline retry affordance; when no materials exist yet, an explicit empty message explains that materials appear once the teacher publishes them.
• Continuation: The student returns to the list and opens another material.

Question Bank and Exercises

FR-07 — Author a question or exercise item (provenance: explicit) As a Guru PKN, I should be able to create a question with a prompt, answer options, a correct answer, and a strand assignment, so that I can build exercises for my students.

• Trigger/input: From Question Bank, the teacher starts a new question and completes it in Question Editor.
• Observable result: The question is saved and appears in Question Bank with its strand coding and metadata.
• Access state: Requires an established Guru PKN identity.
• Failure/recovery: A failed save shows an inline error and preserves the in-editor content; the teacher can retry without losing work.
• Continuation: The teacher returns to Question Bank or continues editing.

FR-08 — Manage the question bank (provenance: explicit) As a Guru PKN, I should be able to revisit, scan, and edit the questions I have authored, so that my exercise bank stays accurate and reusable.

• Trigger/input: The teacher opens Question Bank and selects an existing row.
• Observable result: The list renders with strand coding, question type, and metadata; the selected question opens in Question Editor for revision.
• Access state: Requires an established Guru PKN identity.
• Failure/recovery: A failed list fetch shows an inline retry affordance without discarding the page.
• Continuation: The teacher edits and saves, or returns to the list.

FR-09 — Complete and submit an exercise (provenance: explicit) As a Siswa, I should be able to work through a prepared PKN exercise and submit my answers, so that my teacher can assess my work.

• Trigger/input: The student opens Exercises, selects an answer for each question, and submits.
• Observable result: The submission is recorded against the student and the exercise, and the exercise is marked as submitted.
• Access state: Requires an established Siswa identity.
• Failure/recovery: A failed submission shows an inline error and preserves the selected answers so the student can retry without re-answering. When no exercises exist yet, an explicit empty message explains that exercises appear once the teacher publishes them.
• Continuation: The student sees the submitted state and can return to Student Materials or another exercise.

Assessment

FR-10 — Review student submissions (provenance: explicit) As a Guru PKN, I should be able to review the submissions my students have made, so that I can assess their work.

• Trigger/input: The teacher opens Grading and selects a submission.
• Observable result: The list renders with the submitting student, the exercise, the strand, and the current assessment state; the detail pane shows the student's answers.
• Access state: Requires an established Guru PKN identity.
• Failure/recovery: A failed fetch shows an inline retry affordance; when no submissions exist yet, an explicit empty message explains that submissions appear once students complete exercises.
• Continuation: The teacher records a result or moves to another submission.

FR-11 — Record an assessment result (provenance: explicit) As a Guru PKN, I should be able to record an assessment result for a reviewed submission, so that the student's work is evaluated and the result is retained.

• Trigger/input: The teacher enters the result for a selected submission in Grading and records it.
• Observable result: The result is saved against the submission and the row reflects the new assessment state.
• Access state: Requires an established Guru PKN identity.
• Failure/recovery: A failed save shows an inline error and preserves the entered result so it can be retried.
• Continuation: The teacher moves to the next submission.

FR-12 — Receive an assessment result (provenance: required_inference) As a Siswa, I should be able to see the assessment result my teacher recorded for my submitted exercise, so that I know how my work was evaluated.

• Trigger/input: The student opens Exercises and views a submitted exercise.
• Observable result: The recorded result for that submission is displayed to the student who submitted it, and to no other student.
• Access state: Requires an established Siswa identity; the result is bound to the submitting student.
• Failure/recovery: A failed fetch shows an inline retry affordance; a submission that has not yet been assessed shows an explicit "not yet assessed" state rather than a blank or misleading value.
• Continuation: The student returns to the exercise list or to Student Materials.

4. User Personas

Guru PKN

Product context. The teacher is the authoring and assessing role. They arrive at guru-pkn with subject expertise and a syllabus to cover, and they need one place to hold the three artifacts of their job: the materials students read, the questions students answer, and the results students receive. They are the only role that creates content, and the only role that evaluates it.

Primary goal. To run the full PKN teaching cycle — prepare materials, build the exercise bank, and assess student work — without leaving the application.

Distinct accepted responsibilities.

• Authoring and revising PKN learning materials, including assigning each to a curriculum strand.
• Authoring and revising questions and exercises, including defining answer options and the correct answer.
• Reviewing student submissions and recording assessment results.

Relevant inputs and decisions. The teacher decides what content to create, which strand each item belongs to, which answer is correct, and what result to record for each submission. Their inputs are titles, body content, prompts, options, correct answers, strand assignments, and results.

Interactions with other accepted participants. The teacher's authored materials and exercises are what the Siswa reads and answers; the teacher's recorded results are what the Siswa receives. The teacher does not interact with students directly inside the application — the handoff is asynchronous and mediated by the persisted content and submissions.

Observable success. The teacher can create a material and see it listed; create a question and see it listed; open a student submission, review the answers, record a result, and see the row reflect the recorded state.

What makes this role different. The teacher is the only role with write authority over content and the only role that produces assessment outcomes. Their workspace is a two-pane authoring and review environment with a sticky action bar; the student's workspace is a single reading and answering column. The teacher's work is generative and evaluative; the student's work is receptive and responsive.

Siswa

Product context. The student is the receiving and responding role. They arrive at guru-pkn to read what their teacher prepared and to work through the exercises assigned to them. They do not create content and do not see other students' work or results.

Primary goal. To access the PKN materials prepared by the teacher and complete the exercises, then learn how their work was assessed.

Distinct accepted responsibilities.

• Reading teacher-prepared PKN learning materials.
• Completing prepared exercises by selecting an answer for each question and submitting.
• Viewing the assessment result recorded for their own submission.

Relevant inputs and decisions. The student decides which material to read and which answer to select for each question. Their inputs are answer selections and the act of submission.

Interactions with other accepted participants. The student's experience is entirely shaped by the teacher's authored content: the materials they read and the exercises they answer are the teacher's work, and the result they receive is the teacher's recorded assessment. The student's submission is what the teacher reviews in Grading.

Observable success. The student can open a material and read it; open an exercise, answer every question, submit, and see the submitted state; and later see the recorded result for that submission.

What makes this role different. The student has no authoring or grading authority. Their workspace is a single reading column at a 68ch measure and a single-sheet exercise form with a sticky progress bar. Their state is bound to their own identity: they see their own submissions and results, not anyone else's.

5. Core User Flows

Flow A — Guru PKN enrolls and reaches the teacher workspace

1. The teacher opens Landing without an identity and reads the civic-signage hero band, which names the subject and shows the four strand legend rows (01 Pancasila, 02 UUD 1945, 03 Bhinneka Tunggal Ika, 04 NKRI).
2. The teacher selects the primary signal CTA "Masuk sebagai Guru".
3. The application presents the identity boundary. Because the teacher has no account yet, they move to Sign Up.
4. On Sign Up, the teacher enters their name, identifier, and credential, and explicitly selects the role Guru PKN.
5. The teacher submits. The application creates the account, establishes a session, and routes the teacher to Materials.
6. Observable result: the teacher lands on Materials with the numbered left rail (01 Materi, 02 Bank Soal, 03 Penilaian, 04 Siswa) visible and the teacher workspace available.
7. Failure/recovery: if the identifier is already in use or a field is invalid, an inline error names the field, the entered values are preserved, and the teacher corrects and resubmits — or moves to Login instead.
8. Next step: the teacher begins authoring (Flow B) or moves to the question bank (Flow D).

Flow B — Guru PKN authors a learning material

1. Starting from Materials, the teacher selects the create action in the sticky action bar.
2. Material Editor opens with an empty title and body.
3. The teacher enters a title, assigns the material to a curriculum strand, and writes the body content in the 68ch editing region.
4. The teacher saves. The application persists the material.
5. Observable result: the save is confirmed visibly, and the material appears in Materials as a ruled row with its 4px strand left border and updated metadata.
6. Failure/recovery: if the save fails, an inline error appears and the in-editor content is preserved; the teacher retries the save without losing work.
7. Next step: the teacher returns to Materials to author another material, or moves to Question Bank.

Flow C — Guru PKN revises an existing material

1. Starting from Materials, the teacher scans the ruled rows and selects an existing material.
2. Material Editor opens with the material's current title, strand, and body loaded.
3. The teacher changes the content or reassigns the strand and saves.
4. Observable result: the save is confirmed and the row in Materials reflects the updated metadata.
5. Failure/recovery: a failed save preserves the edits in the editor for retry.
6. Next step: the teacher returns to the list or continues editing.

Flow D — Guru PKN authors a question

1. Starting from Question Bank, the teacher selects the create action in the sticky action bar.
2. Question Editor opens with an empty prompt.
3. The teacher writes the prompt, adds answer options, marks the correct answer, and assigns the question to a curriculum strand.
4. The teacher saves. The application persists the question.
5. Observable result: the save is confirmed visibly, and the question appears in Question Bank as a ruled row with its strand coding and metadata.
6. Failure/recovery: if the save fails, an inline error appears and the in-editor content is preserved; the teacher retries.
7. Next step: the teacher returns to Question Bank to author more questions, or moves to Grading.

Flow E — Guru PKN reviews a submission and records a result

1. Starting from Grading, the teacher scans the ruled submission rows, each showing the submitting student, the exercise, the strand, and the current assessment state.
2. The teacher selects a submission. The detail pane shows the student's answers for that exercise.
3. The teacher reviews the answers and enters the assessment result.
4. The teacher records the result from the sticky action bar. The application persists the result against the submission.
5. Observable result: the recorded result is confirmed visibly and the row in Grading reflects the new assessment state.
6. Failure/recovery: if the save fails, an inline error appears and the entered result is preserved so the teacher can retry. If the list fetch fails, an inline retry affordance appears without discarding the page.
7. Next step: the teacher moves to the next submission, or leaves Grading.

Flow F — Siswa enrolls and reaches the student workspace

1. The student opens Landing without an identity and reads the hero band and strand legend.
2. The student selects the plain text link "Masuk sebagai Siswa" beside the primary CTA.
3. The application presents the identity boundary. Because the student has no account yet, they move to Sign Up.
4. On Sign Up, the student enters their name, identifier, and credential, and explicitly selects the role Siswa.
5. The student submits. The application creates the account, establishes a session, and routes the student to Student Materials.
6. Observable result: the student lands on Student Materials with the numbered left rail visible and the student workspace available.
7. Failure/recovery: if the identifier is already in use or a field is invalid, an inline error names the field, the entered values are preserved, and the student corrects and resubmits — or moves to Login instead.
8. Next step: the student reads a material (Flow G) or moves to Exercises (Flow H).

Flow G — Siswa reads a prepared material

1. Starting from Student Materials, the student scans the ruled rows, each carrying its strand colour on the left border.
2. The student selects a material.
3. The material opens in a single reading column capped at 68ch with strand-coded headers.
4. Observable result: the student reads the teacher-prepared content.
5. Failure/recovery: if the fetch fails, an inline retry affordance appears. If the teacher has not yet published any material, an explicit empty message explains that materials will appear once the teacher publishes them.
6. Next step: the student returns to the list and opens another material, or moves to Exercises.

Flow H — Siswa completes and submits an exercise

1. Starting from Exercises, the student opens a prepared exercise.
2. The exercise renders as a single-sheet form: one question per ruled panel with the strand colour on the left edge, and answer options as radio rows.
3. The student selects an answer for each question. The sticky bottom bar shows progress as "Soal 3 dari 10" in tabular numerals.
4. The student submits the completed exercise. The application records the submission against the student and the exercise.
5. Observable result: the submission is confirmed visibly and the exercise is marked as submitted.
6. Failure/recovery: if the submission fails, an inline error appears and the selected answers are preserved so the student can retry without re-answering. If no exercises exist yet, an explicit empty message explains that exercises will appear once the teacher publishes them.
7. Next step: the student returns to the exercise list or to Student Materials.

Flow I — Siswa receives an assessment result

1. Starting from Exercises, the student opens an exercise they have already submitted.
2. The application displays the assessment result the teacher recorded for that submission.
3. Observable result: the student sees the recorded result for their own work, and only their own work.
4. Failure/recovery: if the fetch fails, an inline retry affordance appears. If the teacher has not yet recorded a result, an explicit "not yet assessed" state is shown rather than a blank or misleading value.
5. Next step: the student returns to the exercise list or to Student Materials.

6. Visuals, Colors and Theme

Muse and headline. Erik Spiekermann — Typographic infrastructure for civic education: wayfinding clarity with a warm signal-coded spine. The design reads as public information infrastructure, not commercial SaaS: warm paper ground, ink text, and signal colours used like transit lines to code the PKN syllabus.

Colour tokens — light mode

Proportion discipline. 70% warm ground and white, 20% ink text, 10% signal colours total. Signals stay scarce so they read as wayfinding, not decoration. Strand colours are used only as 4px left borders, tags, and small pictograms — never as large fills.

Typography

• Headings: Fira Sans, 600–700 weight, tracking −0.01em, sentence case (never all-caps, so Indonesian words stay readable). 500 for UI labels and tab labels. 700 reserved for section numbers and the hero headline. Numbers and strand codes set in Fira Sans with tabular figures.
• Body: Fira Sans.
• Scale: 1.25 modular, 1.333 for display — hero clamp(40px, 7vw, 88px) / h1 40px / h2 28px / h3 22px / body 17px / small 14px / micro-label 12px uppercase tracked +0.08em.
• Line-height: 1.15 for display, 1.55 for body. Reading measure capped at 68ch.

Shape language

Rectangular and honest: 4px–8px radii on cards, inputs, and buttons — not pills, not blobs. Thin 1px rules in #D8D0C2 structure every list and panel. Signal-colour left borders (4px) mark strand identity on cards and rows. Section numbers sit in square outlined badges. No shadow heavier than 0 1px 2px rgba(26,24,21,0.08); hierarchy comes from rules, weight, and colour coding, not elevation.

Layout

A visible 12-column grid with a persistent left rail on desktop: numbered sections (01 Materi, 02 Bank Soal, 03 Penilaian, 04 Siswa) as a wayfinding spine, collapsing to a horizontal numbered tab bar below 768px. Teacher workspaces use a two-pane layout — list column plus detail pane — with a sticky action bar. Student views use a single reading column at 68ch with strand-coded headers. Rules run full width; content aligns flush-left, ragged-right. Every page opens with a numbered page header band: thin rule top and bottom, section number left, title, and a strand-coded tag right.

Imagery

Pictograms and diagrams, not photography: a custom icon set drawn on a 24px grid with 1.5px strokes in the strand colours; schematic diagrams for PKN concepts (separation of powers, hierarchy of laws, archipelago map as a simple line diagram); and a subtle topographic/wayfinding line texture on the landing hero. No stock classroom photos, no 3D, no gradient blobs.

7. Signature Design Concept

The civic-signage hero band. The public entry is a full-width band on the warm paper ground #F2EDE3, composed as a piece of public wayfinding rather than a marketing hero.

• Left seven of twelve columns: the words "Pendidikan Kewarganegaraan" set flush-left in Fira Sans 700 at clamp(40px, 7vw, 88px), ink #1A1815, broken across three ragged lines. No centred headline, no subtext paragraph.
• Right columns: a stacked column of four strand-coded numbered rows — 01 Pancasila (#B5321E), 02 UUD 1945 (#E8A317), 03 Bhinneka Tunggal Ika (#2E6E63), 04 NKRI (#3E5B34) — each with a 1px rule and a small pictogram. This is a miniature wayfinding legend, not a feature card grid.
• Beneath the headline: a single solid signal-red CTA block (#B5321E, square, 8px radius, white label "Masuk sebagai Guru") sitting flush-left, with a plain text link "Masuk sebagai Siswa" beside it.
• At the band's base: a thin amber rule running the full viewport width.
• Ground texture: a subtle topographic/wayfinding line texture behind the band, drawn in muted tones so it never competes with the headline or the controls.

The concept recomposes only accepted content — the subject name, the four curriculum strands, and the two entry paths — into a legible civic map of the syllabus. It introduces no new behaviour, page, or destination.

8. Interaction Model & Motion Direction

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

Landing Hero Motion Brief

• Focal subject. The oversized flush-left headline "Pendidikan Kewarganegaraan" and the four-row strand legend beside it.
• Input → transformation → outcome thesis. On page load, the numbered strand badges tick up once and each strand row's 4px colour border wipes in from the left in a single 200ms pass; the outcome is a fully composed wayfinding legend that reads as a static civic sign once the pass completes. No input beyond page load is required, and no accepted behaviour is added.
• Motion vocabulary. Functional and short — 120–180ms ease-out on state changes, tab transitions, and list reveals; strand colour wipes in from the left on card entry (one pass, 200ms); number badges tick up once on page load; hover on list rows shifts the 4px strand border to full opacity. No bounce, no parallax, no decorative loops.
• Composed first frame. The headline occupies the left seven columns at full display size, the four strand rows are stacked at the right with their rules and pictograms, the signal-red CTA block and the plain text link sit flush-left beneath the headline, and the amber rule runs the full viewport width at the band's base. This frame is complete and legible before any motion runs.
• Reduced-motion state. With prefers-reduced-motion, the wipes and ticks are disabled and all state changes are instant; the composed first frame above is the rendered result, fully readable and fully operable.

9. Non-Functional Requirements

NFR-01 — Responsive legibility (provenance: explicit — creative direction) Readable text and controls must stay whole at every viewport. Headlines, wordmarks, labels, numbers, and card text and controls must remain entirely inside the viewport and their container at 375px, 768px, and 1280px, wrapping or scaling (for example font-size: clamp(...) with its mobile size) to fit, and no other element may cover any part of them. Imagery, decoration, and motion may be cropped, bled off an edge, rotated, overlapped, or cut as the direction asks, provided they cover no readable text or control. Rationale: the application is used on classroom and student devices of varying widths, and the numbered rail must remain legible when it collapses to a tab bar below 768px.

NFR-02 — Reduced-motion support (provenance: explicit — creative direction) With prefers-reduced-motion, wipes and ticks are disabled, leaving instant state changes, and a usable static arrangement is provided for any moving or scrollable content. Rationale: accessibility for users who have requested reduced motion.

NFR-03 — Role-scoped data isolation (provenance: required_inference) A Siswa's submissions and assessment results are bound to that student's identity and are not visible to any other student. A Guru PKN's authoring and grading destinations are not reachable by a Siswa. Rationale: the accepted behavior creates durable, identity-bound state (submissions and results) that must remain bound to the correct participant.

NFR-04 — Durable persistence of authored and submitted state (provenance: required_inference) Materials, questions, submissions, and recorded assessment results persist across sessions so that a teacher can resume authoring and a student can revisit a submitted exercise and its result. Rationale: the accepted journeys require revisiting and resuming durable state.

NFR-05 — Non-destructive failure handling (provenance: required_inference) A failed save or submission must not discard the user's in-progress input; the entered content is preserved and the action can be retried. Rationale: authoring and answering are effortful, and the accepted journeys require recovery without re-entry.

NFR-06 — Typographic and colour fidelity (provenance: explicit — creative direction) Fira Sans is the only typeface for headings and body. The palette is the warm paper ground with signal red and amber; the generic indigo/blue-on-white SaaS template is forbidden for this project. Rationale: the design register is civic signage, and the strand colour coding is functional wayfinding, not decoration.

10. Tech Stack

• Frontend: React — a responsive web application. No native mobile application is accepted.
• Backend: Python with FastAPI, providing the application-owned API for identity, materials, questions, submissions, and assessment results.
• Storage: A relational database appropriate to the persisted entities (accounts, materials, questions, submissions, assessment results).
• Containerization: Docker with docker-compose for local and single-host deployment.
• Kubernetes: not required by any accepted requirement; omitted.

Note: the authoritative requirement thread does not name a technology stack. The items above are the minimal coherent stack for the accepted custom-UI, backend-integrated delivery shape and are recorded here as the implementation baseline rather than as user-specified choices.

11. Assumptions and Constraints

Assumptions

• A-01 (required_inference) — Enrollment is self-service for both roles because no invitation, provisioning, or pre-existing-account boundary is established for either persona.
• A-02 (required_inference) — Enrollment captures the role (Guru PKN or Siswa) so that the application can route each person to the correct protected workspace and apply the correct controls.
• A-03 (required_inference) — A student's submissions and results are bound to that student's identity; the teacher sees all submissions in Grading, and a student sees only their own.
• A-04 (required_inference) — The four PKN curriculum strands (Pancasila, UUD 1945, Bhinneka Tunggal Ika, NKRI) are the strand vocabulary used for coding materials, questions, and grading rows, as established by the creative direction.
• A-05 (required_inference) — A question has a prompt, a set of answer options, and one correct answer, because the accepted behavior requires the teacher to author questions and the student to select answers.

Constraints

• C-01 (explicit) — The application is for PKN (Pendidikan Kewarganegaraan) teaching and learning; it is not a general-purpose LMS.
• C-02 (explicit) — The active human roles are exactly Guru PKN and Siswa. No other persona is in scope.
• C-03 (explicit) — The current feature scope is exactly: bank soal/latihan, materi pembelajaran, and penilaian. No adjacent capability is added.
• C-04 (explicit — creative direction) — Fira Sans only for headings and body; the indigo/blue-on-white SaaS template is forbidden.
• C-05 (explicit — creative direction) — Controls stay rectangular at 4–8px radii; no pill buttons, no 20px+ radii, no glassmorphism, no gradient-blob heroes, no stock classroom photography, no 3D renders, no particle effects.
• C-06 (explicit — creative direction) — Motion stays functional and short (120–180ms ease-out; strand wipes one pass at 200ms); no bounce, no loops, no parallax, no scroll-linked animation.
• C-07 (explicit — creative direction) — Signal colours stay scarce: 70% warm ground and white, 20% ink text, 10% signal colours total.

Future horizon

• F-01 — No future requirements are established by the authoritative requirement thread. Nothing beyond the current scope is planned or promised in this document.

12. Glossary

• PKN (Pendidikan Kewarganegaraan) — Civic education, the Indonesian secondary-school subject this application serves.
• Guru PKN — The teacher persona; the authoring and assessing role.
• Siswa — The student persona; the reading and answering role.
• Materi (Materials) — PKN learning content authored by the teacher and read by students.
• Bank Soal (Question Bank) — The teacher's maintained collection of questions and exercises.
• Penilaian (Grading/Assessment) — The teacher's review of student submissions and recording of results.
• Strand — One of the four PKN curriculum domains used as a colour-coded wayfinding category: Pancasila (#B5321E), UUD 1945 (#E8A317), Bhinneka Tunggal Ika (#2E6E63), NKRI (#3E5B34).
• Submission — A student's recorded set of answers to a prepared exercise.
• Assessment result — The outcome a teacher records against a submission.
• Wayfinding rail — The persistent numbered left spine (01 Materi, 02 Bank Soal, 03 Penilaian, 04 Siswa) that collapses to a numbered tab bar below 768px.
• Numbered page header band — The thin-rule band opening every page, containing the section number in a square outlined badge, the page title, and a strand tag.