Adds requirements and userstories. also updates diagrams to be mermaid diagrams instead of text variants

2026-06-17 11:31:17 +02:00
parent 73025c5a84
commit c7154e288f
13 changed files with 1018 additions and 163 deletions
@@ -0,0 +1,141 @@
+# Story Generation Plan — CMS Frontend
+
+## Approach
+**Persona-Based + Feature-Based Hybrid**: Stories are organized by persona (who) and grouped under the feature/page they relate to (what). This gives clear ownership per role while keeping related stories together for implementation.
+
+## Planning Checklist
+- [x] User Stories Assessment completed
+- [x] Story approach chosen: Persona-Based + Feature-Based Hybrid
+- [x] Clarification questions generated (see below)
+- [x] Clarification questions answered
+- [x] Stories generated (stories.md)
+- [x] Personas generated (personas.md)
+- [x] Acceptance criteria verified (INVEST-compliant)
+- [x] Personas mapped to stories
+
+---
+
+## Generation Steps
+
+### Step 1: Generate personas.md
+Create `aidlc-docs/features/cms-frontend/inception/user-stories/personas.md` with:
+- [ ] Persona: System Owner
+- [ ] Persona: CMS Administrator
+- [ ] Persona: CMS User
+- [ ] Persona: New Invited User (completing setup)
+- [ ] Persona: Anonymous Visitor (unauthenticated, e.g. invite link recipient)
+
+### Step 2: Generate stories.md
+Create `aidlc-docs/features/cms-frontend/inception/user-stories/stories.md` with stories for:
+
+**Epic: Authentication & Session**
+- [ ] US-01 Login with email and password
+- [ ] US-02 Stay logged in across tab switches (session persistence via refresh token)
+- [ ] US-03 Logout and end session
+- [ ] US-04 Access denied redirect when not authenticated
+- [ ] US-05 Auto token refresh on expiry
+
+**Epic: System Initialization**
+- [ ] US-06 Initialize system as first Owner (setup flow)
+- [ ] US-07 Redirect to setup when system is not initialized
+
+**Epic: Dashboard**
+- [ ] US-08 View dashboard after login
+- [ ] US-09 View system availability status on dashboard
+
+**Epic: User Management**
+- [ ] US-10 View list of users (Owner/Admin)
+- [ ] US-11 Invite a new user by email with role selection (Owner/Admin)
+- [ ] US-12 Share invite link after invitation is created
+- [ ] US-13 Complete account setup via invitation link (New Invited User)
+- [ ] US-14 Handle expired/invalid invitation token gracefully
+
+**Epic: Profile**
+- [ ] US-15 View own profile information
+
+**Epic: System Settings**
+- [ ] US-16 View system availability status in settings (Owner)
+- [ ] US-17 Access denied to System Settings for non-Owners
+
+**Epic: Navigation & Layout**
+- [ ] US-18 See role-appropriate navigation items in sidebar
+- [ ] US-19 Toggle dark/light theme
+
+**Epic: CMS Management (Placeholder)**
+- [ ] US-20 View CMS management placeholder page
+
+### Step 3: Validate INVEST criteria
+- [ ] Each story is Independent (can be implemented standalone)
+- [ ] Each story is Negotiable (not a contract)
+- [ ] Each story is Valuable (delivers user benefit)
+- [ ] Each story is Estimable (dev can size it)
+- [ ] Each story is Small (fits in one sprint iteration)
+- [ ] Each story is Testable (acceptance criteria are verifiable)
+
+### Step 4: Map personas to stories
+- [ ] Add persona references to each story in stories.md
+
+---
+
+## Clarification Questions
+
+Please answer the following questions to improve story quality.
+
+---
+
+### Question 1: Story format preference
+Which format should be used for user stories?
+
+A) Standard narrative: "As a [persona], I want to [action], so that [benefit]"
+B) Job-story format: "When [situation], I want to [motivation], so I can [outcome]"
+C) Other (please describe after [Answer]: tag below)
+
+[Answer]: A
+
+---
+
+### Question 2: Acceptance criteria format
+How detailed should acceptance criteria be?
+
+A) Concise bullet points (3–5 bullets per story, focus on happy path + key error states)
+B) Gherkin-style (Given/When/Then scenarios for each story)
+C) Detailed checklist covering happy path, error states, edge cases, and security constraints
+X) Other (please describe after [Answer]: tag below)
+
+[Answer]: C
+
+---
+
+### Question 3: Story granularity for auth flows
+The authentication flow has several sub-steps (login, token refresh, logout, 401 handling). Should these be:
+
+A) Separate stories — one story per interaction type (login, refresh, logout, redirect)
+B) One story per user goal — login is one story, "stay logged in" is one story, logout is one story
+C) A single epic story with sub-tasks broken out in acceptance criteria
+X) Other (please describe after [Answer]: tag below)
+
+[Answer]: A
+
+---
+
+### Question 4: Role names in stories
+How should roles be referred to in story personas?
+
+A) Use technical role names from the backend: Owner, Admin, User
+B) Use business-friendly names: System Owner, CMS Administrator, CMS User
+C) Use both — technical name + friendly alias (e.g. "Owner (System Owner)")
+X) Other (please describe after [Answer]: tag below)
+
+[Answer]: A
+
+---
+
+### Question 5: Out-of-scope stories
+Should the stories document include placeholder/future stories for features that are explicitly out of scope in v1 (e.g. profile editing, availability status management, CMS content)?
+
+A) Yes — include them as clearly marked "Future / Out of Scope" stories
+B) No — only include stories that are in scope for v1
+C) Include brief notes only (no full story format) for future features
+X) Other (please describe after [Answer]: tag below)
+
+[Answer]: C
@@ -0,0 +1,30 @@
+# User Stories Assessment
+
+## Request Analysis
+- **Original Request**: Build a React-based CMS admin frontend with Login, Dashboard, User Management, Profile, System Settings, and CMS placeholder pages
+- **User Impact**: Direct — this is an entirely user-facing application; every requirement is about what users see and do
+- **Complexity Level**: Moderate — multiple pages, multiple user roles (Owner, Admin, User), distinct user workflows
+- **Stakeholders**: CMS administrators (Owners, Admins), regular CMS users
+
+## Assessment Criteria Met
+- [x] High Priority: New user-facing features — entire frontend is new user interaction surface
+- [x] High Priority: Multi-persona system — three distinct roles (Owner, Admin, User) with different access levels
+- [x] High Priority: Complex business requirements — auth flows, invitation flows, role-based navigation, setup initialization
+- [x] High Priority: New product capabilities — no existing frontend; this is the first admin interface
+- [x] Benefits: Stories clarify per-role behavior; acceptance criteria define testable boundaries for each feature
+
+## Decision
+**Execute User Stories**: Yes
+
+**Reasoning**: The CMS frontend is a multi-persona, multi-page user-facing application with distinct workflows per role. User stories will:
+1. Make explicit what each role can and cannot do on each page
+2. Provide testable acceptance criteria for each interaction
+3. Clarify the invitation and setup flows which have multiple states (valid/expired/used tokens)
+4. Define the role-based navigation and access control expectations clearly
+5. Serve as a specification for future development phases (CMS content modules, profile editing)
+
+## Expected Outcomes
+- Clear per-persona stories covering login, dashboard, user management, invitation flow, profile, and settings
+- Explicit acceptance criteria for edge cases (expired invitations, unauthorized access, system not initialized)
+- Role-based stories that define Owner vs Admin vs User capabilities without ambiguity
+- Reusable baseline for future feature extension