---
stepsCompleted:
  - step-01-init.md
  - step-02-discovery.md
  - step-03-success.md
  - step-04-journeys.md
  - step-05-domain.md
  - step-06-innovation.md
  - step-07-project-type.md
  - step-08-scoping.md
  - step-09-functional.md
  - step-10-nonfunctional.md
  - step-11-polish.md
classification:
  projectType: web_app
  domain: edtech
  complexity: medium
  projectContext: greenfield
inputDocuments:
  - file:///home/maximilienmao/Projects/Test01/_bmad-output/planning-artifacts/product-brief-Test01-2026-01-20.md
  - file:///home/maximilienmao/Projects/Test01/_bmad-output/planning-artifacts/ux_brainstorm_notes.md
  - file:///home/maximilienmao/Projects/Test01/_bmad-output/planning-artifacts/ux-design-specification.md
  - file:///home/maximilienmao/Projects/Test01/_bmad-output/analysis/brainstorming-session-2026-01-20.md
workflowType: 'prd'
lastEdited: '2026-01-21'
editHistory:
  - date: '2026-01-21'
    changes: 'Polished flow, consolidated Scope sections, removed duplicate Risk Mitigation.'
  - date: '2026-01-23'
    changes: 'Added "Bring Your Own AI" (BYOD) Support: Custom Providers, API Key Management, and Settings.'
---

# Product Requirements Document - Brachnha

**Author:** Max
**Date:** 2026-01-20

## Executive Summary

**Product Vision:** "Brachnha" (The Pocket Mentor) is a Progressive Web App (PWA) designed to transform the daily struggles of learning into a polished "Journey Log" of insights. It targets bootcamp graduates and self-learners who need to document their growth for recruiters but lack the energy to write from scratch.

**Core Innovation:** Unlike passive note apps or raw AI writers, Brachnha uses a **Dual-Agent Pipeline** ("Teacher" + "Ghostwriter"). It actively interviews the user to extract the "Lesson" from the "Complaint" ("Venting"), then synthesizing it into high-quality personal branding content.

**Key Value:** Turns "I feel stupid today" into "Here is what I learned today."

**Technical Differentiator:** **"Bring Your Own AI" (BYOD) Architecture.** Users provide their own API keys (OpenAI, DeepSeek, etc.) for maximum privacy and vendor independence. No middle-man server.

## Success Criteria

### User Success
*   **Consistency:** >1 post/week.
*   **Efficiency:** < 3 mins from open to draft.
*   **Quality:** < 10% manual edits required.

### Business Success
*   **Engagement:** 1.5x lift vs manual posts.
*   **Retention:** > 50% week-over-week retention.

### Technical Success
*   **Hallucination rate:** < 1%.
*   **Generation latency:** < 5s.

### Measurable Outcomes
*   Active users generate >1 post/week.
*   Generated posts achieve 1.5x higher engagement than previous manual posts.

## Product Scope & Phased Development

### MVP Strategy & Philosophy

**MVP Approach:** "Experience MVP"
The goal is to prove that the *experience* of "guided enlightenment" is cleaner, faster, and more valuable than just using ChatGPT directly. We are optimizing for the "Aha!" moment and the feeling of relief/pride.

**Resource Requirements:** 1 Full-Stack Developer (You).

### MVP Feature Set (Phase 1)

**Core User Journeys Supported:**
*   Journey 1: The "Legacy Log" (Success Path).
*   Journey 2: The "Struggle into Strength" (Refinement).

**Must-Have Capabilities:**
*   **Chat Interface:** Mobile-first, WhatsApp-style interaction.
*   **Offline PWA:** "Venting" on the commute without signal.
*   **Dual-Agent Pipeline:** "Teacher" (Elicitation) for input + "Ghostwriter" (Generation) for legacy-focused output.
*   **Draft View:** "Slide-Up" split view for reviewing the generated post.
*   **Simple Export:** One-click copy to clipboard.
*   **Local History:** Persistence of past chats/drafts on the device.
*   **AI Provider Settings:** Configure custom OpenAI-compatible endpoints (Base URL, API Key, Model Name).
*   **Multi-Provider Toggle:** Switch between providers (e.g., OpenAI vs. DeepSeek) instantly.

### Post-MVP Features

**Phase 2: Growth (The "Public Profile")**
*   **Focus:** Building evidence for recruiters.
*   **Features:**
    *   User Accounts / Cloud Sync across devices.
    *   Public "Learning Timeline" (read-only link for recruiters).
    *   Basic gamification (Streaks/Consistency tracking).
    *   "My Tone" settings and custom preferences.

