System Requirements Document for karma-yatra

1. Introduction

Karma Yatra is a pilgrimage and yatra platform. It exists so that a traveler can browse sacred journeys, register or join one, and follow its itinerary and updates through to completion; so that an organizer can publish yatra details, itineraries, and schedules and manage the registrations and participant communication that make a yatra run; and so that a platform administrator can oversee the published catalog, organizer accounts, and participant records and resolve issues that block journeys.

The product intent is derived from the authoritative user requirement thread: build the platform Karma Yatra from the project briefs, with the project briefs as the authoritative content source for the platform's scope and features. The briefs themselves were referenced but not supplied in the authoritative source text; this document therefore specifies the platform's structure, actors, ownership, and behavior at the level the accepted requirement thread and planning scope establish, and treats the briefs as the authoritative source that governs the platform's detailed scope and features.

The audience is spiritually motivated rather than transactionally motivated. The interface is expected to feel honest, calm, and unhurried — a working platform wearing the surface of paper rather than a dashboard.

2. System Overview

Karma Yatra is delivered as a first-party web application with custom UI and application-owned identity. It comprises:

• A public, anonymous entry and browsing surface: Landing, Yatras, and Yatra Details.
• A shared neutral access surface: Login, which owns self-service enrollment and returning verification for participants and organizers, and returning verification for provisioned administrators.
• Protected, role-appropriate working destinations: My Participation (participant), Create Yatra and Registrations (organizer), and Admin (administrator).

Actors are the closed accepted persona set — Pilgrim / Yatra Participant, Yatra Organizer / Operator, and Platform Administrator — plus the platform's own backend processes that persist yatra, registration, and account state.

Accepted behavior covers: anonymous catalog browsing and yatra detail review; self-service enrollment and returning verification; participant registration/joining and management of their own participation details; organizer creation and publishing of yatra details, itinerary, and schedule; organizer management of registrations and communication of journey updates to participants; and administrator oversight of published yatras, organizer accounts, and participant records.

Narrow exclusions: this document does not add adjacent capabilities beyond the accepted thread and planning scope — no payment processing, no messaging or social features, no recommendation engine, no third-party booking integration, and no account-management surface beyond the enrollment and verification owned by Login. The project briefs remain the authoritative source for the platform's detailed scope and features; where the briefs specify additional detail, that detail governs.

2a. Product Interpretation and Delivery Boundary

Karma Yatra is delivered as a first-party application. The application owns its own identity: a participant or organizer establishes access to protected work by completing self-service enrollment and returning verification through the Login surface, and an administrator account is provisioned before the administrator can reach the Admin oversight workspace. Role-appropriate authorization is enforced for the organizer and administrator working destinations, so that a participant's own participation workspace, an organizer's publishing and registration workspaces, and the administrator's oversight workspace each remain bound to the correct participant.

Anonymous access is a deliberate part of the product, not a gap: a visitor can browse the yatra catalog and open yatra details before any identity establishment. The protected destinations — My Participation, Create Yatra, Registrations, and Admin — require established identity and the appropriate role. Login is itself anonymously reachable, because a protected destination cannot own the interaction that establishes access to itself.

Current delivery covers the accepted journeys described in this document. Future or unspecified work — including any capability the project briefs describe that is not represented in the accepted requirement thread — remains outside current acceptance and is not implemented as part of this scope.

2b. Source Content Inventory

The reference directive for the project briefs declares content_source with authoritative authority, but the briefs' content was not included in the authoritative source text. No verified factual entities, collection items, fields, values, descriptions, dates, contacts, links, or media references from the briefs are available to inventory. The briefs remain the authoritative source for the platform's scope and features and must be consulted directly for their content.

2c. Page Content and Component Coverage

Landing

• Information/state: The public first impression of Karma Yatra — what the platform is, who it is for, and what it does. Presented as a stack of quiet bands separated by full-width rules: wordmark, one sentence of purpose, a single featured yatra, then a catalog preview.
• Primary actions: Follow the plain underlined text link to browse yatras; follow the featured yatra into its details.
• Supporting actions: Navigate to Login to enroll or verify; navigate to the catalog.
• Domain entities: Yatra (featured and preview entries), platform identity and purpose copy.
• Component responsibilities: Hero band (wordmark, purpose line, single still-life image, one plain underlined text link as the only call to action); featured-yatra band; catalog-preview band; top navigation rule with wordmark left and text links right.
• States: Loading — quiet placeholder bands with hairlines, no spinners or skeletons with color. Empty — if no yatras are published, the featured and preview bands are omitted and the purpose band stands alone. Success — bands render with the featured yatra and catalog preview. Error — if the catalog cannot be loaded, the preview band is replaced by a single muted line stating the catalog is unavailable, with a retry link. Recovery — retry reloads the catalog without leaving the page.

Yatras

