plan

Implementation Plan: Brain Knowledge Base (BKB)

Epic: TP-XXXX-BKB | Initiative: TP-2141-Work-Management Spec: spec.md | Design: design-spec.md Created: 2025-11-29 | Status: Draft Depends On: MDE (Markdown Documentation Editor) - must be completed first

---

Summary

Create a GitBook-style documentation browser for the .claude/BRAIN/ knowledge base. Features a three-column layout with collapsible folder tree (left), rendered markdown content (center), and table of contents with feedback widget (right). Reuses MDE editor components for editing. Builds on existing DocumentationService patterns.

---

Technical Context

Aspect	Value
Backend	Laravel 12, PHP 8.4
Frontend	Vue 3 (Composition API), Inertia.js v2, TypeScript
Styling	Tailwind CSS v3, Reka UI
Editor	MDE components (CodeMirror 6) - reused from MDE feature
Storage	Filesystem (.claude/BRAIN/ directory) + MySQL (feedback)
Testing	Pest (PHP), Vitest (JS), Playwright (E2E)
Target Platform	Web (Desktop primary, tablet/mobile secondary)

Dependencies

Dependency	Type	Status
MDE (Markdown Documentation Editor)	Feature	Required - provides editor components
DocumentationService	Existing	Extend for Brain directory
MarkdownParserService	Existing	Reuse for content parsing
useTableOfContents	Existing	Reuse for TOC navigation
Reka UI Tree component	New	Install or build tree widget

Constraints

• Performance: Tree loads <2s, doc navigation <200ms, search <500ms
• Scale: Support ~500 documents, 5 levels of nesting
• Accessibility: WCAG AA compliant, keyboard navigable, screen reader support
• Responsive: Desktop primary (1024px+), tablet/mobile as secondary

---

Constitution Check

Project constitution is a template placeholder. Applying standard Laravel/Vue best practices.

• Domain-Driven Design: Create new domain/Brain/ domain
• Inertia.js Patterns: Use shared page component architecture
• TypeScript: All new Vue components in TypeScript
• Pest Testing: Feature tests for all operations
• Tailwind/Reka UI: Use existing design system components
• Phase 2 Extensibility: Components accept rootPath prop for future tabs

---

Project Structure

Documentation (this feature)

.claude/INITIATIVES/TP-2141-Work-Management/TP-XXXX-BKB-Brain-Knowledge-Base/
├── spec.md              # Feature specification
├── design-spec.md       # UI/UX decisions (comprehensive)
├── plan.md              # This file
├── tasks.md             # Generated by /speckit.tasks
├── mockups/             # ASCII mockups
└── checklists/          # Quality checklists

Source Code Changes

domain/Brain/
├── Http/
│   ├── Controllers/
│   │   ├── BrainController.php               # NEW: Page controller
│   │   └── BrainApiController.php            # NEW: API endpoints
│   └── Requests/
│       ├── StoreBrainDocumentRequest.php     # NEW
│       ├── UpdateBrainDocumentRequest.php    # NEW
│       ├── StoreBrainFolderRequest.php       # NEW
│       └── StoreFeedbackRequest.php          # NEW
├── Services/
│   ├── BrainService.php                      # NEW: Tree + document operations
│   └── BrainFeedbackService.php              # NEW: Feedback CRUD
├── Models/
│   └── DocumentFeedback.php                  # NEW: Eloquent model
├── Data/
│   ├── BrainTreeData.php                     # NEW: Tree structure DTO
│   ├── BrainDocumentData.php                 # NEW: Document DTO
│   └── BrainFolderData.php                   # NEW: Folder DTO
└── Routes/
    └── brainRoutes.php                       # NEW: All routes