**Phase 3: Expansion (The "Ecosystem")**
*   **Focus:** Scale and automated distribution.
*   **Features:**
    *   Direct LinkedIn/Medium API Integration.
    *   Voice Input (Speech-to-Text) for easier venting.
    *   "Series" management (grouping posts into articles).
    *   Multi-Platform support (Dev.to, Twitter threads).

### Risk Mitigation Strategy

**Technical Risks:**
*   **Risk:** PWA Offline Sync complexity.
*   **Mitigation:** Start with a "Local-First" architecture (store everything in persistent client-side storage first, sync later).

**Market Risks:**
*   **Risk:** Users find the "Teacher" questions annoying/blocking.
*   **Mitigation:** Implement a "Fast Track" / "Just Write It" button in the UI to skip the interview if the user is ready.

**Security Risks:**
*   **Risk:** Public deployment on VPS exposes personal journal.
*   **Mitigation:** Implement "Gatekeeper" Authentication (NFR-09) to lock the app via `APP_PASSWORD`.

**Usability Risks:**
*   **Risk:** "Bring Your Own AI" configuration is too complex for non-technical users.
*   **Mitigation:** Provide clear, step-by-step guides for getting API keys. Pre-fill common provider templates (DeepSeek, OpenAI) so users only paste the key.

## User Journeys

### Visual Journey Map: The "Vent into Insight" Loop

```mermaid
sequenceDiagram
    participant User as Alex (Learner)
    participant UI as Brachnha App
    participant Teacher as Teacher Agent
    participant Ghost as Ghostwriter Agent

    User->>UI: Opens app after struggle
    User->>UI: Type: "I spent 4 hours on a typo. I feel stupid."
    UI->>Teacher: Route: Venting Detected
    Teacher-->>UI: "That sounds frustrating. What system can you build to catch this earlier next time?"
    UI->>User: Displays Teacher Probe

    User->>UI: "I need a better checklist for checking variable names."
    UI->>Teacher: Input: Insight Articulated
    Teacher->>Ghost: Handover: Structured Insight

    Ghost-->>UI: Drafts: "My 4-Hour Typo: A Checklist for Better Debugging"
    UI->>User: Displays Polished Content
    User->>UI: One-Click Copy
```


### Journey 1: The "Legacy Log" (Primary Success)
*   **User:** Alex (The Exhausted Learner).
*   **Scene:** Alex finishes a deep study session at 11 PM. He's tired but feels a "click" of understanding after hours of struggle.
*   **Action:** Opens Brachnha to capture the win, not just to vent, but to immortalize the lesson: *"I finally get why dependency injection matters."*
*   **System Response:** The "Teacher" agent validates the insight and probes deeper: *"That's a huge breakthrough. What was the 'before' and 'after' mental model in your head?"*
*   **Transformation:** Alex articulates the specific shift in his thinking.
*   **Result:** The "Ghostwriter" agent drafts: *"The Moment Dependency Injection Clicked for Me."*
*   **Outcome:** Alex feels he has preserved his growth. He posts it, feeling like he is leaving a legacy for other learners behind him, rather than just complaining.

### Journey 2: The "Struggle into Strength" (Refinement)
*   **User:** Alex (The Exhausted Learner).
*   **Scene:** Alex has struggled all day with a typo. He feels stupid, not enlightened.
*   **Action:** He uses the app to analyze the failure: *"I spent 4 hours on a typo. I need to remember how to debug this better next time."*
*   **System Response:** The "Teacher" focuses on the process: *"What is the checklist or system you can build to prevent that next time?"*
*   **Result:** The "Ghostwriter" drafts: *"My 4-Hour Typo: A Checklist for Better Debugging."*
*   **Outcome:** The app helps frame a "failure" as a "lesson learned," turning a negative day into a positive artifact.

### Journey 3: The Recruiter (The Evidence)
*   **User:** Sarah (The Hiring Manager).
*   **Scene:** Sarah is scrolling LinkedIn, ignoring generic "Top 10 Python Tips" posts.
*   **Action:** She sees Alex's post about his debugging struggle and his new checklist.
*   **Perception:** She sees a candidate who is self-aware, resilient, and honest about the learning process. She sees a timeline of consistent "lightbulb moments" on his profile.
*   **Result:** She reaches out, valuing his ability to articulate his growth and problem-solving process.

