Skip to main content

Development Guide

This guide provides information for developers working on the LyfeAI Provider project.

⚠️ Current State: This is a development/demonstration platform. Some commands and features mentioned in aspirational documentation may not exist.

Getting Started​

Prerequisites​

Before you begin, ensure you have the following installed:

  • Node.js (v18.0.0 or higher)
  • npm (pnpm was removed due to Vercel deployment issues)
  • Git
  • VS Code (recommended) or your preferred IDE

Initial Setup​

  1. Clone the repository
git clone https://github.com/SkaFld-Ignite/lyfe-provider-ui.git
cd lyfe-provider-ui
  1. Install dependencies
npm install
  1. Set up environment variables

Create a .env.local file:

# Supabase (Required for database)
NEXT_PUBLIC_SUPABASE_URL=your_supabase_url
NEXT_PUBLIC_SUPABASE_ANON_KEY=your_supabase_anon_key
SUPABASE_SERVICE_ROLE_KEY=your_service_role_key

# OpenAI (Optional - app works without it)
OPENAI_KEY=your_openai_api_key  # Note: Not OPENAI_API_KEY

# Application
NEXT_PUBLIC_APP_URL=http://localhost:3000

Note: The application works without OpenAI key - it will use simulated AI responses.

  1. Run development server
npm run dev

Visit http://localhost:3000 to see the application.

Auto-login: The admin account ([email protected]) automatically logs in for demo convenience.

Project Structure​

lyfe-provider-ui/
├── app/                    # Next.js App Router pages
│   ├── actions/           # Server actions (some mock, some real)
│   ├── admin/            # Admin pages
│   ├── patients/         # Patient management
│   └── layout.tsx        # Root layout with auth
├── components/            # React components
│   ├── ui/               # shadcn/ui components
│   └── (features)/       # Feature components (many UI-only)
├── lib/                   # Utilities and services
│   ├── ai-service.ts     # AI integration (with fallback)
│   ├── mock-users.ts     # Mock authentication data
│   ├── data.ts           # Mock data for demos
│   └── utils.ts          # Helper functions
├── hooks/                 # Custom React hooks
├── types/                 # TypeScript definitions
├── public/                # Static assets
├── scripts/               # Database SQL scripts
├── docs/                  # Documentation (Docusaurus)
└── internal_comms/        # Internal handoff docs

Available Scripts​

Main Application​

npm run dev        # Start development server
npm run build      # Build for production
npm run start      # Start production server
npm run lint       # Run ESLint

Documentation​

npm run docs:start   # Start documentation dev server
npm run docs:build   # Build documentation
npm run docs:serve   # Serve built documentation

Scripts NOT Available (mentioned in some docs)​

  • ❌ npm run test - No tests configured
  • ❌ npm run type-check - Use npm run build instead
  • ❌ npm run format - No formatter configured
  • ❌ npm run generate:types - No type generation

Development Workflow​

1. Understanding the Codebase​

Fully Implemented Features:

  • Patient CRUD operations
  • FHIR data import
  • AI document processing (with OpenAI key)
  • Basic role-based UI

UI-Only Features (Mock Data):

  • Orders & Results
  • Communication/Chat
  • Analytics Dashboard
  • Smart Scheduling

2. Working with Mock Data​

Most features use mock data from lib/data.ts:

// Example: Mock orders
export const mockOrders = [
  {
    id: "1",
    patientId: "sarah-j-thompson",
    type: "lab",
    name: "Comprehensive Metabolic Panel",
    status: "pending",
    // ... mock data
  }
];

3. Server Actions​

Server actions are mixed - some work with real database, others return mock data:

// Real database operation (patient-actions.ts)
export async function createPatient(data) {
  const supabase = createClient();
  const { data: patient, error } = await supabase
    .from('patients')
    .insert(data);
  return { patient, error };
}

// Mock operation (communication-actions.ts)
export async function sendMessage() {
  // Returns simulated response
  return {
    success: true,
    message: { id: '123', content: 'Demo message' }
  };
}

4. AI Integration​

The AI service works with or without OpenAI:

// lib/ai-service.ts
if (!process.env.OPENAI_KEY) {
  // Returns simulated AI response
  return simulateExtraction(documentContent);
}
// Otherwise uses real OpenAI API

5. Authentication​

Uses mock authentication with localStorage:

// lib/use-auth.ts
// Demo users from lib/mock-users.ts:
// - [email protected] (auto-login)
// - [email protected]
// - [email protected]
// - [email protected]

Database Setup​

Using Existing Supabase Database​

  1. Get credentials from Supabase dashboard
  2. Add to .env.local
  3. Tables should already exist

Creating New Database​

Run SQL scripts in order:

# In Supabase SQL editor, run each script:
1. 01_create_tables.sql
2. 02_create_views.sql (may fail due to missing tables)
3. 03_create_policies.sql
4. 04_insert_sample_data.sql

Note: Only 5 tables are implemented:

  • users
  • patients
  • patient_problems
  • patient_medications
  • patient_allergies

Common Development Tasks​

Adding a New Page​

  1. Create page in app/your-page/page.tsx:
export default function YourPage() {
  return (
    <div className="container mx-auto py-6">
      <h1 className="text-3xl font-bold">Your Page</h1>
    </div>
  );
}
  1. Page automatically uses app shell with navigation

Adding UI Components​

Using shadcn/ui:

npx shadcn-ui@latest add dialog

Creating Mock Features​

For demo purposes:

// 1. Create mock data
const mockData = [
  { id: 1, name: "Demo Item" }
];

// 2. Create server action that returns mock data
export async function getDemoData() {
  return { success: true, data: mockData };
}

// 3. Use in component
const data = await getDemoData();

Troubleshooting​

Common Issues​

  1. "Module not found" errors

    rm -rf node_modules package-lock.json
    npm install

  2. Build errors with date-fns

    • Already fixed with .npmrc legacy-peer-deps
    • If persists, check package.json for version conflicts

  3. Supabase connection errors

    • Verify environment variables
    • Check Supabase dashboard for status
    • App works without Supabase for UI demos

  4. TypeScript errors

    • Run npm run build to see all errors
    • Many any types used for rapid development

Debugging Tips​

  1. Check browser console - Most errors appear there
  2. Check terminal - Server-side errors show here
  3. Use console.log - Works in both server and client components
  4. Check Network tab - See actual API calls (many return mock data)

Deployment​

Vercel Deployment​

The project is configured for Vercel:

// Build settings (automatic)
Build Command: npm run build
Output Directory: .next
Install Command: npm install

Environment variables needed in Vercel:

  • All from .env.local
  • Ensure URLs use production domains

Important Notes​

  1. This is a demo system - Not production-ready
  2. Mock auth - No real security
  3. Mixed implementation - Some features real, many mocked
  4. UI-focused - Great for demonstrations
  5. Database optional - Many features work without it

Contributing​

When adding features:

  1. Check if it should be real or mock
  2. Follow existing patterns
  3. Update documentation if adding real functionality
  4. Keep UI consistent with existing design

Getting Help​

  1. Check /docs/handoff/ for project state
  2. Review code comments
  3. Look at existing implementations for patterns
  4. Most "complex" features are actually simple UI with mock data