Social Archetype Quiz - Refactored

A comprehensive personality quiz application built with Val Town that helps users discover their social archetype through interactive questions. The application has been fully refactored following Val Town best practices with a modern, scalable architecture.

• Email Collection: Users must provide email to begin quiz
• Interactive Quiz: 15 carefully crafted questions with smooth animations
• Personality Analysis: Advanced algorithm determining primary social archetype
• Email Delivery: Automated email with detailed results and insights
• Data Persistence: All submissions stored in SQLite database

• Real-time Progress Tracking: Visual progress bar and question counter
• Completion Time Analysis: Tracks and analyzes user completion patterns
• Personality Insights: Deep analysis of user's social tendencies
• Ideal Events Matching: Personalized event and community recommendations
• Social Sharing: Built-in sharing capabilities for social media
• Results Download: Export results as JSON file
• Admin Analytics: Backend analytics for archetype distribution
• Professional Email System: HTML/text emails following Val Town standards
• Custom Email Headers: Tracking and branding headers for analytics
• Configurable Email Templates: Dynamic subject lines and content
• Reply-To Support: Users can reply directly to quiz emails

• Responsive Design: Works seamlessly on desktop and mobile
• Smooth Animations: Fade-in/out transitions and progress animations
• Modern UI: Clean, professional design with CSS variables
• Accessibility: WCAG compliant with proper contrast and keyboard navigation

ssscQuiz/
├── index.http.ts             # 🌐 Main HTTP Val - Primary quiz application
├── admin.http.ts             # 📊 Admin HTTP Val - Dashboard for data analytics
├── config.ts                 # ⚙️ Configuration file for email and app settings
├── frontend/
│   ├── components/
│   │   ├── EmailScreen.tsx           # Email collection component
│   │   ├── IntroScreen.tsx           # Welcome and instructions
│   │   ├── CountdownScreen.tsx       # Pre-quiz countdown
│   │   ├── PersonalityQuiz.tsx       # Main quiz interface
│   │   └── QuizResultsComponent.tsx  # Results display with tabs
│   ├── index.html            # Main HTML template
│   ├── index.tsx             # React app entry point
│   └── style.css             # Comprehensive CSS styles with mobile responsiveness
├── shared/
│   ├── types.ts              # TypeScript interfaces and types
│   ├── quizData.ts           # Quiz questions and archetype information
│   └── utils.ts              # Shared utility functions
├── main.tsx                  # Legacy entry point (redirects to index.http.ts)
├── deno.json                 # Deno configuration
└── README.md                 # This file

• Backend: Hono web framework on Deno
• Frontend: React 18 with TypeScript
• Database: Val Town SQLite
• Email: Val Town email service
• Styling: CSS with custom properties and responsive design
• Build Tool: Native Deno/ES modules

The quiz identifies six primary social archetypes:

1. The Visionary 🔮 - Forward-thinking innovators
2. The Nurturer 🤗 - Community builders and carers
3. The Sage 📚 - Knowledge seekers and wisdom sharers
4. The Artisan 🎨 - Creative expressers and makers
5. The Catalyst ⚡ - Change-makers and motivators
6. The Connector 🌐 - Natural networkers and community builders

Each archetype includes:

• Detailed personality description
• Key traits and characteristics
• Famous examples
• Ideal events and communities
• Personalized insights

• Primary HTTP val that users visit
• Hono web server with comprehensive error handling
• SQLite database with optimized schema and indexing
• Enhanced email system with HTML/text templates
• API endpoints for quiz submission and analytics
• Static file serving for all frontend assets
• Mobile-responsive design

• Separate HTTP val for administrative functions
• Real-time analytics and data visualization
• Responsive table displaying all quiz submissions
• Pagination for large datasets
• CSV export functionality for data analysis
• Mobile-optimized admin interface

• RESTful API with proper error handling
• SQLite database with structured schema and indexes
• Email automation with professional HTML templates
• Admin analytics with real-time data
• Static file serving for frontend assets
• IP hashing for privacy compliance

• Component-based architecture
• State management with React hooks
• Type-safe interfaces throughout
• Smooth animations and transitions
• Progressive enhancement

The application uses a versioned schema management system with automatic migrations:

• Current Version: v2
• Migration System: Automatic migration on startup
• Migration Tracking: sssc_schema_migrations table tracks applied migrations

CREATE TABLE sssc_quiz_submissions_v2 (
  id INTEGER PRIMARY KEY AUTOINCREMENT,
  email TEXT NOT NULL,
  primary_archetype TEXT NOT NULL,
  secondary_archetype TEXT,                    -- NEW: Second highest scoring archetype
  breakdown TEXT NOT NULL,                     -- JSON of archetype percentages
  answers TEXT NOT NULL,                       -- JSON of user answers
  timestamp DATETIME DEFAULT CURRENT_TIMESTAMP,
  completion_time INTEGER,                     -- Milliseconds
  insights TEXT,                               -- JSON of generated insights
  user_agent TEXT,
  ip_hash TEXT,
  session_id TEXT,                             -- NEW: Unique session identifier
  quiz_version TEXT DEFAULT '2.0',             -- NEW: Quiz version tracking
  personality_complexity_score REAL,          -- NEW: 0.0-1.0 complexity metric
  response_consistency_score REAL,            -- NEW: 0.0-1.0 consistency metric
  created_at DATETIME DEFAULT CURRENT_TIMESTAMP,  -- NEW: Record creation time
  updated_at DATETIME DEFAULT CURRENT_TIMESTAMP   -- NEW: Record update time
);

