6 - NextGenHealth: From Sequence to Structure — Mapping the User Registration Flow and Layered Architecture. How a clean sequence diagram guided my class design for scalable, compliant healthcare identity.

Domain Layer: Where Business Rules Live

This is the heart of the system — pure domain logic, free from frameworks, databases, or external services.

In this layer, I defined:

• User: The central entity with shared attributes (UUID, email, role, status)

• Specializations: PatientProfile, DoctorProfile, NurseProfile — all inheriting from User

• Enums: UserRole, UserStatus

• Value Objects: UserCredentials (password hash), AuditLogTrail (immutable logs)

• Repository Interfaces: UserRepository, PatientProfileRepository, etc.

I started with one question:

"What happens — in order — when a new user is created?"

The answer revealed more than just steps. It exposed dependencies, security checkpoints, audit requirements, and integration points that would later shape my entire class diagram and layered architecture.

So before I even drew a single entity, I modeled the flow:

User Management - Register User Sequence Diagram

This sequence diagram became my truth source.

It showed me:

• Where validation must happen

• That every registration must trigger an audit log

• That notifications are secondary — but still essential

And most importantly: which classes needed to exist, what they should do, and how they should interact.

I didn’t just draw boxes and arrows. I built a layered structure grounded in Clean Architecture and Domain-Driven Design (DDD) — where every component has a clear purpose, responsibility, and boundary.

From this sequence flow, I derived the final class diagram, organized across three core layers:

Here’s how I structured it — and why each layer matters.

User Management - Domain Layer Class Diagram

No implementation details. No database queries. Just business meaning.

And because I use interfaces like UserRepository here, higher layers depend on abstractions — not concrete tech.

This ensures compliance by design: HIPAA/GDPR rules live in the domain, enforced regardless of infrastructure.

Application Layer: Orchestration Without Knowledge

This layer contains the Use Cases — the executable specifications of what the system does.

It’s responsible for:

• Coordinating workflows (RegisterUserUseCase, UpdateUserProfileUseCase)

• Enforcing RBAC (only admins can create doctors/nurses)

• Delegating to domain entities and services

• Injecting dependencies via interfaces

Key components:

✅RegisterUserUseCase: orchestrates user creation + profile setup

✅SearchUsersUseCase: applies role-based filters before returning results

✅PatientProfileService, DoctorProfileService, NurseProfileService: handle profile-specific logic

✅NotificationService, AuditService: abstracted interfaces for cross-cutting concerns

User Management - Application Layer Class Diagram

Crucially, no direct dependency on PostgreSQL, Redis, or SendGrid. Everything flows through interfaces defined in the domain and application layers.

This makes the system:

✅ Testable (mock repositories)

✅ Swappable (change email provider without touching Use Cases)

✅ Secure (RBAC enforced at orchestration level)

Infrastructure Layer: Plug-and-Play Implementations

Finally, the Infrastructure Layer brings the system to life — but only as an implementation detail.

Concrete classes live here:

✅PostgreSQLUserRepository: talks to the DB

✅SendGridNotificationAdapter: sends welcome emails

✅PostgreSQLAuditLogger: writes to audit_logs table

✅RedisCacheAdapter: caches frequent lookups like find_by_email

User Management - Infrastructure Layer Class Diagram

These are implementations of contracts defined above — never directly used by Use Cases.

Want to switch from SendGrid to AWS SES? Replace one adapter. Zero changes to business logic.

Need faster queries? Add Redis caching to UserRepository — transparently.

This layer also handles external integrations:

✅Twilio SMS reminders

✅OAuth providers (future)

✅FHIR/HL7 gateways (planned)

All isolated, tested, and replaceable.

Why This Structure Wins:

✅Testability - Mock UserRepository in unit tests; no DB needed

✅Security - RBAC enforced in Application Layer, logged via AuditService

✅Scalability - Add new roles (e.g., Receptionist) without changing core logic

✅Compliance - Full audit trail tied to User, immutable by design

✅Maintainability -Clear ownership per layer; teams can work independently

Real-World Impact

This layered approach enabled us to:

✅Build a single registration flow that supports patients, nurses, and doctors

✅Ensure every sensitive action is audited — from password changes to role updates

✅Write end-to-end tests that run fast because they mock infrastructure

And critically:

➡️ The domain remains untouched when we change tech.

➡️ The application stays clean while integrating complex systems.

Stay in the Loop

Want to follow the journey?

🔗 Connect on LinkedIn — I post updates on architecture decisions, UML modeling, and healthcare compliance.

📧 Need expert help on your healthcare project?

Let’s talk: contact@fmbyteshiftsoftware.com

Check the full project changelog:
👉 Change Log

📁 GitHub NextGenHealth Project

Code. Design. Document. Refine.

About the Author: Fernando Antunes de Magalhães is a Software Architect with over 15 years of experience, including 11 years focused on healthcare technology. He holds a Post-Graduate degree in Software Engineering and is the author of “Software Engineering — Essential Principles for Beginners and Professionals” (link). As CEO of FM ByteShift Software, he builds next-generation systems with precision, compliance, and real-world impact.