### Journey 4: The Power User (Configuration)
*   **User:** Max (Admin/You).
*   **Scene:** Max wants to use the new DeepSeek model because it's cheaper and better at coding tasks.
*   **Action:** Goes to Settings -> AI Provider. Selects "DeepSeek" template. Pastes his API Key. Sets Model to `deepseek-coder`.
*   **Outcome:** The app immediately starts using the new provider for the next chat session. Verify "Input -> Output" quality in the logs.

### Journey Requirements Summary
*   **Cognitive Support:** The system must actively help the user *synthesize* information (the "Teacher" role), not just record it.
*   **Reframing Capability:** The "Teacher" prompt needs to be skilled at finding the "Lesson" inside a "Complaint."
*   **Legacy Formatting:** The output style must feel timeless and valuable (Enlightenment), not just fleeting (Venting).
*   **Dual-Agent State:** The system needs distinct "Teacher Mode" (Questioning) and "Ghostwriter Mode" (Declarative) states.

## Domain-Specific Requirements

### Compliance & Regulatory
*   **Data Privacy (Adult Learners):** Strict control over private "Venting" logs. Chats are "Private by Default" and never shared. Only explicit "Ghostwriter" drafts are exportable.
*   **Content Moderation (Reputation Safety):** The system must include guardrails to prevent generating toxic, offensive, or professionally damaging content.

### Technical Constraints
*   **Tone Safety:** The AI agents must be prompted to maintain a "Professional yet Authentic" tone. Avoiding slang or casual language that could negatively impact a job application.
*   **Hallucination Prevention:** Strict prompt engineering to ensure the AI does not invent libraries, error codes, or successful outcomes that didn't happen. The "Enlightenment" must be grounded in the user's actual input.

### Accessibility
*   **WCAG 2.1 AA:** Standard web accessibility compliance.
*   **Visual Comfort:** High contrast and "calm" color palette suitable for tired eyes (late-night study sessions).

### Educational Framework Alignment
*   **Bloom's Taxonomy Application:** The app moves users from "Remembering" (recall of the event) to "Understanding" (Teacher analysis) and finally "Creating" (Ghostwriter artifact), effectively scaffolding the learning process.

## Innovation & Novel Patterns

### Detected Innovation Areas
*   **Elicitation-First Pipeline:** The core innovation is inserting an active "Teacher" agent before the "Ghostwriter" agent. This solves the "Garbage In, Garbage Out" problem of AI writing by forcing the user to articulate their insight *before* generation.
*   **Guided Transformation:** The UX pattern of transforming a raw, negative "Complaint" into a structured, positive "Insight" via a conversational interview is a novel interaction model for note-taking apps.

### Market Context & Competitive Landscape
*   **vs. Passive Note Apps (Notion/Obsidian):** These require the user to do all the cognitive heaving lifting (synthesis). Brachnha is "Active" and pulls the synthesis out of the user.
*   **vs. Raw AI Writers (ChatGPT):** ChatGPT requires specific prompting and intent. Brachnha acts as a partner that helps the user discover their intent ("What did I actually learn?").
*   **vs. Social Schedulers (Buffer/Hootsuite):** These manage distribution. Brachnha manages *Creation* and *Ideation*.

### Validation Approach
*   **The "Edit Distance" Metric:** Success is measured by how little the user has to edit the final draft. If the "Teacher" interview is effective, the "Ghostwriter" draft should be >90% ready. High edit rates indicate a failure in the elicitation phase.

## Web App Specific Requirements

### Project-Type Overview
Brachnha is a **Progressive Web App (PWA)**. It must deliver a native-app-like experience in the browser, specifically designed for mobile usage during "in-between moments" (commuting, breaks).

### Technical Architecture Considerations
*   **PWA Mechanics:**
    *   **Offline Mode:** Critical. Must use `service-workers` to cache the chat interface (logic and recent history) so the user can "vent" even without a signal (e.g., subway). Sync occurs upon reconnection.
    *   **Installability:** Must serve a valid `manifest.json` to enable "Add to Home Screen" on iOS and Android.

*   **Browser Support Matrix:**
    *   **Tier 1 (Primary):** Mobile Safari (iOS), Chrome for Android.
    *   **Tier 2 (Secondary):** Desktop Chrome/Edge (for reviewing drafts).
    *   **Tier 3 (Touch):** Firefox Mobile.