• Secondary Archetype: Automatically calculated second-highest scoring personality type
• Personality Complexity Score: Measures trait distribution balance (0.0 = single dominant trait, 1.0 = perfectly balanced)
• Response Consistency Score: Measures answer pattern consistency within archetype groups
• Session Tracking: Unique session IDs for advanced analytics
• Version Tracking: Quiz version used for historical analysis

• Automatic Data Migration: v1 data automatically migrated to v2 schema with enhanced fields
• Backward Compatibility: System handles both v1 and v2 data seamlessly
• Migration Logging: All migrations logged with execution time and success status

• Completion Time Analysis: Fast/moderate/thoughtful pacing
• Archetype Strength: Dominance vs balanced personality
• Personality Complexity: Focused/balanced/complex profiles

• Archetype distribution across all users
• Average completion times by archetype
• Total submission tracking
• Performance metrics

1. Email Collection: User enters email address with validation
2. Introduction: Welcome screen with instructions and tips
3. Countdown: 3-second countdown to build anticipation
4. Quiz Questions: 15 questions with progress tracking
5. Results Processing: Calculation of archetype and insights
6. Results Display: Comprehensive results with multiple tabs
7. Email Delivery: Automated email with detailed results

• Primary: #4361ee (Vibrant Blue)
• Secondary: #3a86ff (Sky Blue)
• Tertiary: #4cc9f0 (Cyan)
• Accent: #f72585 (Pink)
• Success: #4bc06c (Green)
• Warning: #ff9f1c (Orange)

• Headers: Playfair Display (Serif)
• Body: Poppins (Sans-serif)
• Consistent spacing and hierarchy

• Desktop: 768px+
• Tablet: 481px - 767px
• Mobile: 480px and below

• Email Validation: Client and server-side validation
• Data Sanitization: All inputs sanitized before database storage
• Privacy Focused: No tracking beyond essential quiz functionality
• Secure Storage: Encrypted database storage through Val Town

The application follows Val Town best practices with HTTP val naming:

1. Main Application: index.http.ts - Primary entry point users visit
2. Admin Dashboard: admin.http.ts - Analytics and data management
3. Database: Automatic SQLite initialization with proper indexing
4. Email: Enhanced email service with HTML templates following Val Town standards
5. Frontend: Served as static files with mobile-responsive design

Update config.ts with your settings:

• adminEmail: Your email for admin notifications
• siteUrl: Your Val Town URL
• hashSalt: Unique salt for privacy protection
• emailConfig.from.email: Must be in format username.valname@valtown.email
• emailConfig.from.name: Display name for outgoing emails
• emailConfig.replyTo: Where users can reply to emails
• emailConfig.headers: Custom email headers for tracking and branding

Based on Val Town's email documentation, the email system supports:

from: {
  email: "username.valname@valtown.email", // Must follow Val Town format
  name: "Display Name"
}

Important: According to Val Town's email documentation, the from field must be either:

• { email: "your_username.valname@valtown.email" } or
• { email: "your_username.valname@valtown.email", name: "Sender Name" }

replyTo: {
  email: "your-email@example.com",
  name: "Your Name"
}

headers: {
  "X-Quiz-Type": "Social Archetype Assessment",
  "X-App-Name": "ssscQuiz", 
  "X-App-Version": "2.0",
  "X-Priority": "3" // 1=High, 3=Normal, 5=Low
}

• VAL_TOWN_API_KEY: Automatically provided by Val Town
• Optional overrides:
  • ADMIN_EMAIL: Admin notification email
  • SITE_URL: Your Val Town site URL
  • HASH_SALT: Unique salt for privacy protection
  • EMAIL_FROM: Override from email address
  • EMAIL_FROM_NAME: Override from display name
  • EMAIL_REPLY_TO: Override reply-to email
  • EMAIL_REPLY_TO_NAME: Override reply-to name

• Lazy Loading: Components loaded as needed
• Efficient Rendering: Optimized React components
• CSS Optimization: Custom properties and efficient selectors
• Database Queries: Indexed and optimized queries

• Manual testing across all user flows
• Cross-browser compatibility testing
• Mobile responsiveness testing
• Email delivery testing

• A/B Testing: Different quiz variations
• Advanced Analytics: User behavior tracking
• Social Features: Community building around archetypes
• API Integration: Connect with event platforms

• Caching: Redis integration for performance
• CDN: Static asset optimization
• Advanced Security: Rate limiting and CSRF protection
• Monitoring: Performance and error tracking