TheFlow 2298d36bed fix(submissions): restructure Economist package and fix article display

- Create Economist SubmissionTracking package correctly:
  * mainArticle = full blog post content
  * coverLetter = 216-word SIR— letter
  * Links to blog post via blogPostId
- Archive 'Letter to The Economist' from blog posts (it's the cover letter)
- Fix date display on article cards (use published_at)
- Target publication already displaying via blue badge

Database changes:
- Make blogPostId optional in SubmissionTracking model
- Economist package ID: 68fa85ae49d4900e7f2ecd83
- Le Monde package ID: 68fa2abd2e6acd5691932150

Next: Enhanced modal with tabs, validation, export

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

2025-10-24 08:47:42 +13:00

20 KiB

Raw Blame History

Phase 2 Preparation Advisory

Project: Tractatus AI Safety Framework Domain: agenticgovernance.digital Objective: World-Class UI/UX Status: Pre-Deployment Recommendations Prepared: 2025-10-07

UI/UX Excellence Preparation
Design System Documentation
Performance Optimization
Accessibility Excellence
Domain Migration Checklist
Security & Privacy
Content Readiness
Monitoring & Analytics
User Testing Protocol
Final Pre-Deployment Checklist

UI/UX Excellence Preparation

World-Class UI/UX Standards

Benchmark Sites: Stripe Docs, Tailwind CSS Docs, Anthropic Claude Docs, Linear App

Core Principles:

Clarity over cleverness: Users understand immediately what the framework does
Speed: Perceived performance matters more than measured performance
Consistency: Every interaction follows predictable patterns
Accessibility: WCAG AAA aspirational (AA minimum achieved)
Delight: Subtle animations, thoughtful micro-interactions
Trust: Professional, credible, transparent design

Recommended Actions

Before Deployment:

Create comprehensive design system document (colors, typography, spacing, components)
Document component patterns (buttons, cards, modals, forms)
Define animation/transition standards (durations, easing functions)
Create UI component library reference page
Design mobile-first responsive breakpoints (documented)

During Soft Launch:

Conduct user testing sessions (5-10 users from each audience)
Track Core Web Vitals (LCP, FID, CLS)
Gather qualitative feedback (usability, clarity, trust)
A/B test key flows (researcher path vs. implementer path)

Design System Documentation

Create: `/docs/DESIGN-SYSTEM.md`

Content to Document:

Color Palette

/* Primary Colors */
--blue-600: #2563eb;  /* Primary CTA */
--blue-700: #1d4ed8;  /* Hover states */
--purple-700: #7c3aed; /* Accents */

/* Semantic Colors */
--success: #10b981;   /* Approvals, success states */
--warning: #f59e0b;   /* Warnings, pending states */
--error: #ef4444;     /* Errors, rejections */
--info: #3b82f6;      /* Information, tips */

/* Neutrals */
--gray-50 through --gray-900 (full Tailwind scale)

Typography Scale

/* Headings */
h1: 2.5rem (40px), font-bold, line-height 1.2
h2: 2rem (32px), font-bold, line-height 1.3
h3: 1.5rem (24px), font-semibold, line-height 1.4
h4: 1.25rem (20px), font-semibold, line-height 1.5

/* Body */
body: 1rem (16px), font-normal, line-height 1.6
small: 0.875rem (14px), font-normal, line-height 1.5

Spacing System

4px, 8px, 12px, 16px, 24px, 32px, 48px, 64px, 96px
(Tailwind's 1, 2, 3, 4, 6, 8, 12, 16, 24 scale)

Component Patterns

Buttons: Primary, Secondary, Outline, Ghost, sizes (sm, md, lg)
Cards: Default, Hover, Interactive, Stat cards
Forms: Input, Textarea, Select, Checkbox, Radio
Modals: Center, Slide-over, Confirmation dialogs
Notifications: Toast, Banner, Inline alerts

Animation Standards

/* Transitions */
--transition-fast: 150ms ease-in-out;
--transition-base: 200ms ease-in-out;
--transition-slow: 300ms ease-in-out;

/* Easing */
--ease-in-out: cubic-bezier(0.4, 0, 0.2, 1);
--ease-out: cubic-bezier(0, 0, 0.2, 1);

Action: Create this document before Week 5 (AI features). Use it to guide all UI implementation.

Performance Optimization

Target Metrics (World-Class Standards)

Metric	Target	Current	Status
Largest Contentful Paint (LCP)	<2.5s	~1.8s	✅ Good
First Input Delay (FID)	<100ms	~50ms	✅ Good
Cumulative Layout Shift (CLS)	<0.1	~0.05	✅ Good
Time to First Byte (TTFB)	<600ms	TBD	🔄 Test
Total Page Size	<1MB	~400KB	✅ Good
JavaScript Bundle Size	<200KB	~180KB	✅ Good

Optimization Checklist

Pre-Deployment:

Enable Brotli compression on Nginx
Configure HTTP/2 (automatic with Nginx + SSL)
Set aggressive caching headers for static assets (1 year)
Minify CSS and JavaScript (production build)
Optimize images (WebP format, lazy loading)
Preload critical assets (fonts, hero images)
Implement service worker for offline support (Phase 3)

Server-Side Optimizations:

Enable MongoDB query caching
Implement Redis for session storage (Phase 3)
Use CDN for static assets (Cloudflare bot protection only, or skip CDN entirely)
Configure connection pooling for MongoDB
Enable Nginx gzip/Brotli compression

Frontend Optimizations:

Code splitting for demos (load on demand)
Lazy load images below fold
Defer non-critical JavaScript
Inline critical CSS (above-the-fold)
Use font-display: swap for web fonts

Monitoring:

Set up Lighthouse CI in GitHub Actions
Configure Core Web Vitals monitoring (Google Analytics or Plausible)
Weekly performance audits during soft launch

Accessibility Excellence

WCAG AAA Aspirational Checklist

Level AA (Achieved):

✅ Semantic HTML (<header>, <main>, <footer>, <nav>)
✅ ARIA landmarks and labels
✅ Keyboard navigation (skip links, focus management)
✅ Color contrast 4.5:1 (text), 3:1 (UI components)
✅ Responsive design (mobile, tablet, desktop)
✅ Alt text for images
✅ Form labels and error messages

Level AAA (Aspirational):

Color contrast 7:1 (enhanced)
Sign language interpretation for video content (Phase 3)
Extended audio descriptions (if video content added)
No time limits on interactions (already achieved)
No flashing content (already achieved)

Accessibility Testing Tools

Automated Testing:

Install axe DevTools (browser extension)
Run Lighthouse accessibility audit (CI/CD)
Use WAVE tool (WebAIM) for manual checks
Configure Pa11y for automated testing

Manual Testing:

Keyboard-only navigation test (no mouse)
Screen reader testing (NVDA on Windows, VoiceOver on macOS)
High contrast mode testing
Zoom to 200% (text readability)
Color blindness simulation (Chrome DevTools)

Action: Run full accessibility audit in Week 9 (pre-soft launch).

Domain Migration Checklist

Update All References: `mysy.digital` → `agenticgovernance.digital`

Files to Check:

package.json (homepage field)
README.md (all domain references)
CLAUDE.md (project instructions)
src/config/app.config.js (domain configuration)
.env.example (domain variables)
All documentation in /docs/ (ROADMAP, COST-ESTIMATES, INFRASTRUCTURE, etc.)
Email templates (PHASE-2-EMAIL-TEMPLATES.md)
Presentation (PHASE-2-PRESENTATION.md)
Kickoff checklist (PHASE-2-KICKOFF-CHECKLIST.md)
HTML files (footer links, meta tags, canonical URLs)

DNS Configuration (OVHCloud Preferred):

Configure A record: agenticgovernance.digital → VPS IP
Configure A record: www.agenticgovernance.digital → VPS IP
Configure AAAA record (IPv6 if available)
Set TTL to 300 seconds (5 minutes) for initial testing
After stability, increase TTL to 3600 seconds (1 hour)

Cloudflare Configuration (Bot Protection Only):

Add domain to Cloudflare (free plan)
Enable Bot Fight Mode (free)
Disable Cloudflare CDN/proxy (DNS only mode)
Disable Auto Minify (we handle this server-side)
Disable Rocket Loader (causes CSP issues)
Enable DNSSEC (security)

SSL/TLS:

Obtain Let's Encrypt certificate for agenticgovernance.digital
Configure auto-renewal (certbot)
Test certificate validity (SSLLabs.com)

Action: Complete domain migration in Week 1 (immediately after VPS provisioning).

Security & Privacy

Pre-Deployment Security Audit

Server Hardening:

SSH key-only authentication (disable password login)
Change default SSH port (optional, reduces noise)
Configure UFW firewall (allow 22, 80, 443 only)
Install and configure Fail2ban (SSH, Nginx)
Enable automatic security updates (unattended-upgrades)
Disable root login via SSH
Set up non-root user with sudo access

Application Security:

Generate strong JWT secret (32+ characters, random)
Set secure session configuration (httpOnly, secure, sameSite)
Implement rate limiting (express-rate-limit)
Configure CORS properly (whitelist domains)
Set security headers (Helmet.js)
- Content-Security-Policy
- X-Frame-Options: DENY
- X-Content-Type-Options: nosniff
- Referrer-Policy: strict-origin-when-cross-origin
- Permissions-Policy (restrict camera, microphone, etc.)

MongoDB Security:

Enable authentication (create admin user, app user)
Bind to localhost only (no external access)
Use strong passwords (32+ characters)
Enable encryption at rest (Phase 3)
Regular backups (daily, retained 7 days)

Dependency Security:

Run npm audit before deployment
Fix all critical and high vulnerabilities
Set up GitHub Dependabot (automated dependency updates)
Configure Snyk or Sonar (optional, code quality scanning)

Privacy:

No tracking cookies (session only)
Privacy-respecting analytics (Plausible or self-hosted)
No third-party scripts (except Cloudflare bot protection)
GDPR compliance (data minimization, user rights)
Create /privacy page (data handling transparency)
Create /terms page (terms of service)

Action: Complete security audit in Week 3 (before soft launch invitations).

Content Readiness

Pre-Launch Content Checklist

Essential Pages (Must be live before soft launch):

/ (Homepage with clear value proposition)
/researcher (Audience path with technical depth)
/implementer (Code examples, API reference)
/advocate (Plain language, policy implications)
/about (Mission, values, Te Tiriti acknowledgment)
/docs (Framework documentation viewer)
/blog (At least 3-5 initial posts)
/api-reference (Complete API documentation)
/contact (Media inquiry form, email)
/privacy (Privacy policy)
/terms (Terms of service)

Blog Content (Seed 3-5 Posts Before Soft Launch):

Introductory Post: "Introducing the Tractatus Framework: AI Safety Through Sovereignty"
- Core principle explanation
- Why architectural constraints > behavioral alignment
- Link to technical documentation
Case Study: "The 27027 Incident: When AI Contradicts Explicit Instructions"
- Real-world example
- How Tractatus prevents this
- Interactive demo link
Technical Deep Dive: "Implementing Cross-Reference Validation in Production"
- Code examples
- Integration patterns
- Link to API reference
Policy Analysis: "AI Safety Regulation: Alignment vs. Boundaries"
- Policy implications
- Regulatory fit (EU AI Act, etc.)
- Advocacy perspective
Behind the Scenes: "Dogfooding Tractatus: How This Website Governs Its Own AI"
- Transparency post
- TRA-OPS-* policies in practice
- Human oversight examples

Action: Draft 3-5 blog posts in Weeks 7-8 (before soft launch). Human writes all drafts.

Monitoring & Analytics

Privacy-Respecting Analytics Setup

Recommended Tool: Plausible Analytics (GDPR-compliant, no cookies)

Alternative: Self-hosted Matomo or Umami

Metrics to Track:

Traffic: Pageviews, unique visitors, bounce rate
Engagement: Time on page, scroll depth, demo interactions
Audience: Researcher vs. Implementer vs. Advocate path split
Geography: Country distribution (no personal data)
Referrers: How users found the site (direct, search, social)

Goals to Track:

Demo interactions (classification, 27027, boundary)
Document downloads (PDFs)
Blog post reads (time on page >2 minutes)
Media inquiry submissions
Case study submissions

Setup:

Create Plausible account (or self-host)
Add tracking script to all pages
Configure goals (demo clicks, downloads)
Create dashboard for soft launch monitoring
Share dashboard link with stakeholders (transparency)

Error Monitoring: Sentry (free tier)

Create Sentry account
Integrate Sentry SDK (Express error handler)
Configure error alerts (email, Slack)
Set up performance monitoring (transaction traces)

Uptime Monitoring:

UptimeRobot (free, 5-minute intervals)
Pingdom or StatusCake (alternatives)
Configure alerts (email, SMS if critical)

Action: Set up monitoring in Week 4 (before AI features).

User Testing Protocol

Soft Launch User Testing Plan

Cohort: 20-50 users (Researchers, Implementers, Advocates)

Testing Method: Moderated + Unmoderated

Moderated Testing (5-10 Users)

Format: 30-minute video call (Zoom, Jitsi)

Script:

Introduction (5 min): Explain Tractatus at high level
Task-based testing (15 min):
- "Find and explain the core principle of the framework"
- "Try the 27027 incident demo and describe what happened"
- "Locate the API documentation for CrossReferenceValidator"
Open exploration (5 min): "Explore anything that interests you"
Q&A (5 min): "What was confusing? What was most valuable?"

Recording: Ask permission, record for analysis

Notes: Observer takes notes on friction points, confusion, delight

Unmoderated Testing (15-40 Users)

Format: Send structured feedback survey (Google Form or TypeForm)

Questions (from PHASE-2-EMAIL-TEMPLATES.md):

How clear is the framework's core principle? (1-5 scale)
What was confusing or unclear? (Open text)
What was most interesting or valuable? (Open text)
Which sections did you explore? (Checkboxes)
How useful are the interactive demos? (1-5 scale)
Would you recommend Tractatus to others? (Yes/Maybe/No)
Any other feedback? (Open text)

Metrics:

Average clarity rating (target: 4+/5)
Recommendation rate (target: 70%+ "Yes")
Confusion themes (qualitative analysis)

Action: Conduct testing in Weeks 10-11 (during soft launch).

Final Pre-Deployment Checklist

Week 0 (Before Kickoff)

Administrative:

OVHCloud account created and payment method added
Domain registered: agenticgovernance.digital ✅
Anthropic Claude API account created (production key)
ProtonMail account: admin@agenticgovernance.digital
GitHub repository updated with correct domain
All governance documents signed off (TRA-OPS-0001 through 0005) ✅

Development Environment:

Git repository clean (no uncommitted changes)
All tests passing (118/118) ✅
Production build tested locally (NODE_ENV=production npm start)
Environment variables documented (.env.example)
Secrets generated (JWT_SECRET, MONGODB_PASSWORD)

Documentation:

All domain references updated (mysy.digital → agenticgovernance.digital)
README.md updated with deployment instructions
CHANGELOG.md created (version 1.0.0 - Initial Release)
API documentation complete ✅
Design system documented (create DESIGN-SYSTEM.md)

Content:

3-5 blog posts drafted (human-written)
About/values page finalized
Privacy policy and terms of service drafted
Media inquiry response templates ready
Case study moderation guidelines reviewed ✅

Security:

JWT secrets generated (store securely, not in Git)
MongoDB passwords generated (32+ characters)
SSH keys generated for VPS access
Fail2ban configuration prepared
Security headers configured (Helmet.js)