1. Problem Statement

Millions of health-conscious consumers get bloodwork done quarterly or annually but lack the tools and knowledge to interpret their results meaningfully. Traditional healthcare provides only a brief "normal/abnormal" flag, while optimal ranges for wellness differ significantly from clinical reference ranges. Users are left to navigate a confusing landscape of supplements, peptides, and nutrition advice from unvetted sources.

VitalNexa solves this by providing an AI-powered wellness companion that ingests a user's actual lab data, tracks biomarker trends over time, and delivers personalized, evidence-informed guidance on vitamins, supplements, peptides, and nutrition through a natural conversational interface.

2. User Personas

2.1 Primary Persona: "Optimized Alex"

Attribute	Details
Age / Demographics	38, software engineer, household income $140K, lives in Austin, TX
Health Behavior	Gets comprehensive bloodwork every 3 months through Quest Direct. Takes 8 supplements daily. Follows a high-protein diet. Interested in peptides like BPC-157 and Thymosin Alpha-1.
Pain Points	Spends hours researching each biomarker on Reddit and PubMed. Unsure if his supplement stack is optimal for his specific labs. Tracks results in a messy spreadsheet with no trend visualization.
Goals	Understand what each marker means in context, see trends over time, get specific supplement/peptide recommendations based on his data.
Tech Comfort	Very high. Uses health apps daily. Expects fast, modern UX.

2.2 Secondary Persona: "Wellness-Curious Maya"

Attribute	Details
Age / Demographics	44, marketing director, household income $95K, lives in Denver, CO
Health Behavior	Just started getting annual bloodwork after a friend's health scare. Takes a multivitamin and vitamin D. Interested in optimizing energy and sleep quality.
Pain Points	Received lab results from her doctor with no explanation beyond "everything looks fine." Knows her vitamin D was flagged as low but doesn't know what to do about it. Overwhelmed by contradictory health information online.
Goals	Understand lab results in plain language, get clear supplement recommendations, build confidence in managing her own wellness.
Tech Comfort	Moderate. Uses iPhone apps comfortably but prefers simple interfaces.

3. Core Features

3.1 User Authentication and Account Management P0

Secure account creation and management with healthcare-grade security controls.

• Email and password registration with email verification
• JWT-based session management with configurable token expiration
• Password requirements: minimum 8 characters, mixed case, numbers, special characters
• Account lockout after 5 failed login attempts (30-minute lockout window)
• Password reset via email with time-limited tokens
• Profile management: name, date of birth, basic health preferences

3.2 Health Record Upload and Processing P0

Users can upload lab results and health records in common formats for AI-assisted analysis.

• Supported formats: .txt and .pdf files
• Maximum file size: 10 MB per upload
• Document text extraction and chunking for semantic search
• Storage in PostgreSQL with pgvector embeddings for RAG retrieval
• PII fields encrypted with AES-256-GCM before storage
• Upload history with metadata (filename, date, record type)
• Delete capability with full audit trail

3.3 Bloodwork and Lab Result Tracking P0

Structured entry and visualization of biomarker data across multiple test dates.

• Manual entry of lab values with biomarker selection (e.g., Vitamin D, TSH, Testosterone, CBC panel)
• Date-stamped entries for longitudinal tracking
• Reference range display (standard and optimal wellness ranges)
• Trend visualization: line charts showing biomarker changes over time
• Color-coded indicators: below optimal, within optimal, above optimal
• CRUD operations on all test result entries

3.4 AI Wellness Chat P0

Conversational AI interface powered by Claude Haiku 4.5, grounded in the user's health data.

• Natural language conversation about wellness topics: vitamins, supplements, peptides, nutrition, exercise, sleep
• RAG-powered responses that reference the user's uploaded records and lab results
• Context-aware: the AI knows the user's biomarker history and trends
• Conversation history persistence within sessions
• Wellness disclaimers automatically appended to medical-adjacent responses
• Response streaming for real-time feel
• Topic guardrails: politely redirects clinical diagnosis questions

3.5 Dashboard P1

Overview screen presenting key health data and quick actions.

• Summary of most recent lab results with trend indicators
• Quick access to AI chat
• Recent uploads and activities
• Biomarker alerts for values outside optimal ranges

4. Non-Functional Requirements

