openapi: 3.1.0
info:
  title: TouchpointHQ API
  version: 1.0.0
  description: |
    TouchpointHQ is a clinical outcomes tracking platform for behavioral health clinicians.
    This specification describes the public-facing resources and structure of the TouchpointHQ platform.
    
    ## Platform Overview
    TouchpointHQ provides validated clinical assessments for mental health, substance use, and eating disorder treatment, enabling measurement-based care with early relapse detection.
    
    ## Key Features
    - 30+ validated clinical assessment forms (PHQ-9, GAD-7, AUDIT, PCL-5, etc.)
    - Automated assessment delivery via email
    - Early relapse detection with customizable threshold alerts
    - HEDIS quality measure mapping for value-based care
    - Practice insights and benchmarking for group practices
    - HIPAA-compliant infrastructure
    
  termsOfService: https://touchpointhq.com/terms
  contact:
    name: TouchpointHQ Support
    email: contact@touchpointhq.com
    url: https://touchpointhq.com/contact
  license:
    name: Proprietary
    url: https://touchpointhq.com/terms

servers:
  - url: https://touchpointhq.com
    description: Production server

tags:
  - name: Public Pages
    description: Public-facing informational pages
  - name: Clinical Resources
    description: Clinical assessment resources and educational content
  - name: VBC Resources
    description: Value-Based Care and HEDIS educational resources
  - name: Clinician Portal
    description: Authenticated clinician portal endpoints

