tractatus/docs/FEATURE_RICH_UI_IMPLEMENTATION_PLAN.md

Feature-Rich UI Implementation Plan

Tractatus Website - Public-Facing Features

Status: Phase 3 Backend Complete | Now Implementing Public UI Date: 2025-10-11 Context: Gap analysis revealed strong backend (AI curation, governance, multi-project) but missing public-facing UI features outlined in ClaudeWeb conversation specification.

---

Executive Summary

Current State:

• ✅ Phase 1-3 Technical Foundation Complete
• ✅ Multi-Project Governance System Fully Implemented
• ✅ Blog Curation Backend Complete with AI Integration
• ✅ Admin Dashboard Complete (10 pages, full CRUD)
• ❌ Public Blog UI Missing
• ❌ Resource Directory Missing
• ❌ Public Transparency Features Limited
• ❌ Multi-language Support Not Implemented

Gap: ClaudeWeb specification outlines comprehensive public-facing features (blog, resources, multi-language, code playground, newsletter), but implementation focused heavily on admin/backend systems.

Strategy: Implement public-facing UI for existing backend capabilities before starting Phase 4 advanced features (forum, events, mobile app).

Timeline: 8 weeks (priorities 1-10)

---

Implementation Priorities

Priority 1: Public Blog System ⭐ START HERE

Effort: 6-8 hours Value: High - Leverages complete BlogCuration.service.js backend Dependencies: None - blog.routes.js already complete

Tasks:

1. Create /public/blog.html - Blog listing page

   • Grid/card layout for blog posts
   • Filter by category/tag
   • Search functionality
   • Pagination
   • Responsive design

2. Create /public/blog-post.html - Individual post template

   • Full blog post display
   • Author info
   • Published date
   • Related posts
   • Social sharing (privacy-preserving)
   • Comment system (optional)

3. Create /public/js/blog.js - Client-side logic

   • Fetch posts from GET /api/blog
   • Dynamic rendering
   • Search/filter client-side logic
   • Pagination state management
   • Markdown rendering (if posts use markdown)

4. Navigation updates

   • Add "Blog" to main navbar
   • Add "Latest Posts" to homepage
   • Link from footer

API Endpoints Available (already implemented):

GET /api/blog                    // List published posts
GET /api/blog/:slug              // Get single post by slug
POST /api/blog                   // Create (admin only)
PUT /api/blog/:id                // Update (admin only)
POST /api/blog/:id/publish       // Publish (admin only)
DELETE /api/blog/:id             // Delete (admin only)
POST /api/blog/suggest-topics    // AI topic suggestions (admin)
POST /api/blog/draft-post        // AI drafting (admin)
POST /api/blog/analyze-content   // Tractatus validation (admin)

Success Metrics:

• Public can view all published blog posts
• Posts are searchable and filterable
• Mobile-responsive layout
• No CSP violations (inst_008)
• Loads in <2s on 3G connection

---

Priority 2: Enhanced Koha Transparency Dashboard

Effort: 4-6 hours Value: High - Demonstrates values commitment (transparency, Te Tiriti) Dependencies: koha.routes.js already complete

Tasks:

1. Enhance /public/koha/transparency.html

   • Real-time donation metrics (total raised, allocation breakdown)
   • Visual charts (privacy-preserving analytics)
   • Public supporter acknowledgments (with permission)
   • Monthly transparency reports
   • Download CSV export for community audit

2. Create /public/js/koha-transparency.js

   • Fetch from GET /api/koha/transparency
   • Chart.js integration (or similar lightweight library)
   • Auto-refresh every 5 minutes

3. Link from homepage "Support This Work" section

API Endpoints Available:

GET /api/koha/transparency        // Public transparency data
POST /api/koha/donate             // Stripe donation flow
GET /api/koha/success             // Post-donation confirmation

Success Metrics:

• Real-time donation total visible
• Allocation breakdown (development, research, Māori sovereignty, etc.)
• Historical trend charts
• Downloadable transparency reports
• Mobile-responsive

---

Priority 3: Search Enhancement

Effort: 8-10 hours Value: Medium-High - Improves docs discoverability Dependencies: None - enhances existing docs.html

Tasks:

1. Enhance /public/docs.html search functionality

   • Faceted search filters:
     • Quadrant (Strategic, Operational, Tactical, System, Storage)
     • Persistence level (High, Medium, Low)
     • Audience path (Researcher, Implementer, Leader)
   • Autocomplete/suggestions
   • Result highlighting
   • Search history (localStorage)

2. Create /public/js/docs-search-enhanced.js

   • Client-side search index (if small enough)
   • OR backend search endpoint
   • Debounced search input
   • Filter state management

3. Add "Search Tips" help modal

Backend Enhancement (if needed):

GET /api/docs/search?q=...&quadrant=...&persistence=...&audience=...

Success Metrics:

• Search response time <500ms
• Relevant results ranked higher
• Filter combinations work correctly
• Keyboard navigation support (accessibility)

---

Priority 4: Media Triage AI Service

Effort: 10-12 hours Value: High - Demonstrates AI+human governance (dogfooding) Dependencies: Requires new service, but MediaInquiry model exists

Tasks:

1. Create /src/services/MediaTriage.service.js

   • AI urgency classification (Claude API)
   • Boundary enforcement (no auto-rejection, human reviews all)
   • Auto-response draft generation
   • Tractatus compliance checks

2. Create /public/admin/media-triage.html

   • Admin triage queue
   • AI urgency scores + reasoning
   • Draft responses
   • Human override interface
   • Audit trail

3. Enhance /public/media-inquiry.html

   • Show submission confirmation
   • Link to transparency page (public triage stats)

4. Create /public/media-triage-transparency.html

   • Public view of triage statistics
   • Average response time
   • AI vs human override rates
   • Boundary enforcement examples

API Endpoints to Create:

POST /api/media/triage/:id           // Run AI triage (admin)
POST /api/media/respond/:id          // Send response (admin)
GET /api/media/triage-stats          // Public transparency stats

Success Metrics:

• AI triage reduces admin time by 30%
• 100% human review before response
• Public transparency on AI assistance
• No boundary violations (BoundaryEnforcer catches all)

---

Priority 5: Resource Directory

Effort: 8-10 hours Value: Medium-High - Community building Dependencies: Requires new Resource model (already exists)

Tasks:

1. Create /public/resources.html

   • Curated list of governance resources
   • Filter by type (Article, Video, Tool, Framework, Research Paper)
   • Sort by relevance, date, popularity
   • External link tracking (privacy-preserving)

2. Create /public/admin/resource-curation.html

   • Admin interface for adding resources
   • AI-assisted categorization
   • Quality score prediction
   • Duplicate detection

3. Create /src/services/ResourceCurator.service.js

   • AI resource analysis (summarization, categorization)
   • Quality assessment
   • Duplicate detection
   • Tractatus validation (ensure resources align with framework values)

4. Update homepage to link to resources

API Endpoints to Create:

GET /api/resources                    // List public resources
POST /api/resources                   // Create (admin)
POST /api/resources/analyze           // AI analysis (admin)
PUT /api/resources/:id                // Update (admin)
DELETE /api/resources/:id             // Delete (admin)

Success Metrics:

• Minimum 50 high-quality resources at launch
• AI categorization accuracy >80%
• User-friendly filtering and search
• Mobile-responsive design

---

Priority 6: Enhanced Moderation Queue UI

Effort: 6-8 hours Value: High - Transparency and trust Dependencies: ModerationQueue model exists

Tasks:

1. Create /public/moderation-transparency.html

   • Public view of moderation statistics
   • AI reasoning explanations
   • Boundary enforcement logs
   • Human override statistics
   • Example cases (anonymized)