Requirement	Target	Priority
HIPAA Compliance	Full compliance with HIPAA Privacy and Security Rules, including BAAs with all vendors	P0
Response Time	API responses under 200ms (non-AI); AI chat first token under 2 seconds	P0
Availability	99.9% uptime SLA	P0
Mobile Responsiveness	Full functionality on screens 375px and wider (iOS Safari, Chrome Android)	P0
Multi-Tenant Isolation	Row-Level Security ensuring zero data leakage between users	P0
Encryption at Rest	AES-256-GCM for all PII fields with key versioning	P0
Audit Logging	Every API request logged with user ID, action, timestamp, IP address	P0
Scalability	Support 10,000 concurrent users without degradation	P1
Accessibility	WCAG 2.1 AA compliance	P1
Internationalization	English-only at launch; i18n-ready architecture	P2

5. Acceptance Criteria

5.1 Authentication

• A new user can register with email and password, receives a verification email, and can log in after verifying
• A user who enters the wrong password 5 times is locked out for 30 minutes and sees an informative message
• JWT tokens expire after the configured TTL and refresh tokens work correctly
• All auth endpoints are rate-limited to prevent brute-force attacks

5.2 Health Record Upload

• A user can upload a .pdf or .txt file up to 10 MB and see it listed in their upload history within 5 seconds
• Uploaded documents are chunked and embedded; the AI chat can reference content from the uploaded file
• A user cannot access another user's uploaded files under any circumstances (verified by integration tests)
• Deleting a record removes it from storage and search results, with the action recorded in the audit log

5.3 Bloodwork Tracking

• A user can add a new lab result entry with date, biomarker type, value, and unit
• The trend visualization updates to include the new data point immediately
• Values outside reference ranges are visually highlighted
• A user can edit or delete any of their own entries but cannot see entries from other users

5.4 AI Wellness Chat

• The first AI response token appears within 2 seconds of sending a message
• When asked about a specific biomarker, the AI references the user's actual data if available
• When asked for a clinical diagnosis, the AI politely declines and suggests consulting a healthcare provider
• Chat responses about supplements and peptides include relevant wellness disclaimers
• Conversation context is maintained within a session (the AI remembers earlier messages)

5.5 Security and Compliance

• All PII fields in the database are encrypted and cannot be read without the decryption key
• Every API request generates an audit log entry viewable in the admin interface
• A user authenticated as User A receives zero results when querying User B's data via direct API manipulation
• The application passes OWASP ZAP baseline scan with no high-severity findings

6. Out of Scope

• Clinical Diagnosis: The platform does not diagnose medical conditions, interpret results as diagnostic indicators, or suggest diagnoses.
• Prescription Management: No medication tracking, prescription reminders, or drug interaction checking.
• Insurance Integration: No claims processing, insurance verification, or billing features.
• Provider Portal: No interface for healthcare providers to view patient data.
• Lab Ordering: No integration with lab services for ordering tests directly (planned for v2.0).
• Wearable Device Integration: No Apple Watch, Fitbit, Oura, or CGM data import (planned for v2.0).
• Social Features: No community forums, user-to-user messaging, or shared health data.
• Telehealth: No video or audio consultation with healthcare providers.

7. Technical Architecture Overview

Layer	Technology	Notes
Frontend	React + TypeScript	Single-page application, responsive design, Vite build tooling
API	FastAPI (Python)	Async endpoints, automatic OpenAPI documentation, middleware for audit logging
AI/LLM	Claude Haiku 4.5 (Anthropic)	Wellness chat with RAG grounding; system prompt enforces wellness-only scope
Database	PostgreSQL + pgvector	Relational data with vector embeddings for semantic search over health records
Authentication	JWT + bcrypt	Access and refresh tokens; bcrypt password hashing; email verification flow
Encryption	AES-256-GCM	PII field-level encryption with key versioning and rotation support
Multi-Tenancy	PostgreSQL RLS	Row-Level Security policies enforce data isolation per user
Audit	HIPAA middleware	Every request logged with user context, action, timestamp, IP, response status

8. Release Plan

Phase	Features	Target Date
Alpha (Internal)	Auth, basic CRUD for test results, AI chat without RAG, core security infrastructure	Q1 2026
Beta (Closed)	File upload with RAG, trend visualization, full HIPAA audit logging, encryption	Q2 2026
v1.0 (Public)	Dashboard, polished UX, mobile optimization, premium tier, onboarding flow	Q3 2026
v2.0	Lab ordering integration, wearable imports, provider sharing, advanced analytics	Q1 2027