Trusted Surgeon

Appearance

Portal App Documentation ​

🏗️ Architecture Overview ​

Technology Stack ​

  • Framework: Vite + React 19 with TypeScript
  • Routing: React Router DOM v6 for client-side navigation
  • Styling: Tailwind CSS + SCSS for advanced styling
  • Build Tool: Vite for fast development and optimized builds
  • State Management: React hooks with localStorage persistence
  • Deployment: Vite preview with custom domain configuration

Project Structure ​

apps/portal/
├── src/
│   ├── Pages/                      # Main application pages
│   │   ├── SurgeonsReport.tsx      # Home page - Surgeon search & results
│   │   ├── PatientSurgeryIntake.tsx # Multi-step patient intake form
│   │   ├── DoctorReport.tsx        # Individual doctor profile
│   │   ├── SurgeonComparison.tsx   # Doctor comparison
│   │   ├── MyFolder.tsx           # Document management
│   │   ├── SavedSearch.tsx        # Saved searches
│   │   ├── PricingPage.tsx        # Pricing information
│   │   ├── Settings.tsx            # User settings
│   │   └── SignIn.tsx             # Authentication
│   ├── components/                 # Reusable components
│   │   ├── Header.tsx             # Navigation header
│   │   ├── Footer.tsx             # Footer component
│   │   ├── ProtectedRoute.tsx     # Route protection wrapper
│   │   ├── Cards/                 # Card components
│   │   │   ├── DoctorCard.tsx    # Doctor profile card
│   │   │   ├── SurgeonReport.tsx  # Surgeon report card
│   │   │   ├── Comparison.tsx     # Comparison card
│   │   │   ├── MyFolder.tsx       # Folder card
│   │   │   └── FolderSurgeonReport.tsx # Folder surgeon report
│   │   ├── Form/                  # Form components
│   │   │   └── AboutPatient.tsx   # Patient information form
│   │   ├── DoctorReport/          # Doctor report sections
│   │   │   ├── ExecutiveSummery.tsx
│   │   │   ├── ProcedureCount.tsx
│   │   │   ├── BoardCertification.tsx
│   │   │   ├── Publications.tsx
│   │   │   ├── PatientsReviews.tsx
│   │   │   ├── AcceptedInsurances.tsx
│   │   │   └── ... (other report sections)
│   │   ├── DetailedComparison/     # Comparison detail views
│   │   │   ├── Overview.tsx
│   │   │   ├── ClinicalData.tsx
│   │   │   ├── SurgicalData.tsx
│   │   │   └── ... (other comparison sections)
│   │   ├── MyFolder/              # Folder management components
│   │   │   ├── SavedSearch.tsx
│   │   │   ├── SurgeonReport.tsx
│   │   │   ├── MedicalReport.tsx
│   │   │   └── SubFolder.tsx
│   │   ├── Dropdowns/             # Dropdown components
│   │   │   ├── CustomSelect.tsx
│   │   │   ├── ActionMenu.tsx
│   │   │   └── SaveSearchFolder.tsx
│   │   ├── Models/                # Modal components
│   │   │   ├── CreateNewFolder.tsx
│   │   │   ├── ShareFolder.tsx
│   │   │   ├── PlanPurchaseSuccessPopUp.tsx
│   │   │   └── ... (other modals)
│   │   ├── Reports/               # Report components
│   │   │   └── SurgerySummaryReport.tsx
│   │   ├── ChatBot/               # AI chatbot
│   │   │   └── ChatbotWidget.tsx
│   │   └── Breadcrumps/           # Breadcrumb navigation
│   │       └── Breadcrumps.tsx
│   ├── contexts/                  # React contexts
│   │   └── AuthContext.tsx        # Authentication context
│   ├── service/                   # API service layer
│   │   ├── surgeonService.ts      # Surgeon data API
│   │   ├── procedureService.ts   # Procedure data API
│   │   ├── userService.ts         # User management API
│   │   └── ... (other services)
│   ├── assets/                    # Static assets
│   └── utils/                     # Utility functions
├── public/                        # Public assets
└── package.json                   # Dependencies

🎯 Application Flow ​

User Journey Architecture ​