2. Enhance /public/admin/blog-curation.html

   • Show AI boundary checks
   • Display Tractatus validation results
   • Audit trail for all AI suggestions
   • Human override interface

3. Create /public/js/moderation-transparency.js

   • Fetch moderation stats
   • Chart human vs AI decisions
   • Display boundary enforcement examples

API Endpoints to Create:

GET /api/moderation/stats             // Public moderation statistics
GET /api/moderation/examples          // Anonymized examples

Success Metrics:

• Public can see AI assistance vs human decisions
• Boundary enforcement examples visible
• Transparency builds trust
• No sensitive data exposed

---

Priority 7: Newsletter System

Effort: 8-10 hours Value: Medium - Community engagement Dependencies: Email service provider (suggest Mailchimp or SendGrid)

Tasks:

1. Create /public/newsletter.html (or modal on homepage)

   • Email subscription form
   • Privacy policy link
   • Frequency selection (weekly, monthly)
   • Topic preferences

2. Create Newsletter model

   • Schema: email, preferences, subscribed_at, confirmed
   • Double opt-in confirmation

3. Create /src/routes/newsletter.routes.js

   • POST /api/newsletter/subscribe
   • POST /api/newsletter/confirm/:token
   • DELETE /api/newsletter/unsubscribe/:token

4. Create /public/admin/newsletter-manager.html

   • Send newsletter interface
   • Subscriber list
   • Email template editor
   • Send test email

5. Email service integration

   • SendGrid or Mailchimp API
   • Template management
   • Delivery tracking

API Endpoints to Create:

POST /api/newsletter/subscribe         // Subscribe with email
POST /api/newsletter/confirm/:token    // Confirm subscription
DELETE /api/newsletter/unsubscribe/:token  // Unsubscribe
GET /api/newsletter/subscribers        // List (admin)
POST /api/newsletter/send              // Send newsletter (admin)

Success Metrics:

• Double opt-in confirmation working
• Unsubscribe link in every email
• GDPR/privacy compliant
• Email delivery rate >95%

---

Priority 8: Code Playground

Effort: 16-20 hours Value: High - Developer engagement Dependencies: Requires sandbox environment (CodeMirror or Monaco Editor)

Tasks:

1. Create /public/playground.html

   • Code editor (CodeMirror or Monaco Editor)
   • Live preview pane
   • Pre-loaded framework examples:
     • Basic BoundaryEnforcer example
     • InstructionPersistenceClassifier demo
     • CrossReferenceValidator example
     • ContextPressureMonitor simulation
   • Share code via URL parameters (base64 encoded)

2. Create /public/js/playground.js

   • Editor initialization
   • Example loading
   • Live execution (sandboxed iframe or Web Worker)
   • Error handling and display

3. Add playground examples for all 5 framework components

4. Create tutorial content

   • Step-by-step walkthroughs
   • Interactive exercises
   • Challenge problems

API Endpoints (optional):

POST /api/playground/save              // Save code snippet (optional)
GET /api/playground/load/:id           // Load saved snippet (optional)

Success Metrics:

• Examples run without errors
• Editor has syntax highlighting
• Live preview updates in <500ms
• Mobile-usable (though not ideal)
• No security vulnerabilities (sandboxed execution)

---

Priority 9: Multi-language Support (Te Reo Māori)

Effort: 12-16 hours Value: High - Values alignment (Te Tiriti commitment) Dependencies: Translation service or human translators

Tasks:

1. Create language selector component

   • /public/js/components/language-selector.js
   • Dropdown in navbar
   • Persist selection to localStorage
   • Update page content dynamically

2. Create translation files

   • /public/translations/en.json (English baseline)
   • /public/translations/mi.json (Te Reo Māori)
   • Structure: JSON key-value pairs for all UI text

3. Update all public HTML files

   • Replace hardcoded text with translation keys
   • Use data-i18n attributes or JavaScript rendering

