Trusted Surgeon

Appearance

Public App Documentation ​

🏗️ Architecture Overview ​

Technology Stack ​

  • Framework: Next.js 14.2.5 with Pages Router
  • Language: TypeScript 5 for type safety
  • Styling: Tailwind CSS v3.4.4 + SCSS (Sass)
  • UI Components: Custom React components
  • Fonts: Merriweather (headlines) + Inter (body)
  • Dependencies: React 18.3.1, axios, markdown-it
  • Deployment: Vercel-ready with serverless functions

Project Structure ​

apps/public/
├── src/
│   ├── pages/                    # Next.js file-based routing
│   │   ├── index.tsx            # Homepage (/)
│   │   ├── how-it-works.tsx     # How it works (/how-it-works)
│   │   ├── trustedhub.tsx       # TrustedHub (/trustedhub)
│   │   ├── faq.tsx              # FAQ (/faq)
│   │   ├── privacy.tsx          # Privacy Policy (/privacy)
│   │   ├── terms&conditions.tsx # Terms & Conditions (/terms&conditions)
│   │   ├── _app.tsx             # App wrapper with Header/Footer/Chatbot
│   │   └── _document.tsx        # Document wrapper
│   ├── components/              # Reusable components
│   │   ├── Header.tsx           # Navigation header with mobile menu
│   │   ├── Footer.tsx           # Footer component
│   │   ├── Button.tsx           # Button component
│   │   ├── ChatbotWidget.tsx    # AI chatbot with markdown support
│   │   └── MyTrustedHub.tsx     # Hub feature (currently commented out)
│   └── styles/
│       └── globals.scss          # Global styles with design tokens
├── public/                      # Static assets (images, PDFs, etc.)
└── package.json                 # Dependencies

🎯 Application Flow ​

User Journey Architecture ​

The Public App follows a strategic user conversion funnel:

  1. Awareness Stage: Homepage hero section with compelling value proposition
  2. Interest Stage: Interactive features and educational content
  3. Consideration Stage: TrustedHub features and transparent pricing
  4. Action Stage: CTA buttons leading to portal app integration
  5. Conversion Stage: Seamless handoff to portal app for patient intake

Page Flow Architecture ​

Homepage (/) - Primary Entry Point ​

  • Hero Section:
    • Compelling headline "Take control of your surgery"
    • Typewriter effect rotating specialties (CABG, Knee, Hip, Spinal, Cataract surgeons)
    • Animated bubble background
    • Value proposition with $99 pricing
  • Feature Tiles: 6 key benefits with interactive hover effects and scroll animations
  • Interactive Demo: "How Trusted Surgeon Works" with step navigation (3 steps)
  • Sample Report Section: Scroll-triggered animations for report display
  • Why Trusted Surgeon Section: Benefits and value propositions
  • Patient Testimonials: Multiple testimonial cards with scroll animations
  • TrustedHub Section: Secure vault platform features with CTA
  • Pricing Information: Transparent $99 one-time investment
  • CTA Buttons: Primary ("Join the Movement Today") and secondary ("See a Sample Report") action buttons
  • Scroll Animations: Intersection Observer API for fade-in animations

How It Works (/how-it-works) - Educational Content ​

  • Process Overview: 3-step surgical journey explanation
  • Step-by-Step Navigation: Interactive step buttons with visual feedback
  • Detailed Steps: In-depth procedure information for each step
  • Scroll Animations: Intersection Observer for step visibility
  • Report Card Display: Sample report card with scroll-triggered animation
  • Benefits: Why choose Trusted Surgeon platform
  • Data Sources: Transparency about data collection methods
  • Success Stories: Patient testimonials and outcomes

TrustedHub (/trustedhub) - Secure Vault Platform ​

  • Journey Sections:
    • Pre-Surgery section with scroll animations
    • Hospital section with scroll animations
    • Post-Surgery section with scroll animations
  • Feature Cards: 4 feature cards with scroll-triggered animations
  • Hub Features: Document storage and management capabilities
  • Security: Blockchain-based security measures
  • Journey Management: Complete surgical process tracking
  • Integration: Connection with surgeon reports and data
  • Visual Elements: Timeline icons and feature illustrations

