med-ydb

A personal learning workspace for exploring YottaDB and VistA healthcare architecture using Python.

About

This project uses the WorldVistA VEHU (VistA Environment for Healthcare Utilities) Docker container to learn:

• YottaDB: A hierarchical NoSQL database using globals
• VistA: Veterans Health Information Systems and Technology Architecture
• FileMan: VistA's data dictionary and abstraction layer
• M (MUMPS): The language VistA is written in

This is a read-only exploration project focused on understanding VistA's architecture through Python scripts.

Prerequisites

• Docker and Docker Compose
• macOS (tested on Apple Silicon; VEHU runs as linux/amd64 via emulation)
• Basic Python knowledge

Quick Start

1. Start the VEHU container:

   docker compose up -d

2. Verify the environment:

   docker exec -it vehu-311 python3 /opt/med-ydb/cli/explore/00_env_check.py

3. Explore VistA data:

   # List globals
   docker exec -it vehu-311 python3 /opt/med-ydb/cli/explore/03_list_globals.py --prefix ^D --limit 20
   
   # Explore patient data (safe, read-only)
   docker exec -it vehu-311 python3 /opt/med-ydb/cli/explore/06_explore_allowlisted.py --global ^DPT --max-nodes 10

Note:
To ensure a completely fresh start for a project, you must remove both the active container and the underlying image. Because docker-compose.yaml uses a build: . instruction, Docker may try to reuse "cached" layers to save time unless you explicitly tell it otherwise.

docker compose up -d --build --force-recreate

Accessing VistA Directly

You can also interact with VistA using its native "roll and scroll" terminal interface:

docker exec -it vehu-311 su - vehu -c 'mumps -r ZU'

When prompted, log in using VistA Access / Verify codes:

User	Access Code	Verify Code	Comment
PROGRAMMER,ONE	PRO1234	PRO1234!!	high privilege - system access
PROVIDER,FORTY	PROV40	PROV40!!	provider workflows

Navigation tips:

• Type ? to see available options at any menu
• Type ^ to back out one level or sign off
• Use FM to enter FileMan for data dictionary exploration

For detailed VistA navigation, see docs/guide/vista-first-session-lab.md

Documentation

Comprehensive guides and learning materials are in the docs/ directory:

• Setup Guides: docs/guide/ - Container setup, Python integration, VistA access
• Learning Path: docs/learn/ - Progressive tutorials from YottaDB basics through VistA architecture
• Project Context: CLAUDE.md - Detailed project context for AI assistance

Recommended starting point: docs/learn/00-learning-plan.md

Project Structure

med-ydb/
├── Dockerfile           # Custom image build (Python 3.11 + dependencies)
├── docker-compose.yaml  # Container orchestration and bind mounts
├── requirements.txt     # Python dependencies (baked into image at build time)
├── app/                 # FastAPI web application (future UI)
├── cli/                 # Python CLI exploration scripts
│   ├── explore/         # Exploratory scripts
│   └── learn/           # Learning scripts
├── exercise/            # Learning exercises (aligned with docs/learn/)
├── docs/
│   ├── guide/           # Setup and operational guides
│   ├── learn/           # Progressive learning materials
│   └── spec/            # Reference specifications
└── output/              # Generated output files (writable)
    ├── misc/            # Miscellaneous files
    └── vehu/            # JSON files

Environment

• Source Image: worldvista/vehu:202504
• Python Version: 3.11 (installed via Dockerfile; overrides VEHU default)
• YottaDB: Pre-configured in VEHU; Python integration via yottadb==2.0.0

Scripts are mounted from the host into /opt/med-ydb/ in the container. No docker cp or rebuild needed for code changes.

License

Personal learning project - not intended for production use.