The Portal App follows a comprehensive patient journey from initial search to detailed surgeon analysis:

  1. Home/Discovery Stage: Surgeons Report page (home page) with search filters and results
  2. Intake Stage: Multi-step patient surgery intake form
  3. Results Stage: Surgeons report with filtering, pagination, and comparison
  4. Analysis Stage: Individual doctor reports and detailed comparisons
  5. Management Stage: Saved searches and document organization
  6. Authentication: Sign-in and user management

Page Flow Architecture ​

Surgeons Report (/ or /surgeons-report) - Home Page ​

  • Primary Entry Point: Main landing page for authenticated users
  • Search Interface: Comprehensive search form with filters (visible when subscribed)
  • Filter Options: Surgery type, CPT code, location (ZIP/State), experience level, research publications, insurance provider
  • Search Results: Paginated grid of surgeon cards with key metrics
  • Comparison Feature: Select up to 3 surgeons (desktop) or 2 surgeons (mobile) for comparison
  • Save Search: Save search criteria for future use
  • Subscription-Based: Filters and full results visible only to subscribed users
  • Navigation: Seamless flow to detailed reports via "View Detailed Profile"
  • Pagination: Efficient navigation through large result sets

Patient Surgery Intake (/patient-surgery-intake) ​

  • Multi-Step Form: 3-step progressive form
  • Step 1 - About Patient: Personal information and contact details
  • Step 2 - About Surgery: Procedure details and medical history
  • Step 3 - Surgeon Preferences: Specific surgeon requirements
  • Progress Tracking: Visual progress bar with step indicators
  • Data Persistence: Form data saved to localStorage

Doctor Report (/doctor-report) ​

  • Comprehensive Profile: Detailed surgeon information
  • Performance Metrics: Trust scores, experience, outcomes
  • Clinical Data: Publications, certifications, affiliations
  • Patient Reviews: Verified patient feedback
  • Insurance Information: Accepted insurance providers

Surgeon Comparison (/surgeon-comparison) ​

  • Side-by-Side Analysis: Detailed comparison of selected surgeons (2-3 surgeons)
  • Overview Tab: High-level metrics comparison
  • Detailed Tab: Comprehensive data analysis across multiple categories
  • Procedure Context: Displays procedure name for which comparison is made
  • Navigation: Direct links to individual surgeon reports
  • Decision Support: Data-driven recommendations

My Folder (/my-folder) ​

  • Document Management: Organize surgeon reports, saved searches, and medical reports
  • Folder Structure: Create and manage custom folders with subfolders
  • File Organization: Categorize documents by procedure, surgeon, or custom categories
  • Content Types: Saved searches, surgeon reports, medical reports, surgery summaries
  • Move Functionality: Move items between folders
  • Sharing: Secure sharing with healthcare providers
  • Authentication: Protected access to personal documents
  • Saved Searches: View and manage previously saved search criteria
  • Search Execution: Re-run saved searches to get updated results
  • Surgeon Results: Display surgeons matching saved search criteria
  • Comparison: Select surgeons from saved search results for comparison
  • Folder Management: Organize saved searches into folders

Settings (/settings) ​

  • User Settings: Manage user account and preferences
  • Profile Management: Update user information

Pricing Page (/pricing) ​

  • Subscription Plans: View available subscription tiers
  • Feature Comparison: Compare features across plans
  • Purchase Flow: Subscribe to access full features

Surgery Summary (/surgery-summary) ​

  • Surgery Reports: View comprehensive surgery summary reports
  • Report Details: Detailed information about surgical procedures

🧩 Component Architecture ​

Core Components ​

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

typescript
// Dynamic navigation with authentication state
- Logo with public app integration
- Authentication-aware navigation
- User profile display
- Mobile responsive navigation
- Route-based authentication checks

Key Features:

  • Authentication State Management: Dynamic header based on user login status
  • Route Protection: Automatic redirects for protected pages
  • Public App Integration: Logo click redirects to public app
  • User Context: Display user name and authentication status
typescript
// Comprehensive footer with multi-column layout
- Brand section with logo and social links
- About links (Mission, Team, How It Works)
- Resources (FAQs, Blog, Patient Guide)
- Contact information with phone and email
- Legal links (Privacy, Terms, Cookies)

DoctorCard Component (src/components/Cards/DoctorCard.tsx) ​

typescript
interface DoctorCardProps {
  name: string;
  specialty: string;
  location?: string;
  avatarUrl?: string;
  topBadge?: string;
  trustScore?: number;
  experienceYears?: number | string;
  cabgProcedures?: number | string;
  publications?: number | string;
  seen?: boolean;
  onViewProfile?: () => void;
  onSelect?: () => void;
  isSelected?: boolean;
}