### Implementation Considerations
*   **Responsive Design Targets:**
    *   **Mobile First:** Design and build for 375px width (iPhone SE) up to 430px (Pro Max) as the primary viewport.
    *   **Desktop:** Constrained "Center Container" layout (max-width 600px) to preserve the chat app feel on large screens.

*   **SEO Strategy:**
    *   **Public Marketing:** The landing page requires standard SEO (meta tags, fast Load, semantic HTML) to attract users.
    *   **Private Application:** The app routes (e.g., `/chat`, `/drafts`) must be explicitly excluded from indexing (`noindex`).

## Functional Requirements

### Dual-Agent Pipeline (Core Innovation)
*   **FR-01:** System can detect "Venting" vs. "Insight" intent from initial user input.
*   **FR-02:** "Teacher Agent" can generate probing questions to elicit specific missing details based on the user's initial input.
*   **FR-03:** "Ghostwriter Agent" can transform the structured interview data into a grammatically correct and structured "Enlightenment" artifact (e.g., Markdown post).
*   **FR-04:** Users can "Regenerate" the outcome with specific critique (e.g., "Make it less corporate", "Focus more on the technical solution").
*   **FR-05:** System provides a "Fast Track" option to bypass the interview and go straight to generation for advanced users.

### Content Management
*   **FR-06:** Users can view a chronological feed of past "Enlightenments" (history).
*   **FR-07:** Users can "One-Click Copy" the formatted text to clipboard.
*   **FR-08:** Users can delete past entries.
*   **FR-09:** Users can edit the generated draft manually before exporting.

### PWA & Offline Capabilities
*   **FR-10:** Users can access the app and view history while offline.
*   **FR-11:** Users can complete a full "Venting Session" offline; system queues generation for reconnection.
*   **FR-12:** System actively prompts users to "Add to Home Screen" (A2HS) upon meeting engagement criteria.

### Data & Privacy
*   **FR-13:** System stores all chat history locally (persistent client-side storage) by default.
*   **FR-14:** Users can export their entire history as a JSON/Markdown file.

### AI Configuration & Settings (BYOD)
*   **FR-15:** Users can configure a custom OpenAI-compatible Base URL (e.g., `https://api.deepseek.com/v1`).
*   **FR-16:** Users can securely save API Credentials (stored in local storage, never transmitted to backend).
*   **FR-17:** Users can specify the Model Name (e.g., `gpt-4o`, `deepseek-chat`).
*   **FR-18:** System validates the connection to the custom provider upon saving.
*   **FR-19:** Users can switch between configured providers globally.

### Security & Access Control
*   **FR-20 (Gatekeeper):** System presents a lock screen upon initial load if not authenticated.
*   **FR-21:** System validates user-entered password against server-side `APP_PASSWORD`.
*   **FR-22:** Authenticated session persists (via secure cookie) to prevent frequent logouts on personal devices.

## Non-Functional Requirements

### Performance & Responsiveness
*   **NFR-01 (Chat Latency):** The "Teacher" agent must generate the first follow-up question within **< 3 seconds** to maintain conversational flow.
*   **NFR-02 (App Load Time):** The app must be interactive (Time to Interactive) in **< 1.5 seconds** on 4G networks.

### Privacy & Security
*   **NFR-03 (Data Sovereignty):** User chat logs AND API Keys are stored **100% Client-Side** (persistent client-side storage). No user content or keys are sent to any middle-man server.
*   **NFR-04 (Inference Privacy):** Data sent to the user-configured LLM API must be stateless (not used for training, subject to provider terms).
*   **NFR-08 (Secure Key Storage):** API Keys must be encrypted at rest or stored in secure local storage capabilities where possible, and never included in exports/logs.

### Reliability & Offline
*   **NFR-05 (Offline Behavior):** The app shell and local history must remain accessible in Aeroplane Mode. **Note:** Active Chat interactions will be unavailable offline as they require live LLM access.
*   **NFR-06 (Data Persistence):** Drafts must be auto-saved locally every **2 seconds** to prevent data loss.
*   **NFR-09 (Gatekeeper Security):** The app must restrict access to the UI via a simple, high-protection login screen backed by a server-side `APP_PASSWORD` environment variable. This protects personal deployments (VPS) from unauthorized public access.

### Accessibility
*   **NFR-07 (Visual Accessibility):** Dark Mode is the default. Contrast ratios must meet **WCAG AA** standards to reduce eye strain for late-night users.