paths:
  /:
    get:
      summary: Homepage
      description: Main landing page showcasing TouchpointHQ platform features and benefits
      tags:
        - Public Pages
      responses:
        '200':
          description: HTML page with platform overview, features, and call-to-action

  /about:
    get:
      summary: About Us
      description: Company information, mission, values, and team overview
      tags:
        - Public Pages
      responses:
        '200':
          description: HTML page with company information

  /pricing:
    get:
      summary: Pricing Plans
      description: |
        Subscription pricing for Individual ($29.99/month) and Group ($199.99/month per 10 seats) plans.
        Includes 90-day free trial, feature comparison, and FAQ.
      tags:
        - Public Pages
      responses:
        '200':
          description: HTML page with pricing tiers and features

  /contact:
    get:
      summary: Contact Information
      description: Contact details and support information for TouchpointHQ
      tags:
        - Public Pages
      responses:
        '200':
          description: HTML page with contact information

  /assessment-library:
    get:
      summary: Clinical Assessment Library
      description: |
        Comprehensive library of 27+ validated clinical assessments with:
        - Detailed scoring guides and interpretation
        - Clinical use cases and evidence base
        - Free PDF downloads for public domain assessments
        
        Categories include:
        - Mental Health: PHQ-9, GAD-7, PCL-5, MDQ, WHO-5, PHQ-15
        - Substance Use: AUDIT, DAST-10, ASSIST, CAGE-AID, ASI-Lite
        - Eating Disorders: EDE-Q, SCOFF, CIA
        - Suicide Risk: C-SSRS
        - Quality of Life: PROMIS measures
      tags:
        - Clinical Resources
      responses:
        '200':
          description: HTML page with searchable assessment library

  /free-downloads:
    get:
      summary: Free Assessment PDF Downloads
      description: |
        Free downloadable PDFs of public domain clinical assessments including:
        - PHQ-9, PHQ-2, PHQ-15 (Depression, Somatic)
        - GAD-7 (Anxiety)
        - PCL-5 (PTSD)
        - AUDIT, AUDIT-C (Alcohol)
        - DAST-10 (Drug Use)
        - C-SSRS (Suicide Risk)
        - CAGE-AID, ASSIST (Substance Screening)
        - WHO-5 (Well-Being)
        - PROMIS measures (Global Health, Sleep, Pain)
        
        All forms are in the public domain and free for clinical use.
      tags:
        - Clinical Resources
      responses:
        '200':
          description: HTML page with downloadable assessment PDFs

  /ai-advisor:
    get:
      summary: AI Assessment Advisor
      description: |
        AI-powered tool that recommends appropriate clinical assessments based on:
        - Patient presenting concerns
        - Diagnostic considerations
        - Treatment setting
        - Clinical objectives
      tags:
        - Clinical Resources
      responses:
        '200':
          description: HTML page with AI advisor chatbot interface

  /assessment-interpreter:
    get:
      summary: AI Assessment Score Interpreter
      description: |
        AI-powered interpretation of assessment scores providing:
        - Clinical severity classification
        - Evidence-based treatment recommendations
        - Risk considerations
        - Follow-up suggestions
      tags:
        - Clinical Resources
      responses:
        '200':
          description: HTML page with score interpretation tool

  /glossary:
    get:
      summary: Clinical & HEDIS Glossary
      description: |
        Comprehensive glossary of 50+ terms covering:
        - Clinical assessment terminology (PHQ-9, GAD-7, AUDIT, etc.)
        - HEDIS quality measures (DSF, FUH, AMM, IET, ADD)
        - Value-based care concepts
        - Measurement-based care terminology
      tags:
        - Clinical Resources
      parameters:
        - name: category
          in: query
          schema:
            type: string
            enum: [all, assessment, clinical, measurement, treatment, healthcare]
          description: Filter terms by category
      responses:
        '200':
          description: HTML page with searchable glossary

  /value-based-care:
    get:
      summary: Value-Based Care Overview
      description: |
        Educational content on Value-Based Care in behavioral health:
        - What is VBC and how it affects clinicians
        - HEDIS quality measures for behavioral health
        - Preparing for outcome-based reimbursement
        - Benefits and challenges of VBC adoption
      tags:
        - VBC Resources
      responses:
        '200':
          description: HTML page with VBC educational content

  /vbc-education:
    get:
      summary: VBC & HEDIS Education Center
      description: |
        Comprehensive VBC learning hub featuring:
        - ROI Calculator for VBC readiness
        - VBC Readiness Quiz
        - Implementation guides and best practices
        - HEDIS measure deep dives (DSF, FUH, AMM, IET, ADD)
        - Downloadable resources and guides
      tags:
        - VBC Resources
      responses:
        '200':
          description: HTML page with VBC education resources

  /hedis-mapping:
    get:
      summary: HEDIS Quality Measure Mapping
      description: |
        Tool for mapping clinical assessments to HEDIS quality measures:
        - DSF (Depression Screening and Follow-Up)
        - FUH (Follow-Up After Hospitalization)
        - AMM (Antidepressant Medication Management)
        - IET (Initiation and Engagement of Treatment)
        - ADD (Follow-Up Care for Children with ADHD)
        
        Generate payer-ready compliance reports for VBC contract negotiations.
      tags:
        - VBC Resources
      responses:
        '200':
          description: HTML page with HEDIS mapping tool and compliance reports

  /relapse-detection:
    get:
      summary: Early Relapse Detection System
      description: |
        Information about TouchpointHQ's early warning alert system:
        - Customizable threshold alerts (20%, 30%, 50% score changes)
        - Instant email notifications
        - Per-patient and per-assessment configuration
        - Clinical intervention guidance
      tags:
        - Clinical Resources
      responses:
        '200':
          description: HTML page explaining relapse detection features

  /insights:
    get:
      summary: Practice Insights Portal
      description: |
        Overview of aggregate practice analytics available to group accounts:
        - Outcome trends by diagnosis
        - Clinician comparison reports
        - Completion rate tracking
        - Anonymized benchmarking
      tags:
        - Clinical Resources
      responses:
        '200':
          description: HTML page with insights feature overview

  /privacy:
    get:
      summary: Privacy Policy
      description: HIPAA-compliant privacy policy and data protection information
      tags:
        - Public Pages
      responses:
        '200':
          description: HTML page with privacy policy

  /terms:
    get:
      summary: Terms of Service
      description: Terms and conditions for using TouchpointHQ
      tags:
        - Public Pages
      responses:
        '200':
          description: HTML page with terms of service

  /medical-disclaimer:
    get:
      summary: Medical Disclaimer
      description: Medical and clinical use disclaimer
      tags:
        - Public Pages
      responses:
        '200':
          description: HTML page with medical disclaimer

  /clinician/login:
    get:
      summary: Clinician Login
      description: Authentication page for clinician portal access
      tags:
        - Clinician Portal
      responses:
        '200':
          description: HTML login form

  /clinician/signup:
    get:
      summary: Clinician Signup
      description: Registration page for new clinician accounts with 90-day free trial
      tags:
        - Clinician Portal
      responses:
        '200':
          description: HTML registration form

  /clinician/dashboard:
    get:
      summary: Clinician Dashboard
      description: Main dashboard for authenticated clinicians showing patient overview and alerts
      tags:
        - Clinician Portal
      security:
        - bearerAuth: []
      responses:
        '200':
          description: HTML dashboard page
        '401':
          description: Unauthorized - authentication required

  /llms.txt:
    get:
      summary: LLM Context File
      description: Machine-readable context file for AI assistants describing TouchpointHQ content and capabilities
      tags:
        - Public Pages
      responses:
        '200':
          description: Plain text file with AI-friendly content description
          content:
            text/plain:
              schema:
                type: string

  /robots.txt:
    get:
      summary: Robots.txt
      description: Search engine and AI crawler directives
      tags:
        - Public Pages
      responses:
        '200':
          description: Robots.txt file
          content:
            text/plain:
              schema:
                type: string

  /sitemap.xml:
    get:
      summary: XML Sitemap
      description: XML sitemap for search engine indexing
      tags:
        - Public Pages
      responses:
        '200':
          description: XML sitemap
          content:
            application/xml:
              schema:
                type: string

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JWT token obtained after clinician login

  schemas:
    Assessment:
      type: object
      properties:
        id:
          type: string
          example: phq-9
        name:
          type: string
          example: PHQ-9
        fullName:
          type: string
          example: Patient Health Questionnaire-9
        category:
          type: string
          enum: [mental-health, substance-use, eating-disorders]
        items:
          type: integer
          example: 9
        timeToComplete:
          type: string
          example: 2-3 minutes
        description:
          type: string
        isPublicDomain:
          type: boolean

    HEDISMeasure:
      type: object
      properties:
        code:
          type: string
          example: DSF
        name:
          type: string
          example: Depression Screening and Follow-Up
        description:
          type: string
        applicableAssessments:
          type: array
          items:
            type: string
          example: [PHQ-9, PHQ-2]

    GlossaryTerm:
      type: object
      properties:
        term:
          type: string
        abbreviation:
          type: string
        definition:
          type: string
        category:
          type: string
          enum: [assessment, clinical, measurement, treatment, healthcare]

externalDocs:
  description: TouchpointHQ Documentation
  url: https://touchpointhq.com/about
