2 - NextGenHealth: From Use Cases to Domain Model – Building the Foundation with Precision

Turning Vision into Actionable Design

In my previous post, I shared how 11 years of enterprise healthcare experience led to NextGenHealth — a system built not from assumptions, but from structured engineering: 9 technical documents, Clean Architecture, and UML-driven design.

Now, the journey goes deeper.

After defining the core use case diagrams, the next critical phase was specification and domain modeling — where abstract workflows become concrete, testable, and implementable artifacts.

This is where software transitions from idea to engineering discipline.

Why Specifications Matter

A use case diagram shows what the system does.

A use case specification defines how it does it — with precision.

I’ve seen too many healthcare systems fail because “Register Patient” was just a box on a diagram.

In reality, it’s a complex flow involving:

• Data validation

• UUID generation

• Audit logging

• Role-Based access

• Secure credential creation

So I wrote detailed specifications for the core use cases, following a standardized template with:

• ID, name, actors

• Preconditions and postconditions

• Main success flow

• Alternative and exception flows

• Business rules

• Non-functional requirements

• Data dictionary

Completed Use Case Specifications

🔹 UC-PAT-01: Register Patient

• Supports self-registration and admin onboarding

• Enforces email uniqueness and secure password rules

• Generates UUID and logs audit event

• Integrates with authentication from day one

Link to Register Patient Use Case Specification

🔹 UC-AUTH-01: Login to System

• Role-based access (Patient, Nurse, Doctor, Admin)

• 30-minute session timeout

• Account lockout after 5 failed attempts

• Full audit trail for compliance (LGPD/HIPAA)

Link to Login Use Case Specification

🔹 UC-APP-01: Book Appointment

• Real-time availability checks

• Prevents double-booking and overlapping appointments

• Triggers confirmation notifications (email/SMS)

• Only authenticated users can book

Link to Book Appointment Use Case Specification

Each specification is a living document — versioned, traceable, and directly mapped to future test cases and API contracts.

The Domain Model: Where the System Takes Shape

With specifications in place, the next step was the domain model — the backbone of the system’s structure.

This isn’t just a class diagram. It’s a shared language between engineers, stakeholders, and the code itself.

Using UML and domain-driven design principles, I modeled the core entities of Patient Management:

Patient Management Domain Model

✅ Core Entities

• Patient — The central entity, holding demographic and clinical data

• UserCredentials — Secure authentication for all system roles

• AuditLogEntry — Immutable record of all data changes

• Nurse, Doctor, Administrator — System actors with distinct access patterns

The model enforces:

• Separation of concerns (e.g., UserCredentials is not part of Patient)

• Role-based access at the domain level

• Auditability as a first-class citizen

• Scalability through clean, navigable associations

Design Decisions That Matter

Some key choices that shaped the model:

Why UserCredentials is separate

Because authentication is a cross-cutting concern — not just for patients, but for all roles.

It’s a reusable, secure component that will support future features like MFA and OAuth.

Why Patient doesn’t view its own audit trail

Because audit logs are for staff and compliance, not patient UX.

Patients see their medical history — not who edited their address.

Why relationships use verbs like manages, views, audits

Because clarity beats abstraction.

The model isn’t just for developers — it’s for auditors, product owners, and future maintainers.

The Technical Stack (Still Python-Centric)

• Backend: Python (Django/Flask)

• UML Tooling: Modelio for domain modeling

• Documentation: Markdown, versioned in Git

• Data Modeling: Entity-Relationship design with future PostgreSQL mapping

• Architecture: Clean Architecture layers (Entities, Use Cases, Interface Adapters, Frameworks)

Every decision reflects lessons from enterprise healthcare:

• Security first

• Compliance by design

• Maintainability over shortcuts

The Philosophy Remains the Same

NextGenHealth isn’t built fast.
It’s built right.

Every specification, every relationship, every verb on a UML line — it’s all grounded in real-world healthcare workflows, not academic theory.

And it’s all documented, versioned, and traceable — because in healthcare, you can’t afford to guess.

Stay in the Loop

Want to follow the journey?

🔗 Connect on LinkedIn — I post daily updates on the development process, UML decisions, and architecture insights.

📧 Need expert help on your healthcare project?
Let’s talk: contact@fmbyteshiftsoftware.com

GitHub NextGenHealth Project
Code. Design. Document. Repeat.

Next article: Refining the Domain Model — From Audit Confusion to Clear Access Control

About the Author: Fernando Antunes de Magalhães is a Software Architect with over 15 years of professional experience in the technology industry, including more than 11 years focused on healthcare innovation. He holds a Post-Graduate degree in Software Engineering and is the author of “Software Engineering — Essential Principles for Beginners and Professionals” available on Amazon (link). Currently, he leads the development of next-generation healthcare systems with precision and compliance through his company, FM ByteShift Software.