Development Workflows & AI Agents
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
The OpenMRS AI EHR project utilizes a structured development workflow integrated with AI-powered services to enhance Electronic Health Record (EHR) capabilities. The architecture is divided into three primary layers: a Java/Spring and MariaDB backend for clinical data, a React/TypeScript frontend microfrontend architecture for the patient chart, and a FastAPI-based AI/ML backend for advanced features such as voice transcription and vitals extraction.
Sources: AGENTS.md:5-13, README.md:10-17
The project follows strict guiding principles, prioritizing test-driven development (TDD), high code coverage, and non-interactive CI-aware commands. AI agents operating within this repository are governed by specific runbooks that detail service orchestration, environment constraints (such as Docker-in-Docker), and specific toolchains like Yarn Berry.
Sources: conductor/workflow.md:3-10, AGENTS.md:28-40
Standard Task Workflow
Development tasks follow a rigorous lifecycle designed to ensure auditability and quality. This lifecycle is managed through a central source of truth, plan.md, and utilizes Git notes for attaching detailed task summaries to commits.
Task Execution Phases
- Selection and Initiation: Tasks are selected from
plan.mdin sequential order and marked as "In Progress"[~]. - Red Phase (TDD): Developers must write failing unit tests that define the acceptance criteria before implementing any code.
- Green Phase: Minimum application code is written to pass the tests.
- Refactoring: Code is optimized for clarity and performance without altering external behavior.
- Audit and Documentation: Completed tasks are marked
[x]in the plan, and a summary is attached to the commit hash viagit notes add -m.
Sources: conductor/workflow.md:12-46
Phase Completion & Checkpointing
When a phase concludes, a verification protocol is triggered to ensure the integrity of the codebase before moving forward.
The checkpointing protocol ensures that every modification is validated through both automated and manual steps before a phase is finalized.
Sources: conductor/workflow.md:53-111
AI Agent Environment & Orchestration
AI agents operate in a complex environment involving nested containers and cloud API integrations.
Service Stack
| Service | Port | Command / Location | Purpose |
|---|---|---|---|
| OpenMRS Backend | 80 | docker compose up -d | Core EHR REST API & Database |
| FastAPI AI Backend | 3001 | uvicorn main:app | Voice transcription & Vitals |
| Gemini Proxy | 8001 | uvicorn gemini_proxy:app | LLM summarization & Proxy |
| Frontend Dev Server | 8010 | yarn start:all | Patient Chart Microfrontends |
Sources: AGENTS.md:15-26, README.md:10-17
Agent Constraints and "Gotchas"
- Docker-in-Docker: The environment runs inside Firecracker using
fuse-overlayfsandiptables-legacy. - Startup Latency: OpenMRS requires approximately 2 minutes for database and module initialization; agents must poll
/openmrs/ws/rest/v1/sessionto detect readiness. - Tooling: Agents must use Yarn Berry (4.10.3) with the
node-moduleslinker. NPM or PNPM are strictly prohibited. - API Dependencies: AI features require external keys (
SARVAM_API_KEY,GEMINI_API_KEY). Without these, backend services start but endpoints will return errors.
Sources: AGENTS.md:42-53
Voice Vitals AI Workflow
A specific implementation of AI agents is found in the "Voice Vitals" feature, which demonstrates the end-to-end data flow from hardware interaction to structured data persistence.
Data Flow Architecture
The AI agent automates the extraction of 10 vital sign fields, including temperature and blood pressure, while performing intelligent unit conversions (e.g., Fahrenheit to Celsius).
Sources: readmes/FINAL_SUMMARY.md:88-105, readmes/README_VOICE_VITALS.md:118-136
Quality Gates & Verification
Before any task or phase is considered "Done," it must pass several quality gates:
- Code Coverage: New code must aim for >80% coverage.
- Static Analysis: No linting or static analysis errors (using configured project tools).
- Mobile Experience: Verification of touch targets (44x44px) and responsive layout.
- Documentation: All public functions and methods must be documented (JSDoc, Docstrings, etc.).
Sources: conductor/workflow.md:126-140, readmes/COMPLETION_CHECKLIST.md:111-125
Manual Verification Examples
For frontend changes, the manual verification plan must include starting the dev server (npm run dev) and confirming specific UI elements. For backend changes, curl commands are used to verify API responses (e.g., expecting 201 Created for user creation).
Sources: conductor/workflow.md:87-100
Conclusion
The development workflows and AI agent interactions within OpenMRS ensure a high standard of code quality through TDD and structured verification. By separating concerns into distinct layers and providing specific orchestration instructions for AI services, the project maintains a production-ready environment for complex EHR features.
Sources: readmes/FINAL_SUMMARY.md:270-285, conductor/workflow.md:272-277