FAQ (/faq) - Support Information ​

  • Accordion Interface: Expandable FAQ items with toggle functionality
  • Common Questions: Patient and procedure-related FAQs
  • Platform Usage: How to use Trusted Surgeon effectively
  • TrustedSurgeon & TrustedVault: Detailed explanations of platform features
  • Technical Support: Troubleshooting and help resources
  • CCPA Compliance: California Consumer Privacy Act employee privacy notice
  • Data Collection: Information about data collection practices
  • User Rights: Consumer privacy rights and how to exercise them
  • Contact Information: Privacy-related contact details
  • Terms of Service: Comprehensive terms and conditions
  • Content Formatting: Properly formatted sections with bullet points
  • Legal Sections: Multiple sections covering service usage, liability, etc.

🧩 Component Architecture ​

Core Components ​

Header Component (src/components/Header.tsx) ​

typescript
// Navigation with mobile responsiveness
- Logo with brand link to homepage (Next.js Image component)
- Desktop navigation menu (Home, How it Works, TrustedHub™, FAQs)
- Mobile hamburger menu with responsive design
- CTA buttons (Sign In, Get Started) with portal app integration
- Fixed positioning with backdrop blur effect (bg-white/70 backdrop-blur)
- State management for mobile menu toggle

Key Features:

  • Responsive navigation for all screen sizes
  • Portal app integration via NEXT_PUBLIC_PORTAL_URL environment variable
  • Smooth transitions and hover effects
  • Accessibility support with ARIA labels
  • Mobile menu state management with React hooks

App Wrapper (src/pages/_app.tsx) ​

typescript
// Global app wrapper with shared components
- Header component (fixed on all pages)
- Footer component (fixed on all pages)
- ChatbotWidget component (fixed on all pages)
- Next.js Head component for SEO metadata
- Router integration for page transitions

Key Features:

  • Consistent layout across all pages
  • Global styles via globals.scss import
  • SEO metadata management
  • Shared component structure
typescript
// Multi-column footer with comprehensive site information
- Brand section with logo, tagline, and social media links
- About links (Mission, Team, How It Works, Partnerships)
- Resources (FAQs, Blog, Patient Guide, Glossary)
- Contact information with phone, email, and address
- Legal links (Privacy Policy, Terms of Service, Cookie Policy)

Social Media Integration:

  • Facebook, Twitter, Instagram, LinkedIn icons
  • Hover effects and smooth transitions
  • Responsive grid layout

Button Component (src/components/Button.tsx) ​

typescript
interface ButtonProps {
  children: React.ReactNode;
  variant?: 'outlined' | 'filled';
  onClick?: () => void;
  className?: string;
  style?: React.CSSProperties;
}

Variants:

  • Filled: Turquoise background with white text
  • Outlined: White background with navy border and text
  • Interactive: Hover effects and focus states
  • Accessible: Keyboard navigation and screen reader support

ChatbotWidget Component (src/components/ChatbotWidget.tsx) ​

typescript
// AI-powered chatbot with modal interface
- Fixed position floating button (bottom-right, configurable offset)
- Modal overlay with backdrop
- Message input with send functionality and file upload support
- AI assistant integration via axios API calls
- Markdown rendering for AI responses (markdown-it)
- Message history with user and AI message types
- Typing indicators and loading states
- Mobile responsive design with touch optimization
- Auto-scroll to latest message

Features:

  • Context-aware responses for surgical procedures
  • Markdown support for formatted AI responses
  • Real-time message handling with state management
  • File upload capability for document sharing
  • Message history persistence during session
  • Smooth animations and transitions
  • TypeScript interfaces for type safety (Message interface)

🎨 Design System Architecture ​

Color Palette ​

scss
// Brand Colors - Healthcare-focused palette
$warm-navy: #23395D;        // Primary - Trust, authority, stability
$soft-sand: #F4E9E1;        // Comfort - Approachability, warmth
$turquoise: #00BFA6;        // Secondary - Healing, calm reassurance
$olive-green: #8B9A5B;      // Natural - Health, balance, growth
$coral-accent: #FF6F61;     // Accent - Human connection, care

Typography System ​