Features:

  • Star Rating System: Visual trust score display
  • Selection State: Checkbox for comparison selection
  • Interactive Elements: Hover effects and click handlers
  • Responsive Design: Mobile-optimized layout
  • Data Display: Comprehensive surgeon metrics

Form Components (src/components/Form/) ​

typescript
// Patient intake form with validation and persistence
- AboutPatient: Comprehensive patient information form including:
  - Personal information and contact details
  - Surgery type and timing
  - Medical history and preferences
  - Surgeon preferences (gender, ethnicity, distance)
  - Insurance information
- Form validation with real-time feedback
- localStorage persistence for form data
- Error handling with proper TypeScript types (no 'any' types)

Advanced Components ​

SurgeonComparison Component ​

typescript
// Detailed surgeon comparison interface
- Overview tab with key metrics
- Detailed tab with comprehensive data
- Side-by-side analysis
- Decision support tools
- Export and sharing capabilities

MyFolder Component ​

typescript
// Document management system
- Folder creation and organization
- File categorization
- Secure sharing
- Authentication protection
- Search and filtering

🎨 Design System Architecture ​

Color Palette ​

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

Typography System ​

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

// 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; }
.body-large { font-size: 1.125rem; line-height: 1.6; font-weight: 400; }

Component Styling ​

scss
// Healthcare card styling
.healthcare-card {
  background: #ffffff;
  border-radius: 12px;
  box-shadow: 0 4px 6px -1px rgba(0, 0, 0, 0.1);
  border: 1px solid #e5e7eb;
}

// Form input styling
.input-base {
  width: 100%;
  height: 44px;
  border-radius: 6px;
  border: 1px solid #d1d5db;
  padding: 0 12px;
  font-size: 14px;
  color: #1f2937;
  background: #ffffff;
  transition: all 0.2s ease;
}

🔄 State Management Architecture ​

Local State Management ​

typescript
// React hooks for component-level state
const [currentStep, setCurrentStep] = useState(1);        // Form navigation
const [isSubscribed, setIsSubscribed] = useState(false);  // Subscription status
const [selectedSurgeons, setSelectedSurgeons] = useState([]);  // Comparison
const [formData, setFormData] = useState({});            // Form data
const [surgeons, setSurgeons] = useState<DoctorDisplay[]>([]); // Surgeon results
const [isContentBlurred, setIsContentBlurred] = useState(false); // Content visibility

Global State Patterns ​

  • Authentication State: Managed via AuthContext with AuthProvider
  • Subscription State: User subscription status affecting feature visibility
  • Form Data Persistence: Multi-step form data in localStorage
  • Search State: Search filters, results, and pagination state
  • Navigation State: Custom routing with popstate events
  • Content Blurring: Subscription-based content visibility control

Data Persistence ​

typescript
// Form data persistence
useEffect(() => {
  const saved = localStorage.getItem('patientForm.aboutPatient');
  if (saved) {
    const parsed = JSON.parse(saved);
    setFormData(prev => ({ ...prev, ...parsed }));
  }
}, []);

// Authentication state persistence
const checkAuthStatus = () => {
  const token = localStorage.getItem('token');
  const authToken = localStorage.getItem('auth_token');
  const user = localStorage.getItem('user');
  const hasAccess = localStorage.getItem('hasAccessToReports') === 'true';
  return { token, authToken, user, hasAccess };
};

// Subscription state persistence
const checkSubscription = async () => {
  const userData = localStorage.getItem('user');
  const localSubscribed = userData ? JSON.parse(userData).is_subscribed : false;
  const apiSubscribed = await userService.checkSubscriptionStatus();
  return apiSubscribed || localSubscribed;
};

🌐 Integration Architecture ​

Public App Integration ​

typescript
// Cross-app navigation
const handleLogoClick = () => {
  const publicAppUrl = import.meta.env.VITE_PUBLIC_APP_URL || "https://trustedsurgeon.ai/";
  window.location.href = publicAppUrl;
};

Backend API Integration ​

  • Surgeon Service (surgeonService.ts):

    • Search surgeons with filters (surgery type, location, experience, etc.)
    • Get individual surgeon details
    • Pagination support
    • ZIP code expansion for nearby locations

  • Procedure Service (procedureService.ts):

    • Get available surgery types
    • Get CPT codes for surgery types

  • User Service (userService.ts):

    • Check subscription status
    • User management
    • Authentication state management

  • Patient Service: Patient intake form submission

  • Auth Service: Login and authentication

