All projects

Case study 04 / Python workflow prototype

MEDAGENT

Explicit rules. Traceable workflow decisions.

A scheduling and care-workflow prototype with staff and patient access, capacity-aware waitlists and deterministic event handlers.

Technology
  • Python
  • Streamlit
  • SQLite
  • pytest
  • GitHub Actions
  • Render
Project context
Portfolio project with earlier group contributions. Individual contribution details are being documented.
Event architecture
  1. ActionStaff or patient
  2. ValidateAccess & domain rules
  3. RecordState + event
  4. DispatchDeterministic handlers
  5. ExplainDecision history
Event-processing architecture · one Python application
Event architecture
  1. ActionStaff or patient
  2. ValidateAccess & domain rules
  3. RecordState + event
  4. DispatchDeterministic handlers
  5. ExplainDecision history
Event-processing architecture · one Python application

Connect the workflow, preserve the decisions.

MEDAGENT explores the software behind patient registration, appointment allocation, arrivals and care transitions. Its objective is to keep these operations consistent and inspectable within a bounded prototype.

The public introduction provides a walkthrough without an account. Staff and patient records require sign-in. The system does not diagnose patients or make validated clinical decisions.

Deterministic agents, inspectable behavior.

Streamlit renders the workspaces. Python domain services validate commands and write state changes alongside events in SQLite. A synchronous dispatcher passes pending events to deterministic handlers and stores the reasons for their decisions.

The agents run within one application. They are not independent services or a machine-learning model. Each event's database effects, decisions and completion marker commit together. A handler failure rolls back those effects and leaves the event pending for investigation.

Waitlist handler

Allocates released capacity using urgency followed by waiting order.

Appointment handler

Records the reasons behind booking and appointment changes.

Care coordination

Records validated visit-transition decisions and their triggering events.

Access follows the actor and the operation.

Staff roles restrict available workspaces, commands and data reads at the application boundary. The patient portal links an authenticated account to a patient identity and scopes appointment operations to that identity.

Registration creates a durable patient identifier. Duplicate review avoids silently merging people based on similar names or contact details. Patient registration and appointment booking remain separate steps.

The security boundary is explicit: clinical staff share role-based chart access rather than assignment-based patient isolation. Audit records provide application history, not an immutable external log or a compliance certification.

Capacity is a rule, not a visual counter.

Patients, appointments and visits are separate records. A visit begins at check-in, rather than when an appointment is booked. Care transitions require an allowed source state and the expected record version, so stale actions cannot silently replace newer ones.

Routine session capacity is a booking quota. Completing a routine visit does not free another booking place. Emergency capacity instead represents concurrent places. Released routine capacity can trigger waitlist promotion by urgency and waiting order.

SQLite write transactions serialize capacity allocation. This keeps simultaneous claims within a single database transaction, with events preserving the decisions that follow.

Include the work around the workflow.

Operational features include staff availability, leave and breaks, consultation tracking, manual database backup and restore, and synthetic queue-policy evaluation. Event and audit views help explain state changes and investigate failures.

pytest covers scheduling, access, care transitions, patient journeys and recovery behavior. The GitHub Actions workflow installs Python dependencies and runs the test suite. The tests use temporary databases and mocked delivery rather than real patient records or live email credentials.

Useful prototype. Clearly stated limits.

SQLite keeps the application's persistence simple, with write concurrency governed by a single database. Streamlit brings the workflow into an interactive interface; the synchronous dispatcher keeps event processing inside that application flow.

The Render demo uses temporary storage: records and accounts may reset on restart or redeployment. Live email delivery is disabled. Persistent hosting and an unattended worker are not deployed. The public walkthrough is the most accessible way to explore the project.

Clinical and triage rules are not clinically validated. Production security review, external audit retention and verified reminder delivery remain outside the current prototype's claims.

Future: persistent hosting

Provide durable database storage and exercise backup/restore before relying on retained accounts or records.

Future: background delivery

Deploy and monitor a worker with explicit recovery and external-delivery guarantees.

Future: validation

Treat clinical and security validation as separate requirements, not consequences of passing software tests.

Source reviewed at revision 41bcb55. View the reviewed snapshot.

Next case study

Bookhaven
Contact