|
| 1 | +# OpenMRS Conch Agent Skill |
| 2 | + |
| 3 | +This skill helps you generate a new OpenMRS ESM microfrontend (DHTI conch) from this template. Use this skill when you need to create a new DHTI-enabled microfrontend that integrates with the OpenMRS 3.x ecosystem. |
| 4 | + |
| 5 | +## Skill Purpose |
| 6 | + |
| 7 | +DHTI is a platform to rapidly prototype, share, and test GenAI healthcare applications within an EHR. This skill guides you through: |
| 8 | +- Setting up a development environment |
| 9 | +- Scaffolding a new microfrontend project |
| 10 | +- Implementing GenAI-powered features based on requirements |
| 11 | + |
| 12 | +## When to Use This Skill |
| 13 | + |
| 14 | +Use this skill when you need to: |
| 15 | +- Create a new OpenMRS ESM microfrontend from this template |
| 16 | +- Build a DHTI-enabled healthcare application |
| 17 | +- Integrate GenAI capabilities into an OpenMRS microfrontend |
| 18 | +- Develop patient-context-aware UI components for OpenMRS |
| 19 | + |
| 20 | +## Instructions |
| 21 | + |
| 22 | +### Environment Setup and Project Scaffolding |
| 23 | + |
| 24 | +1. **Clone the template to the mentioned working directory. If working directory is not specified, create a new directory for the microfrontend at ~/dhti/packages/conch/.** |
| 25 | + ```bash |
| 26 | + npx degit dermatologist/openmrs-esm-dhti-template <<working_directory>>/openmrs-esm-dhti-<<name>> |
| 27 | + ``` |
| 28 | +
|
| 29 | +2. **Install the dependencies:** |
| 30 | + ```bash |
| 31 | + npm install |
| 32 | + ``` |
| 33 | +
|
| 34 | +3. **Read and internalize the original user feature request:** |
| 35 | + - Understand the clinical functionality needed. |
| 36 | + - Identify the UI components, extensions, workflows, and pages required. |
| 37 | + - Note any specific DHTI service integration needs. |
| 38 | +
|
| 39 | +4. **Decide on a simple but unique name** starting with `openmrs-esm-dhti-` for your microfrontend. This name will be used for the project directory, GitHub repository, and npm package. Ensure that the name is not already in use by checking the OpenMRS microfrontends list and npm registry. |
| 40 | +
|
| 41 | +### Code Adaptation and Initial Cleanup |
| 42 | +
|
| 43 | +5. **Adapt the code:** |
| 44 | + - Find and replace all instances of "template" with the name of your microfrontend (what comes after `openmrs-esm-dhti-`). |
| 45 | + - In the rest of this document `<<name>>` refers to what comes after `openmrs-esm-dhti-` in your microfrontend's name. |
| 46 | + - Update `index.ts` as below: |
| 47 | + - Set the value of `moduleName` variable to `@openmrs/esm-<<name>>`. |
| 48 | + - Set the value of `featureName` variable from `dhti-template` to `dhti-<<name>>`. |
| 49 | + - Rename the `root.*` family of files to have the name of your first page. |
| 50 | + - Delete the contents of the objects in `config-schema.ts`. Start filling them back in once you have a clear idea what will need to be configured. |
| 51 | + - Delete the `dhti` directory, and the contents of renamed `root.component.tsx` if you don't need them. |
| 52 | + - **DO NOT** delete `src/hooks` and `src/models` as they contain useful shared code. |
| 53 | + - Delete the contents of `translations/en.json`. |
| 54 | + - Delete the contents of this README and write a short explanation of what you intend to build. Links to planning or design documents can be very helpful. |
| 55 | +
|
| 56 | +### Planning and Notes |
| 57 | +
|
| 58 | +6. **Write detailed notes** on what you plan to implement, how you plan to implement it, and any questions or uncertainties you have. This will help guide your development process. Use the `notes/` directory for this purpose. |
| 59 | +
|
| 60 | +7. **Plan UI components, extensions, workflows, and pages:** |
| 61 | + - Read through the user requirements above again and plan the UI components, extensions, workflows, and pages you will need to implement the feature. |
| 62 | + - Write down a list of these components and their responsibilities in `notes/plan.md` for future reference. |
| 63 | +
|
| 64 | +### Routing and Extension Setup |
| 65 | +
|
| 66 | +8. **Read `src/index.ts` again, and plan how to set up the extensions and routes for your microfrontend.** |
| 67 | + - The `index.ts` file in an OpenMRS frontend module typically includes the following: |
| 68 | + - **Imports:** Essential imports from `@openmrs/esm-framework` like `getSyncLifecycle`, `getAsyncLifecycle`, and `defineConfigSchema`. You may also import your React components here. |
| 69 | + - **Module and Feature Names:** Constants defining the unique `moduleName` (conventionally prefixed with `@openmrs/esm-`) and a descriptive `featureName`. You updated this before. |
| 70 | + - **startupApp function:** This function is the module's activator. It is often used to call `defineConfigSchema` to register the module's configuration schema with the system. |
| 71 | + - **Lifecycle Exports:** Components, pages, extensions, modals, or workspaces are wrapped in lifecycle functions (`getSyncLifecycle` or `getAsyncLifecycle`) and exported as named constants. These exports are then referenced in the `src/routes.json` file. |
| 72 | + - **Translation Support:** An `importTranslation` constant is used to tell the app shell where to find translation files, enabling internationalization. |
| 73 | + - Lifecycle functions may be synchronous (`getSyncLifecycle`) or asynchronous (`getAsyncLifecycle`) depending on whether the component requires async operations like data fetching. |
| 74 | +
|
| 75 | +9. **Reference the component names in your `src/routes.json` file** to define routes or extensions. Read how the extension system works in OpenMRS micro-frontend: <https://o3-docs.openmrs.org/docs/extension-system>. Update `src/routes.json` accordingly. |
| 76 | +
|
| 77 | +### Patient and Encounter Data in Components |
| 78 | +
|
| 79 | +10. **Getting patient and encounter data in components:** |
| 80 | + - When an ESM is rendered inside a patient context (e.g., patient chart, visit workspace, form workspace), the framework automatically injects context props into your root component. |
| 81 | + - These props typically include: |
| 82 | + - `patient` (full patient object) |
| 83 | + - `patientUuid` |
| 84 | + - `encounterUuid` (when inside an encounter context) |
| 85 | + - `visitUuid` (when inside a visit context) |
| 86 | + - When a route is mounted under a patient or encounter workspace, the framework resolves context from the URL and global store. |
| 87 | + - You can access them in two ways: |
| 88 | + - **A. Direct Props (most common):** |
| 89 | + ```tsx |
| 90 | + export default function MyComponent({ patientUuid, encounterUuid }) { |
| 91 | + return ( |
| 92 | + <div> |
| 93 | + Patient: {patientUuid} |
| 94 | + Encounter: {encounterUuid} |
| 95 | + </div> |
| 96 | + ); |
| 97 | + } |
| 98 | + ``` |
| 99 | + - **B. Using Framework Hooks:** |
| 100 | + ```tsx |
| 101 | + import { usePatient, useVisit, useEncounter } from "@openmrs/esm-framework"; |
| 102 | +
|
| 103 | + const MyComponent = () => { |
| 104 | + const patient = usePatient(); |
| 105 | + const encounter = useEncounter(); |
| 106 | +
|
| 107 | + console.log(patient?.uuid); |
| 108 | + console.log(encounter?.uuid); |
| 109 | +
|
| 110 | + return <div>...</div>; |
| 111 | + }; |
| 112 | + ``` |
| 113 | +
|
| 114 | +### GenAI Outputs |
| 115 | +
|
| 116 | +11. **Getting GenAI outputs:** |
| 117 | + - Use the `src/hooks/useDhti.ts` to call the DHTI service and get GenAI outputs. Read the code and comments in the file to understand how to use it. You need to provide the DHTI service name. If the user has not provided it above, ask for it using a prompt. |
| 118 | +
|
| 119 | +### Implementation |
| 120 | +
|
| 121 | +12. **Implement the feature:** |
| 122 | + - Start implementing the feature based on your plans. Follow best practices for React and OpenMRS frontend-module development. When you are in doubt refer to the implementation guide here: https://r.jina.ai/https://o3-docs.openmrs.org/docs/frontend-modules/overview. Test your code frequently to ensure it works as expected. Start with the renamed `root.component.tsx` file and build out from there. Please note that you may have components not included in the root component, but used in extensions or pages. |
| 123 | +
|
| 124 | +### Testing |
| 125 | +
|
| 126 | +13. **Write tests:** |
| 127 | + - Write unit and integration tests for your components and logic. Use the testing framework set up in the template. Ensure good test coverage to catch potential issues early. |
| 128 | +
|
| 129 | +### Documentation |
| 130 | +
|
| 131 | +14. **Update documentation:** |
| 132 | + - Update the `README.md` with details about your microfrontend, including its purpose, setup instructions, and usage. Document any configuration options in `config-schema.ts`. Extended notes and future plans can go in the `notes/` directory. |
| 133 | +
|
| 134 | +### Final Review and Cleanup |
| 135 | +
|
| 136 | +15. **Final review and cleanup:** |
| 137 | + - Review your code for any unused imports, variables, or commented-out code. Ensure your code follows consistent styling and conventions. Run the application to do a final test of all features and ensure everything works as expected. |
| 138 | +
|
| 139 | +## Example Usage |
| 140 | +
|
| 141 | +See `examples/conch-sample-request.md` for a sample feature request that demonstrates how to use this skill. |
| 142 | +
|
| 143 | +## Additional Resources |
| 144 | +
|
| 145 | +- [OpenMRS Frontend Modules Overview](https://o3-docs.openmrs.org/docs/frontend-modules/overview) |
| 146 | +- [OpenMRS Extension System](https://o3-docs.openmrs.org/docs/extension-system) |
| 147 | +- [DHTI GitHub Repository](https://github.com/dermatologist/dhti) |
0 commit comments