Data Flow Architecture ​

User Interaction → Component State → API Call → Data Processing → UI Update
                                                      ↓
                                            Subscription Check → Content Visibility

📱 User Experience Flow ​

Multi-Step Form Experience ​

  1. Step 1 - About Patient: Personal information collection
  2. Step 2 - About Surgery: Medical history and procedure details
  3. Step 3 - Surgeon Preferences: Specific surgeon requirements
  4. Progress Tracking: Visual progress bar with step indicators
  5. Data Validation: Real-time form validation with error messages
  6. Persistence: Form data saved automatically to localStorage

Search and Discovery Experience ​

  1. Home Page: Surgeons Report page serves as the main entry point
  2. Search Interface: Comprehensive filter options (visible when subscribed)
  3. Filter Options: Surgery type, CPT code, location, experience, publications, insurance
  4. Results Display: Paginated grid of surgeon cards with key metrics
  5. Content Visibility: Subscription-based content blurring for non-subscribed users
  6. Comparison: Select 2-3 surgeons for side-by-side analysis
  7. Actions: Save searches, view detailed profiles, compare surgeons
  8. Pagination: Navigate through large result sets efficiently

Document Management Experience ​

  1. Folder Creation: Organize documents by procedure or surgeon
  2. File Organization: Categorize and tag documents
  3. Sharing: Secure sharing with healthcare providers
  4. Search: Find specific documents quickly
  5. Authentication: Protected access to personal documents

🔒 Security Architecture ​

Authentication Flow ​

typescript
// ProtectedRoute component wraps authenticated pages
const ProtectedRoute: React.FC<ProtectedRouteProps> = ({ children }) => {
  const { isAuthenticated, isLoading } = useAuth();
  
  useEffect(() => {
    const hasToken = !!localStorage.getItem('token');
    const hasUser = !!localStorage.getItem('user');
    const hasAccess = localStorage.getItem('hasAccessToReports') === 'true';
    
    if (!isAuthenticated && !isLoading && !hasToken && !hasAccess) {
      window.history.pushState({}, '', '/signin');
      window.dispatchEvent(new PopStateEvent('popstate'));
    }
  }, [isAuthenticated, isLoading]);
  
  if (isLoading || !isAuthenticated) {
    return <LoadingFallback />;
  }
  
  return <>{children}</>;
};

// Protected routes (require authentication)
const protectedRoutes = [
  '/',
  '/surgeons-report',
  '/doctor-report',
  '/surgeon-comparison',
  '/saved-search',
  '/my-folder',
  '/pricing',
  '/settings',
  '/surgery-summary'
];

// Public routes (no authentication required)
const publicRoutes = [
  '/signin',
  '/sign-in',
  '/patient-surgery-intake'
];

Subscription-Based Access Control ​

  • Free Users: Limited access, blurred content, feature cards
  • Subscribed Users: Full access to filters, search results, and detailed reports
  • Content Blurring: Non-subscribed users see blurred surgeon cards
  • Feature Gating: Filters and advanced features only visible to subscribers

Data Protection ​

  • Input Validation: Comprehensive form validation
  • Data Sanitization: Clean user inputs before processing
  • Secure Storage: Encrypted localStorage for sensitive data
  • Route Protection: Authentication-based page access

⚡ Performance Architecture ​

Vite Optimization ​

typescript
// Vite configuration
export default defineConfig({
  plugins: [react()],
  preview: {
    allowedHosts: ['app.trustedsurgeon.ai'],
  },
  build: {
    rollupOptions: {
      output: {
        manualChunks: {
          vendor: ['react', 'react-dom'],
          router: ['react-router-dom']
        }
      }
    }
  }
});

Code Splitting ​

  • Route-based Splitting: Each page loads only necessary code
  • Component Lazy Loading: Load components on demand
  • Asset Optimization: Optimized images and static assets
  • Bundle Analysis: Monitor bundle size and performance

Performance Optimization ​

typescript
// Image optimization
<img 
  src={profileImage} 
  alt={name}
  loading="lazy"
  className="w-16 h-16 rounded-full object-cover"
/>

// Efficient re-renders
const memoizedComponent = React.memo(Component);

