Skip to content

Conversation

@groundmuffin
Copy link
Contributor

Summary

This PR introduces powerful new ways for users to interact with their health data through advanced search and conversational chat. It also includes significant architectural improvements and technology stack upgrades to enhance performance, security, and maintainability.

New Features: Advanced Search & Conversational Chat

The core of this update is the integration of Typesense, which powers two major new features designed to make health data more accessible and useful:

  • Advanced Record Search: Users can now perform fast, relevant searches across their entire health record. The backend supports pagination and filtering by resource type, and the new UI provides a seamless experience from query to viewing a specific record.
  • Conversational Chat (RAG): A new chat interface allows users to "talk" to their health data. In this new architecture, the frontend communicates directly with the Typesense endpoint using the typesense-js library. Typesense, in turn, cooperates with a configured Large Language Model (LLM) to provide the complete RAG-based chat functionality. This approach requires an external or local LLM, and we recommend Ollama for running local models like Llama 3.1 8B. To enable stateful, follow-up questions, Typesense stores conversation history in a dedicated collection, allowing the RAG pipeline to maintain context. More information on topic: https://typesense.org/docs/29.0/api/conversational-search-rag.html

Architectural Improvements

To make the platform more robust, flexible, and easier to manage, we've made the following key improvements:

  • Dynamic Frontend Configuration: The backend now provides environment variables to the frontend at runtime via a new /api/env endpoint. Previously, the frontend's environment was static, bundled from a file at build time. This change was critical to allow features like Search and Chat to be enabled or disabled from a single place (config.yaml) without requiring a rebuild of the frontend application.
  • Optional Features for Wider Compatibility: Recognizing that not all users can run the full stack (especially on desktop), the new Search and Chat features are now optional. This is managed centrally in config.yaml, ensuring the core application remains accessible to all users while allowing power users to enable advanced functionalities.
  • Centralized Configuration: A dedicated section in config.yaml has been introduced to handle all variables related to Typesense, search, and chat, making it easier to manage these features.
  • Data Indexing for Search: To power the search functionality, the backend now includes mechanisms for indexing health records in Typesense. An initial indexing process is performed when the application is launched for the first time, ensuring all existing data is searchable. Subsequently, the index is automatically updated whenever an upsert operation is detected, keeping the search results current.

Platform & Dependency Upgrades

To keep the platform modern, secure, and performant, we have upgraded core components of our tech stack:

  • Angular 17 & Storybook 8: The frontend has been upgraded from v14 to v17. This major update brings performance improvements, new features, and long-term support. The process involved upgrading numerous packages and adjusting build configurations, such as increasing style asset size limits. As part of this upgrade, the Storybook setup for our frontend components has also been upgraded to v8, ensuring compatibility and bringing the latest features for component development and testing. All tests are passing.
  • Node.js 20: The Node.js runtime was updated from v18 to v20 to support the upgrade to Angular 17.
  • Go 1.22: The backend has been upgraded to Go version 1.22, ensuring we are using a modern and supported version of the language. All backend tests are passing.
  • Typesense Clients: We have updated to the latest versions of the Typesense engine, the typesense-go client library for the backend, and the typesense-js library for the frontend.

How to Enable Search and Chat

To get started with the new search and chat functionalities, follow these steps.

Part 1: Set Up a Local LLM with Ollama

The conversational chat feature requires a local Large Language Model (LLM) that exposes an OpenAI-compatible API. We recommend using Ollama for a straightforward setup.

Prerequisites:

  • A computer with sufficient hardware to run a local LLM efficiently. This often requires GPU acceleration. Please check the hardware requirements specific to your system and the model you choose.
  • Other tools like vLLM are also viable alternatives.

Steps:

  1. Download and Install Ollama:

    • Get the appropriate version for your operating system from the official website: https://ollama.com/download
    • Follow the installation instructions.
  2. Pull a Language Model:

    • Open your terminal and pull a model. We recommend llama3.1:8b as a starting point:
      ollama pull llama3.1:8b
  3. Run the Model:

    • Start the model to make it available on your local network:
      ollama run llama3.1:8b
    • This command runs the model and exposes an OpenAI-compatible API that fasten-onprem will use for the chat functionality.

Part 2: Configure and Run Fasten On-Prem

Prerequisites:

  • docker and docker compose must be installed on your system.

Steps:

  1. Download Configuration Files:

    • In the directory where you plan to run fasten-onprem, download the following files:
      • docker-compose-prod.yml:
        curl -o docker-compose.yml https://raw.githubusercontent.com/fastenhealth/fasten-onprem/refs/heads/main/docker-compose-prod.yml 
      • config.yaml:
        curl -o config.yaml https://raw.githubusercontent.com/fastenhealth/fasten-onprem/refs/heads/main/config.yaml
  2. Customize config.yaml:

    • Open config.yaml in a text editor.
    • To enable or disable features, comment or uncomment the relevant sections. If you do not want any search or chat capabilities, you can comment out the entire search block.
    • The vllm_url should point to your local LLM's API endpoint. If you followed the Ollama setup above, the default URL should work correctly without any changes.
  3. Start the Application:

    • Run the application using Docker Compose:
      docker compose up
    • Please allow a few minutes for all the services to initialize properly. Once ready, you can access the application in your browser.

Demo video bellow

chat-demo.mov

@AnalogJ
Copy link
Member

AnalogJ commented Aug 29, 2025

merged the Practitioner addressbook, looks like this branch has conflicts with main now.

# Conflicts:
#	frontend/src/app/app-routing.module.ts
#	frontend/src/app/app.module.ts
#	frontend/src/app/components/header/header.component.html
#	frontend/src/app/services/fasten-api.service.ts
# Conflicts:
#	docker-compose-prod.yml
#	docker-compose.yml
#	frontend/src/app/app-routing.module.ts
#	frontend/src/app/app.module.ts
#	frontend/src/app/components/header/header.component.html
#	frontend/yarn.lock
#	memory-bank/activeContext.md
#	memory-bank/productContext.md
#	memory-bank/progress.md
#	memory-bank/systemPatterns.md
#	memory-bank/techContext.md
@socket-security
Copy link

socket-security bot commented Sep 3, 2025

@socket-security
Copy link

socket-security bot commented Sep 3, 2025

All alerts resolved. Learn more about Socket for GitHub.

This PR previously contained dependency changes with security issues that have been resolved, removed, or ignored.

View full report

@AnalogJ
Copy link
Member

AnalogJ commented Oct 14, 2025

looks like theres conflicts again

# Conflicts:
#	backend/pkg/web/server.go
#	docker-compose-prod.yml
#	docker-compose.yml
#	frontend/src/app/app-routing.module.ts
#	frontend/src/app/app.module.ts
#	frontend/src/app/components/header/header.component.ts
#	frontend/src/assets/scss/dark/_components.scss
#	frontend/yarn.lock
@TheoAtTechStack
Copy link
Contributor

@AnalogJ We have fixed the conflicts, thank you!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

5 participants