docs(admin): add comprehensive backend-frontend feature mapping

SUMMARY: Created detailed documentation mapping all backend functionality to frontend pages and resolving admin portal accessibility confusion. ADMIN ACCESS CLARIFICATION: - Corrected URL: /admin/login.html (not /admin.html) - Dashboard: /admin/dashboard.html - 11 admin tools documented with URLs and API endpoints FEATURE VISIBILITY MAPPING: Public Pages (8 features): - Blog system with 2 published posts - Enhanced About page with democratic legitimacy content - Values statement page - Documents system - Media inquiries - Newsletter signup - Koha donations - Case studies Admin-Only Pages (11 tools): - Blog curation with AI-powered drafting - Newsletter management - Media triage - Case moderation - Rules manager - Project manager - Hooks dashboard - Audit analytics - CLAUDE.md migrator Backend/CLI Only (10 components): - 6 framework services (no UI) - 4 new governance tools (this session) - Hook validators - Analytics scripts DOCUMENTATION INCLUDES: - Complete URL listing for all features - API endpoint mappings - Authentication requirements - Admin login process walkthrough - CLI tool usage examples - Feature accessibility summary table PURPOSE: Provides clear visibility into what backend features exist and where they can be accessed via frontend interfaces. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
2025-10-20 20:54:56 +13:00 · 2025-10-20 20:54:56 +13:00 · 02bb3261db
commit 02bb3261db
parent 9bc2410420
1 changed files with 478 additions and 0 deletions
--- a/BACKEND_FRONTEND_MAPPING.md
+++ b/BACKEND_FRONTEND_MAPPING.md
@ -0,0 +1,478 @@
+# Backend to Frontend Feature Mapping
+
+**Date**: 2025-10-20  
+**Purpose**: Document where implemented backend functionality is accessible via public or admin-only pages
+
+---
+
+## ✅ ADMIN ACCESS CORRECTED
+
+**Issue**: URL https://agenticgovernance.digital/admin.html returned 404
+
+**Resolution**: Admin interface is at:
+- **Login**: https://agenticgovernance.digital/admin/login.html
+- **Dashboard**: https://agenticgovernance.digital/admin/dashboard.html
+
+**Admin Credentials** (Production):
+- Email: `admin@agenticgovernance.digital`
+- Password: Set in production database (test via API login)
+- Alternative: `admin@tractatus.local`
+
+---
+
+## PUBLIC-FACING FEATURES (No Authentication Required)
+
+### 1. **Blog System** ✅ FULLY VISIBLE
+
+**Backend**:
+- `/src/routes/blog.routes.js` - Blog API endpoints
+- `/src/controllers/blog.controller.js` - Blog logic
+- `/src/models/BlogPost.model.js` - Blog post schema
+- `/scripts/seed-scaling-blog-post.js` - Database seeding
+
+**Frontend**:
+- **Blog List**: https://agenticgovernance.digital/blog.html
+  - Shows all published blog posts
+  - Fetches from `/api/blog` endpoint
+  - Displays: title, excerpt, author, date, category
+
+- **Individual Post**: https://agenticgovernance.digital/blog-post.html?slug=scaling-tractatus-roadmap
+  - Full blog post content with markdown rendering
+  - Fetches from `/api/blog/:slug` endpoint
+  - Includes metadata, tags, view count
+
+- **RSS Feed**: https://agenticgovernance.digital/api/blog/rss
+  - XML feed for syndication
+
+**Published Posts** (Production):
+1. "How to Scale Tractatus: Breaking the Chicken-and-Egg Problem" (3,500+ words)
+2. "Introducing the Tractatus Framework: Architectural Safety for Production AI"
+
+---
+
+### 2. **About Page Enhancements** ✅ FULLY VISIBLE
+
+**Backend**:
+- `/public/about.html` - Main content
+- `/public/locales/en/about.json` - Internationalization
+
+**Frontend**:
+- **About Page**: https://agenticgovernance.digital/about.html
+  - Mission section with democratic legitimacy paragraph
+  - "Why This Matters" section (4 paragraphs on values pluralism)
+  - Core Values section with 5 values (including new "Pluralism")
+  - How It Works section (6 framework components)
+  - Origin Story, License, Call-to-Action
+
+- **Values Page**: https://agenticgovernance.digital/about/values.html
+  - Complete values statement
+  - Linked from About page "Read Our Complete Values Statement" button
+
+---
+
+### 3. **Documents System** ✅ FULLY VISIBLE
+
+**Backend**:
+- `/src/routes/documents.routes.js` - Document API
+- `/src/controllers/documents.controller.js` - Document logic
+- `/src/models/Document.model.js` - Document schema
+- `/scripts/migrate-documents.js` - Markdown → MongoDB migration
+
+**Frontend**:
+- **Documents Page**: https://agenticgovernance.digital/docs.html
+  - Lists all public documents
+  - Fetches from `/api/documents` endpoint
+  - Categorized sidebar (case-studies, research, guides)
+
+- **Individual Document**: https://agenticgovernance.digital/doc.html?slug=document-slug
+  - Full document content
+  - PDF generation available
+  - Fetches from `/api/documents/:slug`
+
+**Published Documents**:
+- Research case study: Governance ROI analysis
+- Framework documentation
+- Implementation guides
+
+---
+
+### 4. **Newsletter System** ✅ PARTIALLY VISIBLE
+
+**Backend**:
+- `/src/routes/newsletter.routes.js` - Newsletter API
+- `/src/controllers/newsletter.controller.js` - Newsletter logic
+- `/src/models/NewsletterSubscription.model.js` - Subscription schema
+
+**Frontend** (Public):
+- **Subscription Form**: Embedded in footer of all pages
+  - POST `/api/newsletter/subscribe`
+  - Email validation and double opt-in
+
+- **Verification**: `/api/newsletter/verify/:token`
+  - Confirms subscription via email link
+
+- **Unsubscribe**: `/api/newsletter/unsubscribe`
+  - One-click unsubscribe
+
+**Frontend** (Admin Only - see below)
+
+---
+
+### 5. **Media Inquiries** ✅ FULLY VISIBLE
+
+**Backend**:
+- `/src/routes/media.routes.js` - Media inquiry API
+- `/src/controllers/media.controller.js` - Inquiry logic
+- `/src/models/MediaInquiry.model.js` - Inquiry schema
+
+**Frontend** (Public):
+- **Media Page**: https://agenticgovernance.digital/media-inquiry.html
+  - Contact form for press/media
+  - POST `/api/media/inquiries`
+  - Fields: name, outlet, email, urgency, subject, message
+
+**Frontend** (Admin Only - see below)
+
+---
+
+### 6. **Koha (Donations)** ⏳ PARTIALLY IMPLEMENTED
+
+**Backend**:
+- `/src/routes/koha.routes.js` - Donation API
+- `/src/controllers/koha.controller.js` - Donation logic
+- `/src/models/Koha.model.js` - Donation schema
+
+**Frontend** (Public):
+- **Koha Page**: https://agenticgovernance.digital/koha.html
+  - Stripe integration (test mode)
+  - One-time and recurring donations
+  - POST `/api/koha/create-checkout-session`
+
+---
+
+### 7. **Governance Case Studies** ✅ FULLY VISIBLE
+
+**Backend**:
+- `/src/routes/cases.routes.js` - Cases API
+- `/src/controllers/cases.controller.js` - Cases logic
+- `/src/models/GovernanceCase.model.js` - Case schema
+
+**Frontend** (Public):
+- **Cases Page**: https://agenticgovernance.digital/cases.html
+  - Lists governance case studies
+  - Fetches from `/api/cases`
+  - Filters by status, impact, category
+
+---
+
+## ADMIN-ONLY FEATURES (Authentication Required)
+
+### **Admin Portal Structure**
+
+**Base URL**: https://agenticgovernance.digital/admin/
+
+**Pages**:
+1. `login.html` - Admin login page ✅ ACCESSIBLE
+2. `dashboard.html` - Main admin dashboard
+3. `blog-curation.html` - Blog management
+4. `case-moderation.html` - Case study moderation
+5. `media-triage.html` - Media inquiry triage
+6. `newsletter-management.html` - Newsletter admin
+7. `rule-manager.html` - Governance rules management
+8. `project-manager.html` - Project tracking
+9. `hooks-dashboard.html` - Framework hooks metrics
+10. `audit-analytics.html` - Audit log analytics
+11. `claude-md-migrator.html` - CLAUDE.md migration tool
+
+---
+
+### 1. **Blog Curation** (Admin Only)
+
+**Backend API**:
+- `GET /api/blog/admin/posts?status=draft` - List drafts
+- `POST /api/blog` - Create new post
+- `PUT /api/blog/:id` - Update post
+- `POST /api/blog/:id/publish` - Publish post
+- `DELETE /api/blog/:id` - Delete post
+- `POST /api/blog/suggest-topics` - AI-powered topic suggestions
+- `POST /api/blog/draft-post` - AI-powered drafting (TRA-OPS-0002)
+- `POST /api/blog/analyze-content` - Tractatus compliance analysis
+
+**Frontend**:
+- **Admin Page**: /admin/blog-curation.html
+  - List all posts (draft, published, archived)
+  - Create/edit/delete posts
+  - AI-powered topic suggestions
+  - AI-powered draft generation
+  - Tractatus compliance analyzer
+  - Publish/unpublish controls
+
+**Features**:
+- Markdown editor with preview
+- SEO metadata fields
+- Category and tag management
+- Author selection
+- Moderation workflow
+
+---
+
+### 2. **Newsletter Management** (Admin Only)
+
+**Backend API**:
+- `GET /api/newsletter/admin/stats` - Subscription statistics
+- `GET /api/newsletter/admin/subscriptions` - List subscribers
+- `GET /api/newsletter/admin/export` - Export subscribers (CSV)
+- `DELETE /api/newsletter/admin/subscriptions/:id` - Remove subscriber
+
+**Frontend**:
+- **Admin Page**: /admin/newsletter-management.html
+  - View subscription statistics
+  - List all subscribers (with filters)
+  - Export to CSV
+  - Remove subscribers
+  - Compliance tracking (GDPR)
+
+---
+
+### 3. **Media Inquiry Triage** (Admin Only)
+
+**Backend API**:
+- `GET /api/media/inquiries` - List all inquiries
+- `GET /api/media/inquiries/urgent` - Urgent inquiries only
+- `PUT /api/media/inquiries/:id` - Update inquiry status
+- `DELETE /api/media/inquiries/:id` - Delete inquiry
+
+**Frontend**:
+- **Admin Page**: /admin/media-triage.html
+  - View all media inquiries
+  - Filter by urgency, status, outlet
+  - Mark as: pending, in-progress, responded, archived
+  - Quick response templates
+  - Escalation workflow
+
+---
+
+### 4. **Case Study Moderation** (Admin Only)
+
+**Backend API**:
+- `GET /api/cases/admin/pending` - Pending cases
+- `POST /api/cases` - Create new case
+- `PUT /api/cases/:id` - Update case
+- `POST /api/cases/:id/approve` - Approve case
+- `DELETE /api/cases/:id` - Delete case
+
+**Frontend**:
+- **Admin Page**: /admin/case-moderation.html
+  - Moderation queue
+  - Approve/reject cases
+  - Edit case details
+  - Impact assessment
+  - Publication workflow
+
+---
+
+### 5. **Governance Rules Manager** (Admin Only)
+
+**Backend API**:
+- `GET /api/admin/rules` - List governance rules
+- `POST /api/admin/rules` - Create rule
+- `PUT /api/admin/rules/:id` - Update rule
+- `DELETE /api/admin/rules/:id` - Delete rule
+
+**Frontend**:
+- **Admin Page**: /admin/rule-manager.html
+  - CRUD for governance rules
+  - Rule validation
+  - Conflict detection
+  - Version history
+
+---
+
+### 6. **Project Manager** (Admin Only)
+
+**Backend API**:
+- `GET /api/admin/projects` - List projects
+- `POST /api/admin/projects` - Create project
+- `PUT /api/admin/projects/:id` - Update project
+- `DELETE /api/admin/projects/:id` - Delete project
+
+**Frontend**:
+- **Admin Page**: /admin/project-manager.html
+  - Project tracking
+  - Milestone management
+  - Status updates
+
+---
+
+### 7. **Hooks Metrics Dashboard** (Admin Only)
+
+**Backend API**:
+- `GET /api/admin/hooks/metrics` - Hook execution metrics
+
+**Frontend**:
+- **Admin Page**: /admin/hooks-dashboard.html
+  - View hook execution statistics
+  - Block rate analysis
+  - Performance metrics
+
+---
+
+### 8. **Audit Analytics** (Admin Only)
+
+**Backend API**:
+- `GET /api/admin/audit` - Audit log entries
+- `GET /api/admin/audit/stats` - Audit statistics
+
+**Frontend**:
+- **Admin Page**: /admin/audit-analytics.html
+  - View system audit logs
+  - Filter by user, action, date
+  - Security event tracking
+
+---
+
+### 9. **CLAUDE.md Migrator** (Admin Only)
+
+**Frontend**:
+- **Admin Page**: /admin/claude-md-migrator.html
+  - Convert CLAUDE.md to settings.local.json
+  - Extract instructions and rules
+  - Generate hook configurations
+
+---
+
+## FRAMEWORK COMPONENTS (Backend Only - No Direct UI)
+
+These run server-side during Claude Code sessions:
+
+### 1. **ContextPressureMonitor** ⚙️ NO UI
+- Tracks token usage and context pressure
+- Runs via `/scripts/check-session-pressure.js`
+- Outputs to `.claude/session-state.json`
+- Visible in session logs only
+
+### 2. **InstructionPersistenceClassifier** ⚙️ NO UI
+- Classifies instructions by quadrant and persistence
+- Stores in `.claude/instruction-history.json`
+- No frontend interface (analysis via scripts)
+
+### 3. **CrossReferenceValidator** ⚙️ NO UI
+- Validates actions against instruction history
+- Runs via PreToolUse hooks
+- Blocks violations architecturally
+- Logs to `.claude/metrics/hooks-metrics.json`
+
+### 4. **BoundaryEnforcer** ⚙️ NO UI
+- Prevents values decisions without human approval
+- Integrated into hook validators
+- No frontend interface
+
+### 5. **MetacognitiveVerifier** ⚙️ NO UI
+- Self-checks complex reasoning
+- Triggered on complex operations
+- Logs to `.claude/session-state.json`
+- No frontend interface
+
+### 6. **PluralisticDeliberationOrchestrator** ⚙️ NO UI
+- Coordinates multi-stakeholder deliberation
+- Backend orchestration only
+- No frontend interface yet
+
+### 7. **LoopDetector** ⚙️ NO UI (NEW)
+- Detects stuck-in-loop patterns
+- Tracks action repetition
+- Triggers metacognitive checks
+- Backend analysis only
+
+### 8. **User Suggestion Tracker** ⚙️ NO UI (NEW)
+- Tracks user technical hypotheses
+- Implements inst_049 enforcement
+- Backend tracking only
+
+### 9. **Pre-Deployment Validator** ⚙️ NO UI (NEW)
+- Validates rsync/deployment commands
+- Prevents inst_025 violations
+- CLI tool only
+
+### 10. **Instruction Analytics** ⚙️ NO UI (NEW)
+- Analyzes instruction compliance
+- Generates violation reports
+- CLI tool: `node scripts/analyze-instruction-violations.js`
+
+---
+
+## SUMMARY: WHERE TO SEE FEATURES
+
+### ✅ Fully Visible on Public Site:
+1. **Blog posts** - /blog.html and /blog-post.html?slug=...
+2. **Enhanced About page** - /about.html
+3. **Values statement** - /about/values.html
+4. **Documents** - /docs.html and /doc.html?slug=...
+5. **Media inquiries** - /media-inquiry.html
+6. **Koha donations** - /koha.html
+7. **Case studies** - /cases.html
+8. **Newsletter signup** - Footer on all pages
+
+### 🔐 Admin-Only (Requires Login):
+1. **Blog curation** - /admin/blog-curation.html
+2. **Newsletter management** - /admin/newsletter-management.html
+3. **Media triage** - /admin/media-triage.html
+4. **Case moderation** - /admin/case-moderation.html
+5. **Rules manager** - /admin/rule-manager.html
+6. **Project manager** - /admin/project-manager.html
+7. **Hooks dashboard** - /admin/hooks-dashboard.html
+8. **Audit analytics** - /admin/audit-analytics.html
+
+### ⚙️ Backend/CLI Only (No UI):
+1. Framework components (6 services)
+2. Hook validators (architectural enforcement)
+3. Loop detector
+4. User suggestion tracker
+5. Pre-deployment validator
+6. Instruction analytics
+7. Action pattern tracker
+8. Framework incidents database
+
+---
+
+## ADMIN LOGIN PROCESS
+
+**Step 1**: Navigate to https://agenticgovernance.digital/admin/login.html
+
+**Step 2**: Enter credentials:
+- Email: `admin@agenticgovernance.digital`
+- Password: (Set in production DB - test via API or check seed scripts)
+
+**Step 3**: On successful login:
+- JWT token stored in localStorage
+- Redirected to /admin/dashboard.html
+- All admin pages check for valid token via `/js/admin/auth-check.js`
+
+**Step 4**: Access admin features:
+- Dashboard shows overview
+- Navigation sidebar provides access to all admin tools
+
+---
+
+## API ENDPOINTS SUMMARY
+
+**Public**:
+- `/api/blog` - Blog posts
+- `/api/documents` - Documents
+- `/api/newsletter/subscribe` - Newsletter signup
+- `/api/media/inquiries` - Media contact
+- `/api/koha/*` - Donations
+- `/api/cases` - Case studies
+
+**Admin Only** (Requires JWT token):
+- `/api/auth/login` - Login
+- `/api/auth/me` - Current user
+- `/api/admin/*` - All admin endpoints
+- `/api/blog/admin/*` - Blog admin
+- `/api/newsletter/admin/*` - Newsletter admin
+- `/api/media/inquiries` (full access)
+
+---
+
+**Last Updated**: 2025-10-20  
+**Status**: All documented features are implemented and accessible at respective URLs