TheFlow 02bb3261db 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

14 KiB

Raw Blame History

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):

"How to Scale Tractatus: Breaking the Chicken-and-Egg Problem" (3,500+ words)
"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

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:

login.html - Admin login page ✅ ACCESSIBLE
dashboard.html - Main admin dashboard
blog-curation.html - Blog management
case-moderation.html - Case study moderation
media-triage.html - Media inquiry triage
newsletter-management.html - Newsletter admin
rule-manager.html - Governance rules management
project-manager.html - Project tracking
hooks-dashboard.html - Framework hooks metrics
audit-analytics.html - Audit log analytics
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

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

Blog curation - /admin/blog-curation.html
Newsletter management - /admin/newsletter-management.html
Media triage - /admin/media-triage.html
Case moderation - /admin/case-moderation.html
Rules manager - /admin/rule-manager.html
Project manager - /admin/project-manager.html
Hooks dashboard - /admin/hooks-dashboard.html
Audit analytics - /admin/audit-analytics.html

⚙️ Backend/CLI Only (No UI):

Framework components (6 services)
Hook validators (architectural enforcement)
Loop detector
User suggestion tracker
Pre-deployment validator
Instruction analytics
Action pattern tracker
Framework incidents database

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

14 KiB Raw Blame History

Backend to Frontend Feature Mapping

✅ ADMIN ACCESS CORRECTED

PUBLIC-FACING FEATURES (No Authentication Required)

1. Blog System ✅ FULLY VISIBLE

2. About Page Enhancements ✅ FULLY VISIBLE

3. Documents System ✅ FULLY VISIBLE

4. Newsletter System ✅ PARTIALLY VISIBLE

5. Media Inquiries ✅ FULLY VISIBLE

6. Koha (Donations) ⏳ PARTIALLY IMPLEMENTED

7. Governance Case Studies ✅ FULLY VISIBLE

ADMIN-ONLY FEATURES (Authentication Required)

Admin Portal Structure

1. Blog Curation (Admin Only)

2. Newsletter Management (Admin Only)

3. Media Inquiry Triage (Admin Only)

4. Case Study Moderation (Admin Only)

5. Governance Rules Manager (Admin Only)

6. Project Manager (Admin Only)

7. Hooks Metrics Dashboard (Admin Only)

8. Audit Analytics (Admin Only)

9. CLAUDE.md Migrator (Admin Only)

FRAMEWORK COMPONENTS (Backend Only - No Direct UI)

1. ContextPressureMonitor ⚙️ NO UI

2. InstructionPersistenceClassifier ⚙️ NO UI

3. CrossReferenceValidator ⚙️ NO UI

4. BoundaryEnforcer ⚙️ NO UI

5. MetacognitiveVerifier ⚙️ NO UI

6. PluralisticDeliberationOrchestrator ⚙️ NO UI

7. LoopDetector ⚙️ NO UI (NEW)

8. User Suggestion Tracker ⚙️ NO UI (NEW)

9. Pre-Deployment Validator ⚙️ NO UI (NEW)

10. Instruction Analytics ⚙️ NO UI (NEW)

SUMMARY: WHERE TO SEE FEATURES

✅ Fully Visible on Public Site:

🔐 Admin-Only (Requires Login):

⚙️ Backend/CLI Only (No UI):

ADMIN LOGIN PROCESS

API ENDPOINTS SUMMARY

14 KiB

Raw Blame History