scss
// Font Families - Dual-font system for optimal hierarchy
$font-headline: 'Merriweather', serif;  // Trust, authority, headlines
$font-body: 'Inter', sans-serif;       // Readability, modern, body text

// Typography Scale
.headline-1 { font-size: 3.5rem; line-height: 1.1; font-weight: 700; }
.headline-2 { font-size: 2.5rem; line-height: 1.2; font-weight: 700; }
.headline-3 { font-size: 2rem; line-height: 1.3; font-weight: 700; }
.headline-4 { font-size: 1.5rem; line-height: 1.4; font-weight: 700; }
.body-large { font-size: 1.125rem; line-height: 1.6; font-weight: 400; }
.body-regular { font-size: 1rem; line-height: 1.6; font-weight: 400; }

Responsive Design System ​

scss
// Breakpoint System
Mobile: < 640px      // Single column, stacked layout
Tablet: 640px - 1024px  // Two-column layouts
Desktop: > 1024px      // Multi-column, full layouts

// Grid System
.grid-cols-1 sm:grid-cols-2 lg:grid-cols-3  // Responsive grid
.flex flex-col sm:flex-row                  // Responsive flex

🔄 State Management Architecture ​

Local State Management ​

typescript
// React hooks for component-level state
const [howStep, setHowStep] = useState<number>(1);        // Step navigation
const [isOpen, setIsOpen] = useState(false);             // Modal states
const [message, setMessage] = useState('');              // Form inputs
const [showAIInfo, setShowAIInfo] = useState(false);     // UI toggles
const [openItems, setOpenItems] = useState<Set<string>>(new Set()); // FAQ accordion
const [typedText, setTypedText] = useState<string>(''); // Typewriter effect
const [wordIndex, setWordIndex] = useState<number>(0);   // Typewriter word index
const [charIndex, setCharIndex] = useState<number>(0);   // Typewriter char index
const [isDeleting, setIsDeleting] = useState<boolean>(false); // Typewriter direction
const [messages, setMessages] = useState<Message[]>([]); // Chatbot messages
const [isTyping, setIsTyping] = useState(false);        // Chatbot typing state

Global State Patterns ​

  • URL State: Search parameters and navigation state
  • Local Storage: User preferences and settings persistence
  • Session Management: Cross-app authentication state
  • Environment Variables: Portal app URL configuration

State Flow Examples ​

typescript
// Interactive step navigation
const handleStepClick = (step: number) => {
  setHowStep(step);
  // Update UI based on selected step
};

// Chatbot state management
const toggleChatbot = () => {
  setIsOpen(!isOpen);
  if (!isOpen) {
    // Reset states when opening - start fresh session
    setShowAIMessage(false);
    setHasUserMessage(false);
    setMessages([]);
    setIsTyping(false);
  }
};

// Typewriter effect state management
useEffect(() => {
  const typeWriter = () => {
    const currentWord = rotatingSpecialties[wordIndex];
    // Type and delete logic with state updates
  };
  const timer = setTimeout(typeWriter, isDeleting ? 50 : 100);
  return () => clearTimeout(timer);
}, [wordIndex, charIndex, isDeleting, typedText]);

// Scroll animation with Intersection Observer
const useIntersection = (ref: RefObject<HTMLElement>, threshold = 0.1) => {
  const [isVisible, setIsVisible] = useState(false);
  useEffect(() => {
    const observer = new IntersectionObserver(
      ([entry]) => setIsVisible(entry.isIntersecting),
      { threshold }
    );
    if (ref.current) observer.observe(ref.current);
    return () => observer.disconnect();
  }, [ref, threshold]);
  return isVisible;
};

🌐 Integration Architecture ​

Portal App Integration ​

typescript
// Environment-based cross-app navigation
const portalUrl = process.env.NEXT_PUBLIC_PORTAL_URL;

// Authentication flow integration
<a href={`${portalUrl}/sign-in`}>
  Sign In
</a>

// Patient intake integration
<a href={`${portalUrl}/patient-surgery-intake`}>
  Get Started / Join the Movement Today
</a>

Integration Points:

  • Header navigation links to portal app
  • CTA buttons redirect to portal app patient intake
  • Environment variable NEXT_PUBLIC_PORTAL_URL for configuration
  • Seamless handoff from public marketing to portal application