resources/js/
├── Components/
│   └── Brain/
│       ├── Layout/
│       │   ├── BrainLayout.vue               # NEW: Three-column layout
│       │   └── BrainSidebar.vue              # NEW: Left sidebar wrapper
│       ├── Tree/
│       │   ├── TreeSidebar.vue               # NEW: Tree container + search
│       │   ├── TreeNode.vue                  # NEW: Recursive tree node
│       │   ├── TreeSectionHeader.vue         # NEW: Section header styling
│       │   └── TreeActions.vue               # NEW: New doc/folder buttons
│       ├── Content/
│       │   ├── ContentPanel.vue              # NEW: Document viewer
│       │   ├── ContentHeader.vue             # NEW: Breadcrumb + actions
│       │   └── ContentSkeleton.vue           # NEW: Loading state
│       ├── Toc/
│       │   ├── TocPanel.vue                  # NEW: TOC container
│       │   └── TocItem.vue                   # NEW: TOC entry with scroll spy
│       ├── Feedback/
│       │   ├── FeedbackWidget.vue            # NEW: Emoji rating
│       │   └── FeedbackComment.vue           # NEW: Optional comment
│       ├── Search/
│       │   ├── SearchInput.vue               # NEW: Search field
│       │   └── SearchResults.vue             # NEW: Results dropdown
│       ├── Modals/
│       │   ├── NewDocumentModal.vue          # NEW: Create document
│       │   ├── NewFolderModal.vue            # NEW: Create folder
│       │   ├── DeleteModal.vue               # NEW: Delete confirmation
│       │   └── RenameModal.vue               # NEW: Rename folder
│       └── ContextMenu/
│           └── TreeContextMenu.vue           # NEW: Right-click menu
├── Pages/
│   └── Brain/
│       └── Index.vue                         # NEW: Main brain page
├── composables/
│   ├── useTreeState.ts                       # NEW: Tree expansion state
│   ├── useBrainSearch.ts                     # NEW: Client-side search
│   ├── useTocScrollSpy.ts                    # NEW: TOC scroll tracking
│   └── useFeedback.ts                        # NEW: Feedback submission
└── types/
    └── brain.d.ts                            # NEW: TypeScript interfaces

database/migrations/
└── xxxx_create_document_feedback_table.php   # NEW

tests/
├── Feature/
│   └── Brain/
│       ├── BrainNavigationTest.php           # NEW
│       ├── BrainDocumentCrudTest.php         # NEW
│       ├── BrainFolderCrudTest.php           # NEW
│       ├── BrainSearchTest.php               # NEW
│       └── BrainFeedbackTest.php             # NEW
└── Unit/
    └── Brain/
        └── BrainServiceTest.php              # NEW

---

Design Decisions

1. Data Model

Filesystem Structure (read from .claude/BRAIN/):

.claude/BRAIN/
├── index.md                    # Welcome document
├── 1. OVERVIEW/
│   ├── About.md
│   └── Getting-Started.md
├── 2. Strategy/
│   ├── Goals.md
│   └── Roadmap.md
└── 3. FEATURES/
    └── ...

Tree Node Structure (computed from filesystem):

interface BrainTreeNode {
  id: string;           // Path-based ID: "overview/getting-started"
  name: string;         // Display name: "Getting Started"
  type: 'folder' | 'document' | 'section-header';
  path: string;         // Full path: ".claude/BRAIN/1. OVERVIEW/Getting-Started.md"
  children?: BrainTreeNode[];
  isExpanded?: boolean;
}

Database Schema (new table for feedback):

CREATE TABLE document_feedback (
    id BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
    document_path VARCHAR(500) NOT NULL,
    user_id BIGINT UNSIGNED NOT NULL,
    rating ENUM('positive', 'neutral', 'negative') NOT NULL,
    comment TEXT NULL,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,

    UNIQUE KEY unique_user_document (user_id, document_path),
    FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE,
    INDEX idx_document_path (document_path),
    INDEX idx_rating (rating)
);

2. API Contracts