🎯 Business Logic Flow ​

Patient Journey Management ​

  1. Discovery: Find surgeons based on specific criteria
  2. Intake: Collect comprehensive patient information
  3. Analysis: Detailed surgeon analysis and comparison
  4. Decision: Data-driven surgeon selection
  5. Management: Organize and share documents

Data-Driven Decision Making ​

  • Trust Score System: Comprehensive surgeon rating
  • Performance Metrics: Real surgical outcomes and data
  • Comparison Tools: Side-by-side surgeon analysis
  • Recommendation Engine: AI-powered surgeon matching

Value Proposition Delivery ​

  • Comprehensive Data: 30+ data points per surgeon
  • Personalized Results: Tailored surgeon recommendations
  • Transparent Metrics: Clear performance indicators
  • Secure Management: TrustedHub™ document vault

📊 Analytics and Monitoring ​

User Behavior Tracking ​

  • Form Completion: Track multi-step form progress
  • Search Patterns: Monitor search behavior and filters
  • Comparison Usage: Track surgeon comparison interactions
  • Document Management: Monitor folder and file usage

Business Intelligence ​

  • Conversion Funnel: Track user journey from search to decision
  • Feature Usage: Monitor component interaction rates
  • Performance Metrics: Track page load times and user experience
  • Error Monitoring: Real-time error tracking and resolution

Analytics Implementation ​

typescript
// Event tracking for user interactions
const trackFormStep = (step: number, data: Record<string, unknown>) => {
  console.log(`Form step ${step} completed:`, data);
  // Send to analytics service
};

// Search tracking
const trackSearch = (filters: SurgeonSearchParams, results: number) => {
  console.log('Search performed:', { filters, results });
  // Track search effectiveness
};

// Subscription tracking
const trackSubscription = (plan: string, status: string) => {
  console.log('Subscription event:', { plan, status });
  // Track subscription conversions
};

🚀 Deployment Architecture ​

Build Process ​

bash
# Development
npm run dev

# Production build
npm run build

# Preview
npm run preview

Vite Configuration ​

  • Fast Development: Hot module replacement
  • Optimized Builds: Tree shaking and code splitting
  • Asset Optimization: Image and static asset optimization
  • Custom Domain: Configured for app.trustedsurgeon.ai

Environment Configuration ​

env
# Development
VITE_PUBLIC_APP_URL=http://localhost:3000

# Production
VITE_PUBLIC_APP_URL=https://trustedsurgeon.ai

🔧 Development Workflow ​

Code Quality ​

  • TypeScript: Type safety and better developer experience
  • ESLint: Code linting and style enforcement
  • React Hooks: Modern React patterns
  • Component Architecture: Reusable and maintainable components

Testing Strategy ​

  • Component Testing: Individual component testing
  • Integration Testing: Page-level testing
  • User Flow Testing: End-to-end user journey testing
  • Performance Testing: Load time and responsiveness testing

Development Tools ​

  • Vite Dev Server: Fast development with HMR
  • TypeScript: Real-time type checking
  • React DevTools: Component debugging
  • Browser DevTools: Performance monitoring

📋 Component Library ​

Form Components ​

  • AboutPatient: Comprehensive patient information collection form
    • Personal details, contact information
    • Surgery type, timing, and preferences
    • Surgeon preferences (gender, ethnicity, distance)
    • Insurance and medical history
  • CustomSelect: Dropdown with search functionality
  • Form Validation: Real-time validation with error messages
  • Type Safety: All form components use proper TypeScript types (no 'any' types)

Card Components ​

  • DoctorCard: Surgeon profile display
  • ComparisonCard: Side-by-side surgeon comparison
  • FolderCard: Document organization
  • ReportCard: Detailed surgeon reports
  • Header: Dynamic navigation with authentication
  • Footer: Comprehensive site information
  • Breadcrumbs: Page navigation context
  • Pagination: Large dataset navigation
  • CreateNewFolder: Folder creation interface
  • ShareFolder: Document sharing functionality
  • SaveSearch: Search saving interface
  • ReportSuccessfullyMoved: Confirmation modals

This comprehensive architecture provides a robust, scalable foundation for the Trusted Surgeon Portal App, ensuring optimal user experience, performance, and maintainability for the complete patient journey from discovery to decision-making.

Trusted Surgeon Platform Documentation

Copyright © 2024 Trusted Surgeon