External API Integration ​

  • Chatbot API: AI assistant integration via axios
    • POST requests to chatbot endpoint
    • Markdown response rendering
    • File upload support for document sharing
    • Message history management
  • Analytics: User behavior tracking and conversion monitoring (ready for implementation)

Data Flow Architecture ​

User Interaction → Component State → API Call → Data Processing → UI Update

📱 User Experience Flow ​

Homepage Experience ​

  1. Hero Section:
    • Compelling headline "Take control of your surgery"
    • Typewriter effect with rotating surgeon specialties
    • Animated bubble background
    • Clear value proposition
  2. Feature Tiles: 6 key benefits with interactive hover effects and scroll animations
  3. Interactive Demo: "How Trusted Surgeon Works" with 3-step navigation buttons
  4. Sample Report Section: Scroll-triggered report display with animations
  5. Why Trusted Surgeon: Benefits section with scroll animations
  6. Patient Testimonials: Multiple testimonial cards with staggered scroll animations
  7. TrustedHub Section: Secure vault features and benefits with CTA
  8. Pricing Information: Transparent $99 one-time investment
  9. CTA Buttons: Primary ("Join the Movement Today") and secondary ("See a Sample Report") action buttons

Interactive Elements ​

typescript
// Step navigation with visual feedback
const [howStep, setHowStep] = useState<number>(1);

// Interactive step buttons with active states
<button 
  onClick={() => setHowStep(1)}
  className={`step-button ${howStep === 1 ? 'active' : ''}`}
>
  Step 01
</button>

// Typewriter effect for hero section
const rotatingSpecialties = ['CABG Surgeon', 'Knee Surgeon', 'Hip Surgeon', 'Spinal Surgeon', 'Cataract Surgeon'];
// Auto-typing and deleting effect with cursor animation

// Scroll-triggered animations
const useIntersection = (ref: RefObject<HTMLElement>, threshold = 0.1) => {
  const [isVisible, setIsVisible] = useState(false);
  useEffect(() => {
    const observer = new IntersectionObserver(
      ([entry]) => setIsVisible(entry.isIntersecting),
      { threshold }
    );
    if (ref.current) observer.observe(ref.current);
    return () => observer.disconnect();
  }, [ref, threshold]);
  return isVisible;
};

// FAQ accordion toggle
const toggleItem = (itemId: string) => {
  const newOpenItems = new Set(openItems);
  if (newOpenItems.has(itemId)) {
    newOpenItems.delete(itemId);
  } else {
    newOpenItems.add(itemId);
  }
  setOpenItems(newOpenItems);
};

Mobile Experience Optimization ​

  • Touch-friendly: Minimum 44px touch targets
  • Responsive Layout: Adaptive grid systems and typography
  • Fast Loading: Optimized images and lazy loading
  • Smooth Animations: CSS transitions and transforms
  • Gesture Support: Swipe and touch interactions

🔒 Security Architecture ​

Data Protection ​

  • Input Validation: Sanitize all user inputs and form data
  • HTTPS: Secure communication with SSL/TLS encryption
  • Privacy Controls: User data management and GDPR compliance
  • Cross-Origin Security: Proper CORS configuration for API calls

Authentication Flow ​

typescript
// Secure portal app integration
const handleSignIn = () => {
  // Redirect to portal app for authentication
  window.location.href = `${process.env.NEXT_PUBLIC_PORTAL_URL}/sign-in`;
};

// Session management
const checkAuthStatus = () => {
  const isAuthenticated = localStorage.getItem('isAuthenticated') === 'true';
  return isAuthenticated;
};

⚡ Performance Architecture ​

Optimization Strategies ​

  • Code Splitting: Automatic page-based splitting with Next.js
  • Image Optimization: Next.js Image component with lazy loading
  • Static Generation: Pre-rendered pages where possible
  • CDN: Global content delivery for assets
  • Bundle Optimization: Tree shaking and dead code elimination

Loading Performance ​

typescript
// Image optimization with Next.js
<Image 
  src="/logo.svg" 
  alt="Trusted Surgeon" 
  width={180} 
  height={40}
  className="h-10 w-auto"
  priority // For above-the-fold images