• Information/state: The available yatra catalog as a vertical list of full-width bands, each with the yatra name in large serif on the left and date and duration in muted small caps on the right, separated by 1px hairlines.
• Primary actions: Open a yatra's details.
• Supporting actions: Navigate to Login to enroll or verify; return to Landing.
• Domain entities: Yatra (name, date, duration, and any brief-specified summary fields).
• Component responsibilities: Catalog list with hairline-separated rows; per-row link into Yatra Details; top navigation rule.
• States: Loading — hairline-ruled placeholder rows. Empty — a single muted line stating no yatras are currently published. Success — the full catalog list renders. Error — a muted line stating the catalog could not be loaded, with a retry link. Recovery — retry reloads the list in place.

Yatra Details

• Information/state: A single yatra's details, itinerary, and schedule, opened from the catalog.
• Primary actions: Register for or join the yatra (which requires established identity and continues in My Participation); return to the catalog.
• Supporting actions: Navigate to Login to enroll or verify before registering.
• Domain entities: Yatra (name, description, itinerary, schedule, date, duration, and any brief-specified detail fields).
• Component responsibilities: Yatra header band; itinerary and schedule presentation as aligned label/value rows with hairlines; registration entry point; top navigation rule.
• States: Loading — hairline-ruled placeholder rows for header, itinerary, and schedule. Empty — if a yatra has no itinerary or schedule entries yet, those bands show a single muted line stating details are forthcoming. Success — full details, itinerary, and schedule render. Error — a muted line stating the yatra could not be loaded, with a retry link and a link back to the catalog. Recovery — retry reloads the yatra; returning to the catalog is always available.

My Participation

