PD-Server Documentation

Overview

A server application for Parkinson's Disease detection that processes tremor, spiral drawing, and voice data through ML models and manages user authentication and test history.

Core Functionality

1. Authentication System

• User registration and login
• Session management
• Authorization for API endpoints

2. ML Model Processing

Processes three types of diagnostic tests:

• Tremor Analysis: Processes sensor data files
• Drawing Analysis: Evaluates motor control through drawing patterns
• Voice Analysis: Analyzes speech characteristics

3. Data Persistence

• Store test results in database
• Maintain user test history
• Link results to user accounts

4. Tremor Flow (Deferred Implementation)

Special handling for tremor data collection:

• Tremor module operates independently and uploads collected data
• Server processes files asynchronously
• Results pushed to mobile app (mechanism TBD)
• Requires bidirectional communication strategy

Architecture Considerations

Test Invocation Models

Implement a unified completion endpoint:

• Tests don't return immediate results
• Mobile app polls GET /api/test/:id after test completion
• Consistent pattern across all test types

API Specification

Authentication

POST /api/auth/register
POST /api/auth/login

Test Submission

POST /api/test/tremor
Content-Type: multipart/form-data
Body: text files containing sensor data
POST /api/test/drawing
Content-Type: multipart/form-data
Body: image files
POST /api/test/speech
Content-Type: multipart/form-data
Body: audio files (mp3)

Data Retrieval

GET /api/history
Returns: List of all tests for authenticated user
GET /api/test/:id
Returns: Detailed results for specific test

App Sequence Diagram

sequenceDiagram
participant Client as Client/Frontend
participant App as Flask App
participant Auth as Auth Routes
participant Tests as Tests Routes
participant DB as Database
participant ML as ML Models
participant Files as File System
Note over Client,ML: 1. User Registration/Login Flow
Client->>+Auth: POST /api/auth/register
Auth->>+DB: Create user record
DB-->>-Auth: Return user object
Auth->>-Client: JWT Token + User Info
Client->>+Auth: POST /api/auth/login
Auth->>+DB: Validate credentials
DB-->>-Auth: User object
Auth->>-Client: JWT Token + User Info
Note over Client,ML: 2. Starting a Test
Client->>+Tests: POST /api/test/ (with JWT)
Tests->>+DB: Create new test record
DB-->>-Tests: Test object
Tests->>-Client: Test ID + Test Object
Note over Client,ML: 3. Submitting Tremor Test
Client->>+Tests: POST /api/test/tremor (with JWT + file)
Tests->>+Files: Save uploaded file
Files-->>-Tests: File path
Tests->>+ML: Process tremor file
ML-->>-Tests: Analysis results
Tests->>+DB: Update tremor_score
DB-->>-Tests: Updated test object
Tests->>-Client: Success response + ML results
Note over Client,ML: 4. Submitting Drawing Test
Client->>+Tests: POST /api/test/drawing (with JWT + file)
Tests->>+Files: Save uploaded file
Files-->>-Tests: File path
Tests->>+ML: Process drawing file
ML-->>-Tests: Analysis results
Tests->>+DB: Update drawing_score
DB-->>-Tests: Updated test object
Tests->>-Client: Success response + ML results
Note over Client,ML: 5. Submitting Speech Test
Client->>+Tests: POST /api/test/speech (with JWT + file)
Tests->>+Files: Save uploaded file
Files-->>-Tests: File path
Tests->>+ML: Process speech file
ML-->>-Tests: Analysis results
Tests->>+DB: Update speech_score
DB-->>-Tests: Updated test object
Tests->>-Client: Success response + ML results
Note over Client,ML: 6. Retrieving Test Results
Client->>+Tests: GET /api/test/{test_id} (with JWT)
Tests->>+DB: Retrieve test record
DB-->>-Tests: Test object
Tests->>-Client: Test result with scores and progress

Loading

Utility Scripts

Scripts are located in the scripts/ directory.

Clear Test Data

Delete all test data (TestGroups, TestSessions, TestInputs):

# Clear database only
python scripts/clear_test_data.py
# Clear database AND uploads folder
python scripts/clear_test_data.py --all

Docker:

docker compose exec app python scripts/clear_test_data.py
docker compose exec app python scripts/clear_test_data.py --all

Cleanup Expired Inputs

Delete expired test inputs and their associated files:

# Preview what would be deleted (dry run)
python scripts/cleanup_expired_inputs.py
# Actually delete expired inputs
python scripts/cleanup_expired_inputs.py --run

Docker:

docker compose exec app python scripts/cleanup_expired_inputs.py
docker compose exec app python scripts/cleanup_expired_inputs.py --run

Generate Factory Key

Generate factory API keys for ESP32 device provisioning:

python scripts/generate_factory_key.py <mac_address># Example
python scripts/generate_factory_key.py AA:BB:CC:DD:EE:FF

Docker:

docker compose exec app python scripts/generate_factory_key.py AA:BB:CC:DD:EE:FF