Method	Endpoint	Purpose	Request/Response
GET	/brain	Load page with tree	Inertia page
GET	/brain/{path}	Load specific document	Inertia page
GET	/api/brain/tree	Get folder tree	{ tree: BrainTreeNode[] }
GET	/api/brain/document/{path}	Get document content	{ content, headings }
POST	/api/brain/document	Create document	{ folder, title }
PUT	/api/brain/document/{path}	Update document	{ content }
DELETE	/api/brain/document/{path}	Delete document	-
POST	/api/brain/folder	Create folder	{ parent, name, isSection }
PUT	/api/brain/folder/{path}	Rename folder	{ name }
DELETE	/api/brain/folder/{path}	Delete folder	-
GET	/api/brain/search?q={term}	Search documents	{ results: SearchResult[] }
POST	/api/brain/feedback	Submit feedback	{ path, rating, comment? }
GET	/api/brain/feedback/{path}	Get user’s feedback	{ rating, comment }

Section Header Detection:

• Folders starting with number + dot (e.g., “1. OVERVIEW”) render as section headers
• Regex: /^\d+\.\s+/

3. UI Components

Component	Purpose	MDE Reuse
BrainLayout.vue	Three-column container	Similar to DocumentationShowLayout
TreeSidebar.vue	Left sidebar with tree	NEW
TreeNode.vue	Recursive tree rendering	NEW (use Reka Collapsible)
ContentPanel.vue	Document viewer	Reuse markdown rendering from MDE
TocPanel.vue	Right sidebar TOC	Reuse useTableOfContents
FeedbackWidget.vue	Emoji rating	NEW
SearchInput.vue	Search field + dropdown	NEW
MarkdownEditor.vue	Edit mode	FULL REUSE from MDE
Modals	Create/Delete/Rename	Similar patterns to MDE

4. State Management

State	Storage	Scope
Tree structure	Inertia props (SSR)	Page load
Expansion state	Session storage	Per-session
Selected document	URL path	Shareable
Document content	Inertia props	Per-navigation
Search query	Component ref	Search session
Feedback state	Component ref + DB	Per-user

Session Storage Key:

brain:expandedNodes: ["overview", "overview/getting-started"]

---

Implementation Phases

Phase 1: Foundation (Backend + Layout)

Goal: Basic page structure with tree data loading

1. Create domain/Brain/ structure
2. Create BrainService.php with tree scanning
3. Create BrainController.php with index route
4. Create migration for document_feedback table
5. Create BrainLayout.vue (three-column skeleton)
6. Create TreeSidebar.vue with static tree
7. Wire up route: /brain

Exit Criteria: Navigate to /brain, see three-column layout with tree structure

Phase 2: Tree Navigation (P1 - Core)

Goal: Interactive tree with document selection

1. Create TreeNode.vue with expand/collapse
2. Create TreeSectionHeader.vue styling
3. Implement useTreeState.ts composable
4. Add keyboard navigation (arrows, enter)
5. Persist expansion state to session storage
6. Navigate to document on click
7. Highlight selected document in tree

Exit Criteria: Can browse tree, click documents, tree state persists

Phase 3: Content Viewing (P1 - Core)

Goal: Display markdown content with TOC

1. Create ContentPanel.vue with markdown rendering
2. Create ContentHeader.vue with breadcrumb
3. Create TocPanel.vue with heading extraction
4. Implement useTocScrollSpy.ts for active heading
5. Smooth scroll on TOC click
6. Default welcome document on load
7. Loading skeletons

Exit Criteria: View documents, TOC navigation works, scroll spy highlights

Phase 4: Search (P3)

Goal: Find documents by search

1. Create SearchInput.vue with debounced input
2. Create SearchResults.vue dropdown
3. Implement useBrainSearch.ts (client-side filtering)
4. Search titles and content
5. Navigate to document on result click
6. Expand tree to show result location

Exit Criteria: Search finds documents, click navigates and expands tree

Phase 5: Editing (P2 - Reuse MDE)

Goal: Edit documents using MDE components

1. Add “Edit” button to ContentHeader.vue
2. Integrate MarkdownEditor.vue from MDE
3. Create Brain-specific API endpoints for save
4. Handle save/cancel flow
5. Reuse concurrent edit detection from MDE

Exit Criteria: Can edit and save Brain documents

Phase 6: Document Creation (P2)

Goal: Create new documents