4. Priority pages for translation:

   • Homepage (index.html)
   • About/Values (about.html, about/values.html)
   • Te Tiriti acknowledgment (critical)
   • Navigation elements

5. Engage Māori language experts

   • Review translations for cultural appropriateness
   • Ensure Te Reo translations honor indigenous sovereignty

Translation Structure:

// en.json
{
  "nav.home": "Home",
  "nav.blog": "Blog",
  "nav.resources": "Resources",
  "hero.tagline": "Governance for AI Systems",
  "te_tiriti.acknowledgment": "We acknowledge Te Tiriti o Waitangi..."
}

// mi.json
{
  "nav.home": "Kāinga",
  "nav.blog": "Rangitaki",
  "nav.resources": "Rauemi",
  "hero.tagline": "Te Kaitiaki mō ngā Pūnaha AI",
  "te_tiriti.acknowledgment": "Ka mihia e mātou Te Tiriti o Waitangi..."
}

Success Metrics:

• Language selector works on all pages
• Te Reo translations reviewed by Māori language experts
• Selection persists across sessions
• No missing translations (fallback to English gracefully)
• Mobile-responsive language selector

---

Priority 10: User Accounts (Optional)

Effort: 12-16 hours Value: Medium - Enables personalization Dependencies: Auth system (JWT already implemented for admin)

Tasks:

1. Extend User model

   • Add role: 'user' (in addition to 'admin')
   • Add profile fields (optional: bio, avatar)
   • Add preferences (theme, language, newsletter)

2. Create /public/login.html and /public/register.html

   • User registration form
   • Login form
   • Password reset flow
   • Email verification (optional but recommended)

3. Create user-specific features

   • Saved resources (bookmarking)
   • Comment on blog posts
   • Track reading progress in docs
   • Personalized recommendations

4. Update auth.routes.js

   • Separate admin and user login flows
   • User registration endpoint
   • Password reset endpoint

API Endpoints to Create:

POST /api/auth/register                // User registration
POST /api/auth/login                   // User login (separate from admin)
POST /api/auth/reset-password          // Password reset request
POST /api/auth/reset-password/confirm  // Confirm password reset
GET /api/user/profile                  // Get user profile
PUT /api/user/profile                  // Update profile
GET /api/user/saved-resources          // Bookmarked resources
POST /api/user/save-resource/:id       // Bookmark resource

Success Metrics:

• User registration and login working
• Email verification (if implemented)
• Password reset flow working
• GDPR/privacy compliant (data export, deletion)
• No security vulnerabilities (XSS, CSRF, SQL injection)

---

Deferred to Phase 4+

The following features from the ClaudeWeb specification are intentionally deferred until Phase 4 or later:

Phase 4 Features (Advanced Community)

• Community Forum: Discourse or custom forum implementation
• Event Calendar: Webinars, workshops, conferences
• Mobile App/PWA: Progressive Web App for mobile users
• Webinar Integration: Live streaming and recording infrastructure
• Federation/Interoperability: ActivityPub or similar protocol support

Phase 5+ Features (Enterprise & Partnerships)

• Enterprise Portal: Custom governance solutions for organizations
• Academic Partnership Tools: Research collaboration platform
• Certification Program: Training and certification for implementers
• Consulting Marketplace: Connect organizations with Tractatus consultants

Rationale for Deferral: These features require significant infrastructure, ongoing maintenance, and community critical mass. Completing public-facing UI for Phases 1-3 first will build the community foundation needed for Phase 4+ features to succeed.

---

Success Metrics (Overall)

User Engagement

• 1,000+ unique visitors/month by Month 3
• 100+ blog post views/month by Month 2
• 50+ newsletter subscribers by Month 3
• 20+ resource directory visits/week by Month 2

Technical Quality

• All pages load in <2s on 3G connection
• Zero CSP violations (inst_008 compliance)
• 95%+ uptime (monitored by existing monitoring scripts)
• Accessibility: WCAG 2.1 AA compliance
• Mobile responsive: All pages usable on 320px width