/>

// Lazy loading for below-the-fold content
<Image 
  src="/background.jpg" 
  alt="Background" 
  loading="lazy"
/>

Core Web Vitals Optimization ​

  • LCP (Largest Contentful Paint): Optimize hero section loading
  • FID (First Input Delay): Minimize JavaScript execution time
  • CLS (Cumulative Layout Shift): Prevent layout shifts with proper sizing

🎯 Business Logic Flow ​

User Conversion Funnel ​

  1. Awareness: Homepage hero and feature presentation
  2. Interest: Interactive demo and educational content
  3. Consideration: TrustedHub features and transparent pricing
  4. Action: CTA buttons with clear value proposition
  5. Conversion: Seamless portal app integration

Value Proposition Delivery ​

  • Data-Driven: 30+ proprietary data points analysis
  • Personalized: 5+ top-rated recommended specialists
  • Trusted: TrustedRange™ personalized rating system
  • Secure: TrustedHub™ blockchain-based vault platform
  • Affordable: $99 one-time investment in health

Call-to-Action Strategy ​

typescript
// Primary CTA - Main conversion goal
<a href={`${portalUrl}/patient-surgery-intake`}>
  Join the Movement Today
</a>

// Secondary CTA - Trust building
<a href="/sample-report.pdf" target="_blank">
  See a Sample Report
</a>

📊 Analytics and Monitoring ​

User Behavior Tracking ​

  • Page Views: Navigation patterns and user flow
  • Interaction Events: Button clicks and form submissions
  • Conversion Tracking: CTA button effectiveness and conversion rates
  • Performance Metrics: Core Web Vitals and loading times

Business Intelligence ​

  • User Journey Analysis: Complete conversion funnel tracking
  • Feature Usage: Component interaction and engagement metrics
  • A/B Testing: CTA button optimization and content testing
  • Performance Monitoring: Real-time app performance and error tracking

Analytics Implementation ​

typescript
// Event tracking for user interactions (ready for implementation)
const trackEvent = (eventName: string, properties: Record<string, unknown>) => {
  if (typeof window !== 'undefined' && window.gtag) {
    window.gtag('event', eventName, properties);
  }
};

// Conversion tracking
const trackConversion = (conversionType: string) => {
  trackEvent('conversion', {
    event_category: 'engagement',
    event_label: conversionType,
    value: 1
  });
};

// Chatbot interaction tracking
const trackChatbotMessage = (messageType: 'user' | 'ai') => {
  trackEvent('chatbot_interaction', {
    event_category: 'engagement',
    event_label: messageType
  });
};

🚀 Deployment Architecture ​

Build Process ​

bash
# Development
npm run dev

# Production build
npm run build

# Production server
npm start

Vercel Deployment ​

  • Serverless Functions: API routes as serverless functions
  • Edge Caching: Global CDN caching for optimal performance
  • Automatic Scaling: Handle traffic spikes automatically
  • Preview Deployments: Branch-based preview environments

Environment Configuration ​

env
# Development
NEXT_PUBLIC_PORTAL_URL=http://localhost:5173

# Production
NEXT_PUBLIC_PORTAL_URL=https://portal.trustedsurgeon.ai

🔧 Development Workflow ​

Code Quality ​

  • TypeScript: Type safety and better developer experience
  • ESLint: Code linting and style enforcement
  • Prettier: Code formatting consistency
  • Husky: Git hooks for pre-commit checks

Testing Strategy ​

  • Unit Tests: Component testing with Jest and React Testing Library
  • Integration Tests: Page-level testing and user flow validation
  • E2E Tests: Full user journey testing with Playwright
  • Performance Tests: Core Web Vitals monitoring

Development Tools ​

  • Hot Reload: Fast development with Next.js dev server
  • Type Checking: Real-time TypeScript error detection
  • Source Maps: Debug-friendly development builds
  • Component Library: Reusable component documentation

This comprehensive architecture provides a robust, scalable foundation for the Trusted Surgeon Public App, ensuring optimal user experience, performance, and maintainability.

Trusted Surgeon Platform Documentation

Copyright © 2024 Trusted Surgeon