1. Create NewDocumentModal.vue
2. Create TreeActions.vue (New Document button)
3. API endpoint for document creation
4. Filename generation (slugify)
5. Open editor after creation
6. Add document to tree

Exit Criteria: Can create new document in any folder

Phase 7: Folder Management (P3)

Goal: CRUD operations for folders

1. Create NewFolderModal.vue
2. Create RenameModal.vue
3. Create TreeContextMenu.vue (right-click)
4. API endpoints for folder CRUD
5. Section header checkbox for new folders
6. Delete confirmation with content warning

Exit Criteria: Can create, rename, delete folders

Phase 8: Feedback Widget (P3)

Goal: Document helpfulness ratings

1. Create FeedbackWidget.vue with emoji buttons
2. Create FeedbackComment.vue (optional comment)
3. Create BrainFeedbackService.php
4. API endpoints for feedback submission
5. Show existing feedback on return visit
6. Allow feedback update

Exit Criteria: Can rate documents, feedback persists

Phase 9: Polish & Testing

Goal: Edge cases, accessibility, performance

1. Keyboard shortcuts (/, Ctrl+K, Ctrl+E)
2. Deep nesting handling (>5 levels)
3. Large document handling (>100KB)
4. Responsive adaptations (tablet/mobile)
5. ARIA attributes for screen readers
6. Dark mode verification
7. Playwright E2E tests
8. Performance profiling

Exit Criteria: All edge cases handled, tests pass, accessible

---

Risk Assessment

Risk	Likelihood	Impact	Mitigation
MDE not ready	Medium	High	BKB can ship view-only first; editing added when MDE complete
Tree performance with 500+ docs	Low	Medium	Virtualize with vue-virtual-scroller if needed
Deep nesting UI issues	Low	Low	Limit visual indent, allow horizontal scroll
Search slow with large content	Low	Medium	Debounce 300ms, consider backend search later
Concurrent edit conflicts	Low	Medium	Reuse MDE soft lock pattern

---

Dependencies Graph

[MDE Feature] ──────────────────────────────────────┐
                                                     │
[Phase 1: Foundation] ──> [Phase 2: Tree] ──> [Phase 3: Content]
                                                     │
                              [Phase 4: Search] <────┤
                                                     │
[MDE Components] ──────> [Phase 5: Editing] <────────┤
                                                     │
                         [Phase 6: Creation] <───────┤
                                                     │
                         [Phase 7: Folders] <────────┤
                                                     │
                         [Phase 8: Feedback]         │
                                                     │
                         [Phase 9: Polish] <─────────┘

Note: Phases 1-4 can proceed without MDE. Phases 5-6 require MDE editor components.

---

Success Metrics

From spec.md:

• SC-001: Users can locate a known document via tree navigation within 10 seconds
• SC-002: Users can navigate to a specific section using TOC within 3 seconds
• SC-003: Users can create a new document within 60 seconds of starting the action
• SC-004: Users can create a new folder within 30 seconds
• SC-005: Search returns relevant results within 1 second
• SC-006: Tree expansion state persists across document selections within a session
• SC-007: System handles folder structures up to 5 levels deep without UI degradation
• SC-008: 90% of users can successfully navigate to and edit a document without assistance

---

Next Steps

1. Run /speckit.tasks - Generate detailed implementation tasks
2. Run /trilogy.jira-sync - Create Jira tickets from tasks
3. Verify MDE status - Check if editor components are ready for reuse
4. Run /speckit.implement - Begin Phase 1 implementation

---

Appendix

Mockup Reference

See mockups/summary.md for:

• Main layout options (GitBook-style recommended)
• Tree sidebar variations
• Feedback widget variations
• Responsive adaptations

Related Documentation

• Design Spec - Comprehensive UI/UX decisions
• MDE Plan - Editor dependency
• Storybook - Component library

Phase 2: Tab-Based Architecture

Future enhancement documented in spec. Phase 1 components should:

• Accept rootPath prop (not hardcoded .claude/BRAIN/)
• Use generic component names where possible
• Support URL pattern /brain/{path} for future /docs/{path}