Values Alignment

• Te Reo Māori translations reviewed by Māori language experts
• Koha transparency dashboard shows 100% allocation breakdown
• Moderation transparency shows 100% human review for boundary decisions
• No AI decisions made without human oversight (inst_016, inst_017, inst_018)

Developer Engagement

• Code playground used by 10+ developers by Month 3
• GitHub stars increase by 50+ by Month 3
• 5+ community contributions (issues, PRs, discussions)

---

Implementation Strategy

Week 1-2: Content Publishing Foundation

1. Priority 1: Public Blog System (6-8 hours)

   • Most immediate value
   • Leverages complete backend
   • Establishes content publishing pattern

2. Priority 2: Enhanced Koha Transparency (4-6 hours)

   • Quick win for values demonstration
   • Uses existing koha.routes.js
   • Builds trust with community

3. Priority 3: Search Enhancement (8-10 hours)

   • Improves existing docs.html
   • Better user experience
   • Foundation for future search features

Week 3-4: AI Features & Community

4. Priority 4: Media Triage AI Service (10-12 hours)

   • Demonstrates dogfooding (using framework to govern itself)
   • Shows AI+human governance in action
   • Public transparency builds trust

5. Priority 5: Resource Directory (8-10 hours)

   • Community value
   • AI-assisted curation
   • Content foundation

6. Priority 6: Enhanced Moderation Queue (6-8 hours)

   • Transparency and trust
   • Shows boundary enforcement
   • Complements Media Triage

Week 5-6: Engagement & Learning

7. Priority 7: Newsletter System (8-10 hours)

   • Community engagement
   • Recurring touchpoint
   • Email list asset

8. Priority 8: Code Playground (16-20 hours)

   • Developer engagement
   • Interactive learning
   • Framework adoption

Week 7-8: Cultural & Advanced

9. Priority 9: Multi-language Support (12-16 hours)

   • Values commitment (Te Tiriti)
   • Cultural appropriateness
   • Engage Māori language experts

10. Priority 10: User Accounts (12-16 hours, optional)

    • Enables personalization
    • Foundation for future features
    • Community building

---

Pre-Implementation Checklist

Before starting each priority, run:

node scripts/pre-action-check.js <action-type> [file-path] <description>

Action types: file-edit, database, architecture, config, security, values, complex

Example:

node scripts/pre-action-check.js file-edit public/blog.html "Create public blog listing page"

Exit codes:

• 0 = PASS (proceed)
• 1 = FAIL (blocked, address issues)
• 2 = ERROR (system failure)

CSP Validation (inst_008 enforcement):

• Automatically validates HTML/JS files for Content Security Policy violations
• Detects: inline event handlers, inline styles, inline scripts, javascript: URLs
• Blocks action if violations found

---

Context Pressure Monitoring

Mandatory checkpoints (inst_001):

• 50,000 tokens (25%): Report pressure level + next checkpoint
• 100,000 tokens (50%): Report pressure level + warn if elevated
• 150,000 tokens (75%): Report pressure level + recommend action if high

Format: 📊 Context Pressure: [LEVEL] ([SCORE]%) | Tokens: [CURRENT]/200000 | Next: [CHECKPOINT]

Command: node scripts/check-session-pressure.js --tokens <current>/<budget> --messages <count>

---

Conclusion

This implementation plan prioritizes public-facing UI features that leverage the complete Phase 1-3 backend infrastructure. By focusing on blog publishing, transparency, search, AI-assisted features, and multi-language support, we honor the ClaudeWeb specification's vision while building on our strong technical foundation.

Recommended start: Priority 1: Public Blog System for immediate value and content publishing foundation.

Next Steps: Proceed with Priority 1 implementation, then re-evaluate priorities based on user feedback and community needs.

---

Document Version: 1.0 Last Updated: 2025-10-11 Author: Claude Code (Tractatus Framework Implementation)