# NeoScan Radiologist App

> **A comprehensive React Native application designed for radiologists to review AI-powered medical imaging predictions, validate diagnostic accuracy, and provide clinical feedback to improve AI performance.**

*Design & Developed by Tech4Biz Solutions*  
*Copyright (c) Spurrin Innovations. All rights reserved.*

---

## 📋 Table of Contents

- [🚀 Overview](#-overview)
- [🏗️ Project Architecture](#️-project-architecture)
- [🔄 Project Flow & User Journey](#-project-flow--user-journey)
- [🛠️ Technology Stack](#️-technology-stack)
- [📱 Core Features](#-core-features)
- [🔧 Development Setup](#-development-setup)
- [📁 Project Structure](#-project-structure)
- [🎨 Design System](#-design-system)
- [🔐 Security & Authentication](#-security--authentication)
- [📊 Data Flow & State Management](#-data-flow--state-management)
- [📦 Building & Deployment](#-building--deployment)
- [🚨 Troubleshooting](#-troubleshooting)
- [📞 Support & Documentation](#-support--documentation)

---

## 🚀 Overview

NeoScan Radiologist App is a specialized mobile application that bridges the gap between AI-powered medical imaging analysis and expert radiologist validation. The app enables radiologists to:

- **Review AI Predictions**: Analyze automated diagnostic findings with confidence scores
- **Validate Clinical Accuracy**: Provide expert feedback on AI-generated results
- **Access DICOM Images**: View high-resolution medical imaging files
- **Track Performance**: Monitor AI improvement through feedback analytics
- **Manage Cases**: Organize and prioritize patient cases for review

---

## 🏗️ Project Architecture

### High-Level Architecture
```
┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   React Native  │    │   Redux Store   │    │   API Services  │
│     App Layer   │◄──►│   (State Mgmt)  │◄──►│   (Backend)     │
└─────────────────┘    └─────────────────┘    └─────────────────┘
         │                       │                       │
         ▼                       ▼                       ▼
┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│  Native Modules │    │  Local Storage  │    │  DICOM Viewer   │
│ (iOS/Android)   │    │  (Redux Persist)│    │  (WebView)      │
└─────────────────┘    └─────────────────┘    └─────────────────┘
```

### Module-Based Architecture
The app follows a **feature-based modular architecture** where each major feature is self-contained:

- **Auth Module**: Authentication, registration, and user management
- **Dashboard Module**: Analytics, statistics, and overview
- **PatientCare Module**: Patient data, case management, and DICOM viewing
- **Settings Module**: User preferences and app configuration

---

## 🔄 Project Flow & User Journey

### 1. **Authentication Flow**
```
App Launch → Check Authentication → Login/Register → Dashboard
     │              │                    │            │
     ▼              ▼                    ▼            ▼
  Splash Screen → Auth Check → Login Screen → Main App
```

**Registration Process:**
1. **Self-Registration**: User enters email → Password creation → Personal info → Hospital ID upload → Hospital selection → Wait for admin approval
2. **Admin-Created**: Admin creates account → Credentials sent via email → User logs in → Hospital ID upload → Password reset → Access granted

### 2. **Main Application Flow**
```
Dashboard → Patient List → Case Selection → DICOM Review → AI Analysis → Feedback Submission
    │            │            │              │            │            │
    ▼            ▼            ▼              ▼            ▼            ▼
Overview → Filter Cases → Open Case → View Images → Review AI → Submit Validation
```

**Case Review Workflow:**
1. **Select Case**: Choose from patient queue or search
2. **View DICOM**: Access medical imaging files
3. **Review AI**: Analyze AI predictions and confidence scores
4. **Provide Feedback**: Submit validation (Agree/Partially Agree/Disagree)
5. **Add Notes**: Optional clinical observations
6. **Complete Review**: Case marked as reviewed

### 3. **Data Flow**
```
API Request → Redux Action → State Update → UI Re-render → User Interaction → Feedback → API Update
```

---

## 🛠️ Technology Stack

### **Frontend Framework**
- **React Native 0.79.0**: Cross-platform mobile development
- **TypeScript 5.x**: Type-safe development with strict typing
- **React Navigation 6**: Navigation management and routing

### **State Management**
- **Redux Toolkit**: Modern Redux with simplified patterns
- **Redux Persist**: Local storage for offline capability
- **React Redux Hooks**: Typed hooks for state access

### **UI & Styling**
- **React Native Vector Icons**: Comprehensive icon library
- **Custom Theme System**: Consistent design tokens and components
- **Responsive Design**: Adaptive layouts for different screen sizes

### **Native Integration**
- **WebView**: DICOM image viewing with Cornerstone.js
- **AsyncStorage**: Local data persistence
- **Push Notifications**: Real-time alerts and updates

### **Development Tools**
- **Metro Bundler**: React Native bundler
- **ESLint + Prettier**: Code quality and formatting
- **Jest**: Unit testing framework
- **TypeScript Compiler**: Static type checking

---

## 📱 Core Features

### **🔐 Authentication & Security**
- **Dual Registration Paths**: Self-registration or admin-created accounts
- **Hospital Integration**: Institution-based access control
- **ID Verification**: Secure credential upload and verification
- **Admin Approval System**: Account activation requires approval
- **Secure Storage**: Encrypted credential management

### **📊 Dashboard & Analytics**
- **Validation Metrics**: Total predictions reviewed and accuracy rates
- **Performance Tracking**: AI confidence score analysis
- **Quality Assurance**: Monitor AI performance trends
- **Real-time Updates**: Live data synchronization

### **🔍 AI Prediction Review**
- **Comprehensive Analysis**: Review automated diagnostic predictions
- **Confidence Assessment**: Evaluate AI confidence scores (e.g., 98.6%)
- **Finding Categories**: Stroke detection, hemorrhage analysis, anatomical findings
- **Severity Classification**: High/Medium/Low risk stratification

### **🖼️ DICOM Image Viewer**
- **Series Navigation**: Browse through multiple image series
- **AI Overlay Integration**: Compare predictions with actual scans
- **Finding Localization**: Precise visualization of pathological findings
- **Image Controls**: Zoom, pan, and navigation tools

### **📝 Advanced Feedback System**
- **Binary Validation**: Positive (✅) or Negative (❌) feedback
- **Clinical Notes**: Detailed observations and suggestions
- **Performance Improvement**: Feedback data enhances AI accuracy
- **Quality Metrics**: Continuous validation performance tracking

---

## 🔧 Development Setup

### **Prerequisites**

#### **System Requirements**
- **Operating System**: macOS (for iOS development) or Windows/Linux (for Android)
- **Node.js**: Version 18.0.0 or higher
- **RAM**: Minimum 8GB, recommended 16GB
- **Storage**: At least 10GB free space

#### **Required Software**
- **Node.js & npm**: [Download from nodejs.org](https://nodejs.org/)
- **Git**: [Download from git-scm.com](https://git-scm.com/)
- **React Native CLI**: Install globally with `npm install -g @react-native-community/cli`

#### **Platform-Specific Requirements**

**For Android Development:**
- **Android Studio**: [Download from developer.android.com](https://developer.android.com/studio)
- **Android SDK**: API level 21 (Android 5.0) or higher
- **Java Development Kit (JDK)**: Version 11 or 17
- **Android Emulator**: For testing without physical device

**For iOS Development (macOS only):**
- **Xcode**: Latest version from Mac App Store
- **iOS Simulator**: For testing without physical device
- **CocoaPods**: Install with `sudo gem install cocoapods`

### **Installation Steps**

#### **1. Clone the Repository**
```bash
# Clone the project
git clone <repository-url>
cd NeoScan_Radiologist

# Verify the structure
ls -la
```

#### **2. Install Dependencies**
```bash
# Install Node.js dependencies
npm install

# Install iOS dependencies (macOS only)
cd ios && pod install && cd ..
```

#### **3. Environment Configuration**
```bash
# Copy environment template
cp .env.example .env

# Edit environment variables
nano .env
```

**Required Environment Variables:**
```env
# API Configuration
API_BASE_URL=https://api.neoscan.com
API_TIMEOUT=30000

# Authentication
AUTH_TOKEN_KEY=neoscan_auth_token
REFRESH_TOKEN_KEY=neoscan_refresh_token

# DICOM Viewer
DICOM_VIEWER_URL=https://viewer.neoscan.com
```

#### **4. Start Development Server**
```bash
# Start Metro bundler
npm start

# In a new terminal, run on device/simulator
npm run android    # For Android
npm run ios        # For iOS (macOS only)
```

### **First-Time Setup Checklist**

- [ ] Node.js and npm installed
- [ ] React Native CLI installed globally
- [ ] Repository cloned successfully
- [ ] Dependencies installed (`npm install`)
- [ ] Environment file configured (`.env`)
- [ ] Platform-specific tools installed (Android Studio/Xcode)
- [ ] Development server starts without errors
- [ ] App runs on device/simulator

---

## 📁 Project Structure

```
NeoScan_Radiologist/
├── 📱 app/                          # Main application code
│   ├── 🎯 modules/                  # Feature-based modules
│   │   ├── 🔐 Auth/                 # Authentication & user management
│   │   │   ├── components/          # UI components
│   │   │   ├── screens/             # Screen components
│   │   │   ├── redux/               # State management
│   │   │   ├── services/            # API services
│   │   │   └── types/               # Type definitions
│   │   ├── 📊 Dashboard/            # Analytics & overview
│   │   │   ├── components/          # Dashboard components
│   │   │   ├── screens/             # Dashboard screens
│   │   │   ├── redux/               # Dashboard state
│   │   │   └── hooks/               # Custom hooks
│   │   ├── 👥 PatientCare/          # Patient & case management
│   │   │   ├── components/          # Patient components
│   │   │   ├── screens/             # Patient screens
│   │   │   ├── redux/               # Patient state
│   │   │   └── services/            # Patient API services
│   │   └── ⚙️ Settings/             # App configuration
│   │       ├── components/          # Settings components
│   │       ├── screens/             # Settings screens
│   │       └── redux/               # Settings state
│   ├── 🔧 shared/                   # Shared utilities & components
│   │   ├── components/              # Reusable UI components
│   │   │   ├── CustomModal.tsx      # Modal component
│   │   │   ├── ComingSoonScreen.tsx # Placeholder screen
│   │   │   ├── DicomViewer.tsx      # DICOM image viewer
│   │   │   └── DicomViewerModal.tsx # DICOM viewer modal
│   │   ├── utils/                   # Utility functions
│   │   │   ├── api.ts               # API utilities
│   │   │   ├── constants.ts         # App constants
│   │   │   ├── helpers.ts           # Helper functions
│   │   │   ├── validators.ts        # Validation functions
│   │   │   └── toast.ts             # Toast notifications
│   │   └── types/                   # TypeScript type definitions
│   │       ├── auth.ts              # Authentication types
│   │       ├── patient.ts           # Patient data types
│   │       ├── dashboard.ts         # Dashboard types
│   │       └── common.ts            # Common types
│   ├── 🎨 theme/                    # Design system & theming
│   │   ├── colors.ts                # Color palette
│   │   ├── typography.ts            # Font definitions
│   │   ├── spacing.ts               # Spacing scale
│   │   ├── shadows.ts               # Shadow definitions
│   │   ├── animations.ts            # Animation configurations
│   │   └── theme.ts                 # Main theme object
│   ├── 🧭 navigation/               # Navigation setup
│   │   ├── RootStackNavigator.tsx   # Root navigation
│   │   ├── MainTabNavigator.tsx     # Tab navigation
│   │   ├── navigationTypes.ts       # Navigation types
│   │   └── navigationUtils.ts       # Navigation utilities
│   ├── 📦 store/                    # Redux state management
│   │   ├── index.ts                 # Store configuration
│   │   ├── Provider.tsx             # Redux provider
│   │   └── hooks.ts                 # Custom Redux hooks
│   ├── 📁 assets/                   # Static assets
│   │   ├── images/                  # Image assets
│   │   ├── fonts/                   # Custom fonts
│   │   └── dicom/                   # DICOM viewer HTML
│   ├── ⚙️ config/                   # Configuration files
│   └── 🌐 localization/             # Internationalization
├── 🤖 android/                      # Android native code
├── 🍎 ios/                          # iOS native code
├── 📚 docs/                         # Documentation
├── 📄 package.json                  # Dependencies & scripts
├── 🔧 metro.config.js               # Metro bundler config
├── 📝 tsconfig.json                 # TypeScript configuration
└── 📖 README.md                     # This file
```

### **Key File Explanations**

#### **Entry Points**
- **`app/App.tsx`**: Main application component with navigation setup
- **`index.js`**: React Native entry point
- **`metro.config.js`**: Bundler configuration

#### **Module Structure**
Each module follows the same pattern:
- **`components/`**: Reusable UI components
- **`screens/`**: Full-screen components
- **`redux/`**: State management (actions, reducers, selectors)
- **`services/`**: API and external service integrations
- **`types/`**: TypeScript type definitions

#### **Shared Resources**
- **`shared/components/`**: Cross-module reusable components
- **`shared/utils/`**: Common utility functions
- **`shared/types/`**: Shared type definitions
- **`theme/`**: Centralized design system

---

## 🎨 Design System

### **Color Palette - "Modern Healthcare Blue"**

```typescript
// Primary Colors
Primary: '#2196F3'        // Material Blue - Main brand color
Secondary: '#1976D2'      // Darker Blue - Secondary actions
Tertiary: '#E3F2FD'       // Very Light Blue - Backgrounds

// Status Colors
Success: '#4CAF50'        // Green - Success states
Warning: '#FF9800'        // Orange - Warning states
Error: '#F44336'          // Red - Error states
Info: '#2196F3'           // Blue - Information states

// Text Colors
TextPrimary: '#212121'    // Dark Gray - Main text
TextSecondary: '#757575'  // Medium Gray - Secondary text
TextMuted: '#9E9E9E'      // Light Gray - Muted text
```

### **Typography System**

```typescript
// Font Family
PrimaryFont: 'Roboto'     // Main font family

// Font Weights
Light: 300, Regular: 400, Medium: 500, Bold: 700

// Font Sizes
DisplayLarge: 32px        // Main headings
DisplayMedium: 24px       // Section headings
BodyLarge: 16px           // Body text
BodyMedium: 14px          // Secondary text
Caption: 10px             // Small labels
```

### **Component Design Rules**

#### **Button Variants**
- **Primary**: Blue background with shadow
- **Secondary**: Transparent with blue border
- **Success**: Green background for positive actions
- **Critical**: Red background for urgent actions

#### **Card Design**
- **Default**: White background with subtle shadow
- **Elevated**: Enhanced shadow for important content
- **Critical**: Red accent for urgent information

---

## 🔐 Security & Authentication

### **Authentication Flow**

```
1. User Registration → Email Validation → Hospital ID Upload → Admin Approval
2. User Login → Token Generation → Session Management → Access Control
3. Token Refresh → Automatic Renewal → Secure Storage → Session Persistence
```

### **Security Features**

- **Multi-Factor Authentication**: Email + password + hospital verification
- **Token-Based Security**: JWT tokens with automatic refresh
- **Secure Storage**: Encrypted credential storage
- **Admin Approval System**: Account activation requires approval
- **Hospital Integration**: Institution-based access control

### **Data Protection**

- **DICOM Encryption**: Medical imaging file security
- **API Security**: HTTPS with token authentication
- **Local Storage**: Encrypted sensitive data
- **Session Management**: Secure session handling

---

## 📊 Data Flow & State Management

### **Redux Store Structure**

```typescript
interface RootState {
  auth: AuthState;           // Authentication & user data
  dashboard: DashboardState; // Dashboard analytics
  patientCare: PatientCareState; // Patient & case data
  settings: SettingsState;   // User preferences
  hospital: HospitalState;   // Hospital information
}
```

### **Data Flow Pattern**

```
1. API Request → Redux Action → State Update → UI Re-render
2. User Interaction → Redux Action → API Call → State Update
3. Local Storage → Redux Persist → State Hydration → App Initialization
```

### **State Persistence**

- **Redux Persist**: Automatic state persistence
- **Selective Persistence**: Only critical data persisted
- **Migration Support**: Version-based state updates
- **Offline Capability**: Local data access

---



### **Testing Strategy**

#### **Unit Testing**
```bash
# Run unit tests
npm test

# Run tests with coverage
npm run test:coverage

# Run specific test file
npm test -- PatientCard.test.tsx
```

#### **Component Testing**
- **React Native Testing Library**: Component behavior testing
- **Jest**: Test runner and assertion library
- **Mock Services**: API service mocking

### **Code Quality Tools**

- **ESLint**: Code linting and style enforcement
- **Prettier**: Code formatting
- **TypeScript**: Static type checking
- **Pre-commit Hooks**: Automated quality checks

---

## 📦 Building & Deployment

### **Development Build**

```bash
# Start development server
npm start

# Run on Android
npm run android

# Run on iOS
npm run ios
```

### **Production Build**

#### **Android Build**
```bash
# Generate APK
cd android
./gradlew assembleRelease

# Generate AAB (for Play Store)
./gradlew bundleRelease
```

#### **iOS Build**
```bash
# Open Xcode project
cd ios
open NeoScan_Radiologist.xcworkspace




---

## 🚨 Troubleshooting

### **Common Issues & Solutions**

#### **Metro Bundler Issues**
```bash
# Clear Metro cache
npm start -- --reset-cache

# Clear React Native cache
npx react-native start --reset-cache
```

#### **Android Build Issues**
```bash
# Clean Android build
cd android
./gradlew clean

# Clear Android cache
cd android/app/build
rm -rf *
```

#### **iOS Build Issues**
```bash
# Clean iOS build
cd ios
xcodebuild clean

# Reinstall pods
cd ios
pod deintegrate
pod install
```

#### **Dependency Issues**
```bash
# Clear npm cache
npm cache clean --force

# Remove node_modules and reinstall
rm -rf node_modules package-lock.json
npm install
```

### **Debug Mode**

```bash
# Enable debug logging
export DEBUG=*

# Run with verbose logging
npm start -- --verbose
```

---

## 📞 Support & Documentation

### **Documentation Resources**

- **API Documentation**: Complete API reference guide
- **User Guide**: End-user documentation and tutorials
- **Developer Guide**: Technical implementation details
- **Architecture Guide**: System design and patterns
- **Troubleshooting**: Common issues and solutions

### **Contact Information**

- **Technical Support**: dev-support@neoscan.com
- **Emergency Support**: emergency-support@neoscan.com
- **Feature Requests**: features@neoscan.com
- **Bug Reports**: bugs@neoscan.com

### **Development Guidelines**

- **Code Style**: Follow ESLint and Prettier configurations
- **TypeScript**: Use strict typing and proper interfaces
- **Testing**: Write tests for new features
- **Documentation**: Update documentation with code changes
- **Code Review**: All changes require peer review

---

## 📄 License

This project is proprietary software developed for healthcare institutions. All rights reserved.

**NeoScan Radiologist App** - Enhancing AI diagnostic accuracy through expert radiologist validation and clinical feedback.

---

## 🚀 Quick Start for New Developers

### **1. Environment Setup (5 minutes)**
```bash
# Clone and setup
git clone <repository-url>
cd NeoScan_Radiologist
npm install

# Configure environment
cp .env.example .env
# Edit .env with your API endpoints
```

### **2. First Run (3 minutes)**
```bash
# Start development server
npm start

# In new terminal, run on device
npm run android  # or npm run ios
```

### **3. Explore the Code (10 minutes)**
- Start with `app/App.tsx` to understand the app structure
- Check `app/modules/Auth/screens/LoginScreen.tsx` for authentication flow
- Review `app/shared/components/` for reusable components
- Examine `app/theme/` for design system

### **4. Make Your First Change (15 minutes)**
- Modify a component in `app/shared/components/`
- See live updates in your simulator/device
- Understand the hot reload development experience

---

*This README is designed to help developers at all levels understand and contribute to the NeoScan Radiologist App. For additional support, please refer to the documentation or contact the development team.*