• Information/state: The participant's own participation records — the yatras they have registered for or joined, and their own participation details.
• Primary actions: Register for or join a yatra; update or manage their own participation details.
• Supporting actions: Open a yatra's details; navigate to the catalog.
• Domain entities: Participation (participant, yatra, status, and the participant's own details), Yatra reference.
• Component responsibilities: Participation list as tabular rows with label left and value right in a centered measure, hairlines between rows; registration/join action; participation-detail editing; top navigation rule.
• States: Loading — tabular placeholder rows. Empty — a single muted line stating the participant has no participation yet, with a link to browse yatras. Success — participation records render with their current status. Error — a muted line stating participation could not be loaded, with a retry link. Recovery — retry reloads the participant's records; the participant can always return to the catalog to start a new registration.

Create Yatra

• Information/state: The organizer's creation and publishing workspace for a yatra's details, itinerary, and schedule.
• Primary actions: Create a yatra; publish it to the catalog.
• Supporting actions: Edit details, itinerary, and schedule before publishing; return to Registrations.
• Domain entities: Yatra (name, description, itinerary, schedule, date, duration, and any brief-specified fields), publication state.
• Component responsibilities: Yatra detail form; itinerary and schedule entry as aligned label/value rows; publish action; validation feedback; top navigation rule.
• States: Loading — form fields render in a quiet placeholder state while any existing draft loads. Empty — a blank creation form for a new yatra. Success — the yatra is saved and published, and appears in the catalog. Error — validation errors are shown as muted inline messages beside the offending field; a publish failure shows a muted line with a retry action and preserves the entered content. Recovery — the organizer corrects the field or retries publishing without losing entered content.

Registrations

• Information/state: The organizer's recurring workspace for the registrations on their yatras and for communicating journey updates to participants.
• Primary actions: Review and manage registrations; send a journey update to participants.
• Supporting actions: Open a yatra's details; navigate to Create Yatra.
• Domain entities: Registration (participant, yatra, status), Participant reference, Journey update (message content, target yatra).
• Component responsibilities: Registration list as tabular rows with label left and value right in a centered measure, hairlines between rows; registration status management; journey-update composition and send; top navigation rule.
• States: Loading — tabular placeholder rows. Empty — a single muted line stating no registrations exist yet for the organizer's yatras. Success — registrations render with their current status, and a sent update is confirmed. Error — a muted line stating registrations could not be loaded, with a retry link; a failed update send shows a muted line with a retry action and preserves the composed message. Recovery — retry reloads registrations or resends the update.

Admin

• Information/state: The administrator's oversight workspace for published yatras, organizer accounts, and participant records.
• Primary actions: Review published yatras, organizer accounts, and participant records; resolve issues that block journeys.
• Supporting actions: Navigate between the published-yatra, organizer-account, and participant-record views.
• Domain entities: Yatra (publication state), Organizer account, Participant record.
• Component responsibilities: Oversight views as tabular rows with label left and value right in a centered measure, hairlines between rows; issue-resolution actions; top navigation rule.
• States: Loading — tabular placeholder rows. Empty — a single muted line per view stating there is nothing to review in that view. Success — published yatras, organizer accounts, and participant records render. Error — a muted line stating the view could not be loaded, with a retry link. Recovery — retry reloads the view; the administrator can switch views without losing position.

Login

• Information/state: The shared neutral access surface. It owns self-service enrollment and returning verification for participants and organizers, and returning verification for provisioned administrators.
• Primary actions: Enroll as a participant or organizer; verify as a returning participant, organizer, or provisioned administrator.
• Supporting actions: Switch between enrollment and verification; return to Landing.
• Domain entities: Account (participant or organizer), Administrator credential (provisioned), session.
• Component responsibilities: Enrollment form; verification form; mode switch; validation and failure feedback; top navigation rule.
• States: Loading — the form renders in a quiet placeholder state. Empty — the enrollment form for a first-time visitor. Success — enrollment completes and the participant or organizer continues to their working destination; verification succeeds and the actor continues to their role-appropriate destination. Error — invalid or unrecognized credentials show a muted line stating verification failed, without revealing which field was wrong; a failed enrollment shows muted inline validation beside the offending field. Recovery — the actor corrects the field or retries verification; the mode switch remains available throughout.

3. Functional Requirements

FR-1 — Anonymous catalog browsing (explicit) As a Pilgrim / Yatra Participant, I should browse the yatra catalog and open yatra details anonymously, before any identity establishment, so that I can evaluate journeys before committing to one.

• Trigger/input: the visitor opens Yatras or follows a catalog link from Landing.
• Observable result: the catalog renders as a hairline-separated vertical list of yatras with name, date, and duration; opening a yatra renders its details, itinerary, and schedule in Yatra Details.
• Access state: anonymous; no identity required.
• Failure/recovery: if the catalog or a yatra cannot be loaded, a muted line states the failure with a retry link; the visitor can return to the catalog.
• Continuation: the visitor proceeds to register or join, which requires established identity.

FR-2 — Self-service enrollment (required_inference) As a Pilgrim / Yatra Participant or Yatra Organizer / Operator, I should complete self-service enrollment through Login so that I can manage my participation or publish yatras.

• Trigger/input: the actor opens Login and completes the enrollment form.
• Observable result: an account is established and the actor continues to their role-appropriate working destination.
• Access state: Login is anonymously reachable; protected state remains unavailable until enrollment completes.
• Failure/recovery: invalid enrollment input shows muted inline validation beside the offending field; the actor corrects it and resubmits.
• Continuation: the actor proceeds to My Participation (participant) or Create Yatra / Registrations (organizer).

FR-3 — Returning verification (required_inference) As a Pilgrim / Yatra Participant, Yatra Organizer / Operator, or Platform Administrator, I should verify my identity through Login so that I can resume my own protected work.

• Trigger/input: the actor opens Login and submits verification credentials.
• Observable result: the actor reaches their role-appropriate destination — My Participation, Create Yatra / Registrations, or Admin.
• Access state: Login is anonymously reachable; the protected destination becomes available only after verification succeeds.
• Failure/recovery: unrecognized credentials show a muted line stating verification failed without revealing which field was wrong; the actor retries or switches to enrollment.
• Continuation: the actor resumes their protected work.

FR-4 — Administrator provisioning (required_inference) As a Platform Administrator, I should have my account provisioned before I can reach the Admin oversight workspace, so that oversight access is not self-granted.

• Trigger/input: an administrator account is provisioned outside self-service enrollment.
• Observable result: the administrator can verify through Login and reach Admin.
• Access state: Admin is role-restricted; verification through Login is required.
• Failure/recovery: if verification fails, the administrator retries through Login.
• Continuation: the administrator performs oversight work in Admin.

FR-5 — Role-appropriate authorization (required_inference) As the platform, I should enforce role-appropriate authorization for the organizer and administrator working destinations so that each actor reaches only their own working surface.

• Trigger/input: an actor attempts to reach Create Yatra, Registrations, or Admin.
• Observable result: the actor reaches the destination only when their established role permits it; otherwise access is refused and the actor is directed to Login.
• Access state: role-restricted destinations; established identity required.
• Failure/recovery: a refused actor can verify through Login with an account that holds the required role.
• Continuation: the actor proceeds to their permitted destination.

FR-6 — Participant registration and joining (required_inference) As a Pilgrim / Yatra Participant, I should register for or join a yatra so that I can take part in the journey.

• Trigger/input: the participant selects register or join from Yatra Details or My Participation.
• Observable result: a participation record is created and appears in My Participation with its current status.
• Access state: established identity required; My Participation is role-restricted to the participant.
• Failure/recovery: if registration cannot be completed, a muted line states the failure with a retry action and the participant's selection is preserved.
• Continuation: the participant manages their participation details and follows the journey's itinerary and updates.

FR-7 — Participant management of own participation details (required_inference) As a Pilgrim / Yatra Participant, I should manage my own participation details so that my journey information stays correct through to completion.

• Trigger/input: the participant edits their participation details in My Participation.
• Observable result: the updated details are saved and reflected in the participant's participation record.
• Access state: established identity required; the participant sees only their own participation.
• Failure/recovery: invalid input shows muted inline validation; the participant corrects it and resaves.
• Continuation: the participant continues to follow the journey through to completion.

FR-8 — Organizer creation and publishing of a yatra (required_inference) As a Yatra Organizer / Operator, I should create and publish a yatra's details, itinerary, and schedule so that participants can discover and register for it.

• Trigger/input: the organizer completes the creation form in Create Yatra and publishes.
• Observable result: the yatra is saved and published, and appears in the catalog.
• Access state: established identity required; Create Yatra is role-restricted to the organizer.
• Failure/recovery: validation errors show muted inline messages beside the offending field; a publish failure shows a muted line with a retry action and preserves entered content.
• Continuation: the organizer manages the resulting registrations in Registrations.

FR-9 — Organizer management of registrations (required_inference) As a Yatra Organizer / Operator, I should review and manage the registrations on my yatras so that the yatra is fully subscribed and well run.

• Trigger/input: the organizer opens Registrations.
• Observable result: registrations render as tabular rows with their current status, and status changes are saved.
• Access state: established identity required; Registrations is role-restricted to the organizer.
• Failure/recovery: if registrations cannot be loaded, a muted line states the failure with a retry link.
• Continuation: the organizer communicates journey updates to participants.

FR-10 — Organizer communication of journey updates (required_inference) As a Yatra Organizer / Operator, I should communicate journey updates to participants so that participants are informed at each stage.

• Trigger/input: the organizer composes and sends an update from Registrations.
• Observable result: the update is sent to the participants of the targeted yatra and the send is confirmed.
• Access state: established identity required; Registrations is role-restricted to the organizer.
• Failure/recovery: a failed send shows a muted line with a retry action and preserves the composed message.
• Continuation: the organizer continues managing registrations and sending further updates.

FR-11 — Participant receipt of journey updates (required_inference) As a Pilgrim / Yatra Participant, I should receive the journey updates my organizer sends so that I stay informed at each stage of the yatra.

• Trigger/input: the organizer sends an update for a yatra the participant has registered for or joined.
• Observable result: the update is delivered to the participant and is visible in the context of their participation.
• Access state: established identity required; the participant sees updates for their own participation.
• Failure/recovery: if the participant cannot load their participation, a muted line states the failure with a retry link.
• Continuation: the participant continues to follow the journey through to completion.

FR-12 — Administrator oversight of published yatras (required_inference) As a Platform Administrator, I should oversee published yatras so that the catalog stays healthy and trustworthy.

• Trigger/input: the administrator opens the published-yatra view in Admin.
• Observable result: published yatras render as tabular rows with their publication state.
• Access state: established identity required; Admin is role-restricted to the administrator.
• Failure/recovery: if the view cannot be loaded, a muted line states the failure with a retry link.
• Continuation: the administrator resolves issues that block journeys.

FR-13 — Administrator oversight of organizer accounts (required_inference) As a Platform Administrator, I should oversee organizer accounts so that publishing remains trustworthy.

• Trigger/input: the administrator opens the organizer-account view in Admin.
• Observable result: organizer accounts render as tabular rows.
• Access state: established identity required; Admin is role-restricted to the administrator.
• Failure/recovery: if the view cannot be loaded, a muted line states the failure with a retry link.
• Continuation: the administrator resolves issues that block journeys.

FR-14 — Administrator oversight of participant records (required_inference) As a Platform Administrator, I should oversee participant records so that participation flows keep functioning.

• Trigger/input: the administrator opens the participant-record view in Admin.
• Observable result: participant records render as tabular rows.
• Access state: established identity required; Admin is role-restricted to the administrator.
• Failure/recovery: if the view cannot be loaded, a muted line states the failure with a retry link.
• Continuation: the administrator resolves issues that block journeys.

FR-15 — Administrator issue resolution (required_inference) As a Platform Administrator, I should resolve issues that block journeys so that participants and organizers can complete their work.

• Trigger/input: the administrator acts on a published yatra, organizer account, or participant record from Admin.
• Observable result: the issue is resolved and the affected record reflects the resolution.
• Access state: established identity required; Admin is role-restricted to the administrator.
• Failure/recovery: if the resolution action fails, a muted line states the failure with a retry action.
• Continuation: the administrator returns to oversight of the catalog and records.

FR-16 — Briefs as authoritative scope source (explicit) As the platform, I should follow the project briefs as the authoritative source for the platform's scope and features, so that the delivered platform matches the intended product.

• Trigger/input: scope and feature decisions for the platform.
• Observable result: the platform's scope and features conform to the briefs.
• Access state: not applicable.
• Failure/recovery: where the briefs specify detail not represented in the accepted requirement thread, the briefs govern and the detail is incorporated.
• Continuation: ongoing as the authoritative reference for the platform.

4. User Personas

Pilgrim / Yatra Participant

The traveler for whom the Karma Yatra platform exists. They arrive without an account and browse the catalog anonymously, reading a yatra's details, itinerary, and schedule before deciding whether to commit. Their commitment is spiritual rather than transactional, so the decision is unhurried and the information they need is the written record of the journey — where it goes, when, and for how long.

Their primary goal is to complete a yatra: to select one, register or join it, and follow its itinerary and updates through to the end. Their distinct accepted responsibilities are registering for or joining a yatra, managing their own participation details so their journey information stays correct, and receiving the journey updates their organizer sends. Their relevant inputs and decisions are the yatra they choose from the catalog and the accuracy of their own participation details. They interact with the Yatra Organizer / Operator as the party who publishes the yatra and sends updates, and with the Platform Administrator only indirectly, as the party who keeps the catalog and participation flows functioning. Their observable success is a participation record that reflects their chosen yatra and stays correct through to completion, with the organizer's updates reaching them at each stage.

What makes this role's work different: the participant is the only actor whose work is entirely about their own single journey — they never see another participant's records, never publish, and never oversee the catalog. Their workspace is personal and recurring, and their success is measured by completing the journey rather than by managing anything.

Yatra Organizer / Operator

The party that creates and runs yatras. They come to the platform to publish a journey and then to run it: they author the yatra's details, itinerary, and schedule, and they manage the registrations that follow and the communication that keeps participants informed.

Their primary goal is a fully subscribed, well-run yatra with participants informed at each stage. Their distinct accepted responsibilities are creating and publishing yatra details, itinerary, and schedule; reviewing and managing registrations on their yatras; and composing and sending journey updates to participants. Their relevant inputs and decisions are the yatra content they author, the publication decision, registration status changes, and the content and timing of journey updates. They interact with the Pilgrim / Yatra Participant as the party who registers and receives updates, and with the Platform Administrator as the party who oversees their account and published yatras. Their observable success is a published yatra that appears in the catalog, registrations they can review and manage, and updates confirmed as sent to participants.

What makes this role's work different: the organizer is the only actor who authors product content and the only one who initiates communication to another persona. Their work spans two distinct responsibilities — publishing a yatra once, and running its registrations and communication repeatedly — and their success depends on another persona's response (participants registering and staying informed).

Platform Administrator

The operator of the Karma Yatra platform itself. They do not travel and do not publish; they keep the platform's catalog and participation flows healthy so that the other two personas can do their work.

Their primary goal is a healthy, trustworthy catalog of yatras and functioning participation flows. Their distinct accepted responsibilities are overseeing published yatras, overseeing organizer accounts, overseeing participant records, and resolving issues that block journeys. Their relevant inputs and decisions are the state of published yatras, the standing of organizer accounts, the integrity of participant records, and the resolution action appropriate to a blocking issue. They interact with the Yatra Organizer / Operator through oversight of organizer accounts and published yatras, and with the Pilgrim / Yatra Participant through oversight of participant records. Their observable success is a catalog whose published yatras are trustworthy and participation flows that continue to function.

What makes this role's work different: the administrator is the only actor with a cross-cutting view — they see published yatras, organizer accounts, and participant records together, and their work is corrective rather than creative or participatory. Their account is provisioned rather than self-enrolled, which reflects that oversight access is not self-granted.

5. Core User Flows

Flow 1 — A visitor browses the catalog and reads a yatra (Pilgrim / Yatra Participant)

1. The visitor arrives at Landing anonymously. The page presents the wordmark, one sentence of purpose, a single featured yatra, and a catalog preview as quiet bands separated by full-width rules.
2. The visitor follows the plain underlined text link to browse yatras and reaches Yatras.
3. Yatras renders the catalog as a vertical list of full-width bands, each with the yatra name in large serif on the left and date and duration in muted small caps on the right, separated by hairlines.
4. The visitor selects a yatra and reaches Yatra Details.
5. Yatra Details renders the yatra's details, itinerary, and schedule as aligned label/value rows with hairlines.
6. If the catalog or a yatra cannot be loaded, a muted line states the failure with a retry link; the visitor retries or returns to the catalog.
7. The visitor decides whether to commit. To register or join, they continue to Flow 2; otherwise they return to Yatras and continue browsing.

Flow 2 — A participant enrolls and registers for a yatra (Pilgrim / Yatra Participant)

1. From Yatra Details, the participant selects register or join. Because registration requires established identity, they are directed to Login.
2. Login is anonymously reachable and presents the enrollment form for a first-time visitor.
3. The participant completes the enrollment form and submits it.
4. If enrollment input is invalid, muted inline validation appears beside the offending field; the participant corrects it and resubmits.
5. On successful enrollment, an account is established and the participant continues to My Participation.
6. In My Participation, the participant completes the registration or join for the chosen yatra.
7. The participation record is created and appears in My Participation with its current status. If registration cannot be completed, a muted line states the failure with a retry action and the participant's selection is preserved.
8. The participant continues to Flow 3.

Flow 3 — A participant manages their participation and follows the journey (Pilgrim / Yatra Participant)

1. The participant returns to Login and verifies their identity.
2. If verification fails, a muted line states that verification failed without revealing which field was wrong; the participant retries or switches to enrollment.
3. On successful verification, the participant reaches My Participation, which renders their participation records as tabular rows with label left and value right, hairlines between rows.
4. The participant edits their own participation details and saves them. Invalid input shows muted inline validation; the participant corrects it and resaves.
5. The updated details are saved and reflected in the participant's participation record.
6. The organizer's journey updates arrive and are visible in the context of the participant's participation. If the participant cannot load their participation, a muted line states the failure with a retry link.
7. The participant continues to follow the itinerary and updates through to completion of the yatra.

Flow 4 — An organizer enrolls and publishes a yatra (Yatra Organizer / Operator)

1. The organizer reaches Login and completes self-service enrollment.
2. If enrollment input is invalid, muted inline validation appears beside the offending field; the organizer corrects it and resubmits.
3. On successful enrollment, the organizer continues to Create Yatra.
4. In Create Yatra, the organizer authors the yatra's details, itinerary, and schedule as aligned label/value rows.
5. The organizer publishes the yatra.
6. If a field fails validation, a muted inline message appears beside it; if publishing fails, a muted line states the failure with a retry action and the entered content is preserved. The organizer corrects the field or retries without losing content.
7. On success, the yatra is saved and published and appears in the catalog, where participants can discover it.
8. The organizer continues to Flow 5.

Flow 5 — An organizer manages registrations and informs participants (Yatra Organizer / Operator)

1. The organizer returns to Login and verifies their identity, reaching Registrations.
2. If verification fails, a muted line states that verification failed; the organizer retries.
3. Registrations renders the registrations on the organizer's yatras as tabular rows with label left and value right, hairlines between rows. If none exist yet, a single muted line states that no registrations exist yet.
4. The organizer reviews registrations and manages their status; status changes are saved.
5. If registrations cannot be loaded, a muted line states the failure with a retry link; the organizer retries.
6. The organizer composes a journey update for a yatra and sends it.
7. The update is sent to the participants of that yatra and the send is confirmed. If the send fails, a muted line states the failure with a retry action and the composed message is preserved.
8. The participants receive the update (Flow 3, step 6). The organizer continues managing registrations and sending further updates.

Flow 6 — An administrator oversees the platform (Platform Administrator)

1. The administrator's account is provisioned before they can reach Admin; oversight access is not self-granted.
2. The administrator reaches Login and verifies their identity.
3. If verification fails, a muted line states that verification failed; the administrator retries.
4. On successful verification, the administrator reaches Admin.
5. The administrator reviews published yatras, organizer accounts, and participant records, each rendered as tabular rows with label left and value right, hairlines between rows. If a view is empty, a single muted line states there is nothing to review in that view.
6. If a view cannot be loaded, a muted line states the failure with a retry link; the administrator retries or switches views without losing position.
7. The administrator acts on a published yatra, organizer account, or participant record to resolve an issue that blocks a journey.
8. The issue is resolved and the affected record reflects the resolution. If the resolution action fails, a muted line states the failure with a retry action.
9. The administrator returns to oversight of the catalog and records.

6. Visuals Colors and Theme

The creative direction is authoritative for this section. Muse: Kenya Hara. Headline: Emptiness as the path — Karma Yatra after Kenya Hara. The surface should feel like paper, not a dashboard: vast quiet space, natural materials, one calm object, whispering type.

Colour tokens (light mode, authoritative):

No gradients, no shadows beyond a 1px hairline, no coloured surfaces except one accent block per page at most. Dark mode is not the default surface; if a dark variant exists it must keep the same hairline discipline and the single terracotta accent.

Typography:

• Headings: Cormorant Garamond, Light weight, humanist serif, wide tracking 0.02em, leading 1.15. Sentence case, never all-caps, never bolder than 400. Display sizes clamp(56px, 12vw, 128px) for the hero wordmark; 28px–48px for section headings.
• Body: Zen Kaku Gothic New. Modular scale 1.333: 128 / 96 / 72 / 48 / 32 / 24 / 18 / 16 / 14. Body copy 17px/1.75 on reading surfaces (yatra details, itinerary); 15px/1.6 for UI labels.
• Numerals: old-style in body text, lining in data rows.

Shape language: Square proportions and thin rules. Cards are not rounded — soft-cornered at most 2px, defined by a single 1px hairline in #D9D4C8 rather than a shadow. Section boundaries are full-width horizontal rules, not boxes. Buttons are rectangular with 2px radius, 1px border, and no fill except the primary CTA, which is a solid accent block. Imagery is square or 4:5, never 16:9. No blobs, no pills, no floating layers.

Layout: Centered single-column compositions with abundant margin — 96px gutters at 1280px, 48px at 768px, 24px at 375px. The catalog is a vertical list of yatras, each row a full-width band with the yatra name in large serif on the left, date and duration in muted small caps on the right, and a single hairline beneath. No card grid. Landing is a stack of quiet bands separated by full-width rules: wordmark, one sentence of purpose, a single featured yatra, then the catalog preview. Admin and Registrations use the same centered measure (max 880px) with tabular rows — label left, value right, hairline between — so dense data still breathes. Navigation is a single top rule with the wordmark left and four text links right, no background fill, no sticky chrome until scroll.

Imagery: One still-life photograph per major band: a single object on a plain ground — a walking stick, a folded map, a pair of worn sandals, a temple step in morning light, a hand holding a paper ticket. Shot on paper-white or unbleached beige, soft natural light, no people's faces, no crowds, no stock-photo spirituality. Where photography is unavailable, use a single thin-line diagram (a route line, a calendar grid, a topographic contour) in 1px stone grey. No illustration for its own sake, no icons beyond the minimum needed for wayfinding.

Avoid: any blue or indigo (#0057FF, #2563EB, #6366F1, or neighbours); Inter, Roboto, Arial, Helvetica, Open Sans, Lato, Poppins, or system-ui as heading or body fonts; gradient-blob heroes, mesh gradients, glassmorphism, frosted panels, soft multicolour washes; grids of identical hover-lift cards with drop shadows; rounded pill buttons, large corner radii, floating action buttons; stock photography of crowds, faces, or "spiritual" clichés (lotus flowers, om symbols, sunsets over temples); marquees, tickers, parallax scroll-jacking, and any motion that draws attention to itself. The generic indigo/blue-on-white SaaS template is forbidden for this project.

7. Signature Design Concept

The paper field and the single object.

The Landing hero is a full-viewport paper-white field (#F4F1EA) with a single centred object: a 4:5 still-life photograph of a worn walking stick and a folded paper itinerary on an unbleached cloth, placed slightly below the optical centre, occupying roughly 38% of the viewport height on desktop and 30% on mobile. Above it, set in Cormorant Garamond Light at clamp(56px, 12vw, 128px), the wordmark Karma Yatra spans the measure in sentence case with 0.02em tracking. Beneath the wordmark, a single line of 18px body text in muted grey: "Journeys walked with intention."

There is no button in the hero itself. The first CTA — Browse yatras — sits as a plain text link with a 1px underline, 48px below the image, so the eye travels wordmark → object → path. No gradient, no blob, no floating UI, no centred blue button. The composition is a single vertical axis with generous air on both sides; at 375px the wordmark wraps to two lines and the image sits directly beneath it with 24px gutters.

Below the hero, the page continues as a stack of quiet bands separated by full-width horizontal rules in #D9D4C8 with 96px of air above and below: the purpose sentence, a single featured yatra, then the catalog preview. The catalog itself is a vertical list of full-width bands — large serif yatra name left, muted small-caps date and duration right, a single hairline beneath — never a grid of identical cards, never a hover-lift. A single muted terracotta (#B4552D) accent appears exactly once per page: as the primary CTA fill, the active nav underline, or one emphasised word in a section heading — never as decoration, never as a second accent.

This concept recomposes only accepted content, states, and controls: the wordmark, the purpose line, the featured yatra, the catalog preview, and the link into Yatras. It introduces no new behaviour, page, or destination.

8. Interaction Model & Motion Direction

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

Landing Hero Motion Brief

• Focal subject: the single 4:5 still-life photograph of a worn walking stick and a folded paper itinerary on unbleached cloth, placed slightly below the optical centre on a full-viewport paper-white field.
• Input → transformation → outcome thesis: as the visitor arrives and scrolls, each quiet band fades in slowly and drifts upward 40px, so the page resolves from a single object into the wordmark, the purpose line, the featured yatra, and the catalog preview — the visitor's attention travels wordmark → object → path, and the only interactive motion is a 200ms colour change on link hover (muted → text) with a 1px underline that draws in from the left on nav hover.
• Motion vocabulary: slow fades of 600–800ms on scroll reveal for each band with a 40px upward drift; 200ms colour change on link hover; 1px underline drawing in from the left on nav hover; 400ms crossfade on page transitions. No parallax, no hover lift, no marquees.
• Composed first frame: the paper-white field fills the viewport; the wordmark sits above the optical centre in Cormorant Garamond Light, sentence case, wide tracking; the still-life photograph sits slightly below the optical centre at roughly 38% of viewport height on desktop and 30% on mobile; the single muted-grey purpose line sits beneath the wordmark; the plain underlined Browse yatras link sits 48px below the image. Nothing else is on screen.
• Reduced-motion state: with prefers-reduced-motion, all scroll-reveal fades and drifts are removed and every band renders in its final position immediately; hover colour changes and the nav underline remain as instant state changes without transition; page transitions become immediate. The composed first frame is unchanged, and all readable text and controls remain whole and fully inside the viewport at 375px, 768px, and 1280px.

The restraint is the point: the platform should feel like turning a page, not operating a machine.

9. Non-Functional Requirements

NFR-1 — Durable state (required_inference) The platform must persist yatra, registration, participation, account, and journey-update state durably, so that a participant's participation, an organizer's published yatras and registrations, and an administrator's oversight records survive across sessions. Rationale: the accepted journeys require participants to resume their own participation and organizers to return to their registrations and published yatras.

NFR-2 — Application-owned identity and session continuity (required_inference) The platform must establish and verify application-owned identity through Login, and must bind protected state — participation, published yatras, registrations, and oversight records — to the correct participant. Rationale: the accepted journeys require each actor to privately own and resume durable actor-specific state, and commitments and records must remain bound to the correct participant.

NFR-3 — Role-appropriate authorization (required_inference) The platform must enforce role-appropriate authorization for Create Yatra, Registrations, and Admin, so that only an organizer reaches the organizer workspaces and only an administrator reaches the oversight workspace. Rationale: the accepted planning scope establishes differentiated control over shared product state for these destinations.

NFR-4 — Anonymous access to public surfaces (explicit) Landing, Yatras, Yatra Details, and Login must remain reachable without established identity, and protected state must remain unavailable until identity is established. Rationale: anonymous catalog browsing and yatra detail review before identity establishment are accepted behavior, and a protected destination cannot own the interaction that establishes access to itself.

NFR-5 — Readable text and controls at every viewport (explicit) Headlines, wordmarks, labels, numbers, and card text and controls must stay 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 creative direction asks, as long as they cover no readable text or control. With prefers-reduced-motion, a usable static arrangement must be provided.

NFR-6 — Briefs as authoritative scope source (explicit) The platform's scope and features must follow the project briefs, which are the authoritative source. The briefs' content was not included in the authoritative source text and must be consulted directly.

NFR-7 — Backend integration (required_inference) The platform requires backend integration to persist and serve yatra, registration, participation, account, and journey-update state to the custom UI. Rationale: the accepted journeys depend on durable, actor-bound state that the custom UI reads and writes.

10. Tech Stack

No technology choices were specified in the authoritative user requirement thread or the planning scope. The following are coherent defaults, labelled as such.

• Frontend: React with a single-page application structure serving the eight accepted pages. [Default — not specified by user]
• Backend: Python with FastAPI, providing the API for yatras, registrations, participation, accounts, and journey updates. [Default — not specified by user]
• Storage: A relational database for durable yatra, registration, participation, account, and journey-update state. [Default — not specified by user]
• Packaging and local run: Docker with docker-compose for the frontend, backend, and database services. [Default — not specified by user]
• Deployment: Kubernetes only if deployment requires it; not otherwise. [Default — not specified by user]

Where the project briefs specify technology, the briefs govern and these defaults are replaced.

11. Assumptions and Constraints

Constraints

• C-1 (explicit): The platform's scope and features must follow the project briefs, which are the authoritative source; the briefs' content was not included in the authoritative source text.
• C-2 (explicit): The project name is karma-yatra.
• C-3 (explicit): The creative direction is authoritative for visuals, colour, typography, shape, layout, imagery, and motion; the generic indigo/blue-on-white SaaS template is forbidden.
• C-4 (explicit): Readable text and controls must stay whole and inside the viewport and their container at 375px, 768px, and 1280px; imagery, decoration, and motion may be cropped or bled off an edge as long as they cover no readable text or control.

Assumptions

• A-1 (narrow): The project briefs contain the platform's detailed scope and features and are available to the implementation team as the authoritative reference; this document specifies structure, actors, ownership, and behavior at the level the accepted requirement thread and planning scope establish.
• A-2 (narrow): The closed persona set — Pilgrim / Yatra Participant, Yatra Organizer / Operator, and Platform Administrator — is the complete set of active human actors for the current generation.
• A-3 (narrow): The eight accepted pages — Landing, Yatras, Yatra Details, My Participation, Create Yatra, Registrations, Admin, and Login — are the complete current information architecture.
• A-4 (narrow): Administrator accounts are provisioned outside self-service enrollment; participants and organizers self-enroll through Login.
• A-5 (narrow): Journey updates are delivered to participants within the platform, in the context of their participation; no external messaging channel is assumed.
• A-6 (narrow): No payment processing, messaging or social features, recommendation engine, or third-party booking integration is part of the current scope.

12. Glossary

• Yatra — A pilgrimage journey published on the platform, with details, an itinerary, and a schedule.
• Catalog — The collection of published yatras, presented on Yatras as a hairline-separated vertical list.
• Participation — A participant's record of registering for or joining a yatra, with its own details and status.
• Registration — An organizer's view of the participants signed up for one of their yatras, managed in Registrations.
• Journey update — A message an organizer composes and sends to the participants of a yatra to keep them informed at each stage.
• Enrollment — Self-service establishment of a participant or organizer account through Login.
• Verification — Returning identity confirmation through Login for participants, organizers, and provisioned administrators.
• Provisioning — Establishment of an administrator account outside self-service enrollment, before the administrator can reach Admin.
• Role-appropriate authorization — Enforcement that only an organizer reaches Create Yatra and Registrations, and only an administrator reaches Admin.
• Hairline — A 1px rule in #D9D4C8 used as the only separator and border treatment.
• Accent — The single muted terracotta #B4552D, appearing exactly once per page.