PRISM – SOFTWARE ARCHITECTURE & DESIGN DOCUMENT
Author: Raman Tallamraju
Contributors: Gabriel Rodriguez, Jeffrey Levetin & Yan Zhang
(Last Revised - 5/14/2003)
The vision statement for PRISM is as follows: “The Avon Foundation
Comprehensive Breast Evaluation Center at Massachusetts General Hospital
currently asks each patient to provide information about her medical history
each time she visits the Center. The PRISM system will allow her to do that
just once, comfortably and conveniently at a computer.
PRISM will be web based, easy to use, and secure. The design and testing will
pay particular attention to the user’s varied cultural and technical
backgrounds and the need to comply with ADA guidelines. PRISM will provide
secure access and maintain audit trails in order to conform to HIPAA
PRISM design will allow for future features: updating records, porting to a
touch screen kiosk and scaling for patient data entry from remote sites.”
Our customer, Dr. Kevin Hughes at Massachusetts General Hospital wanted
the following features:
Existing paper scan form specifies data to be collected.
Web based client runs in a browser (IE 5.5 & above).
Patient can update data on subsequent visits.
Medical assistant can lock and update patient records.
Records in database are never overwritten.
All access to patient data is logged for audit trail purposes.
Printout of patient risk information as a report for the physician.
Spanish language support.
Port to Kiosk.
Apart from the above requirements, the following hardware & software
constraints were placed on the team:
The application client was to be run on a PC or a touch screen Kiosk. The
client should run within a browser, specifically Internet Explorer 5.5 or above.
We were also required to use either MS Access or MS SQL Server 2000
database on the server to store patient information.
B. System Architecture
Given that our hardware platform was going to be a Windows 2000 PC on the
server side, we chose the following tools to build this application:
Microsoft IIS as our web server
Apache Tomcat 4.1 as our application server
MS SQL Server 2000 for our database
Ant 1.5.1 as our build and deploy tool
Client runs on Internet Explorer 5.5 or above
C. Software Architecture Overview
The design process began with a thorough use case analysis based on the
customer’s requirements. After we had designed the user interface (HTML
screenshots were used in the UI prototype) and got it approved by our
customer, we finalized the use cases. Our next task was to architect a web
application that would meet all the above requirements and be consistent with
our vision statement.
We had several options at the outset. We could do a 2-tier ASP application or
a 3-tier application using Microsoft platforms (.NET, COM etc). We decided to
go in the end with a 3 tier architecture using Sun’s Java platform. Here are
our reasons for this choice:
Separating functionality from presentation would allow a better
modular design that is easier to expand and allows parallel
Clearly defined interfaces and separation boundaries promote better
understanding of the design and a cleaner implementation.
Changes are only needed in well defined components in case of bug
fixes or functionality additions.
The Java Platform is not limited to running on Microsoft platforms and
allows us to build a cross platform application.
JDBC drivers for SQL Server 2000 were readily available.
3-tier architecture is scalable with increasing user loads.
Everybody on the team had done at least some Java programming
therefore considerably lowering the learning curve involved with
introducing a new technology.
Given the above advantages, we chose to go with the following elements in
our design: Front end would implement dynamic elements with Java Server
tier would be Java Servlet based with Java helper classes and the backend
(SQL Server 2000) would be tied in with the help of JDBC.
We implemented one of the most commonly used design patterns for such
applications – the model view control design pattern. Here is a diagram that
illustrates this pattern (taken from java.sun.com):
D. UI & Front End Design
Considering that the application would most likely be used by computer
novices who would not use the application more than a few times a year, it
was very important to make PRISM easy to use. The UI was designed with
ease of use as the primary focus which demanded a very simple navigational
interface. A minimum set of 4 buttons were required to perform all the
necessary actions by our primary user – a middle aged (35-45 years old),
woman under considerable stress, and most likely averse to computers. Once
the set of 4 buttons were finalized, a simple navigational bar was created at
the bottom of the screen that remained static through all the screens the
patient would ever see. This would help keep the navigation consistent and
improve the user experience.
Help was offered to the patient on every screen and it is important to note
that we found during our usability testing that most users never read the
opening help screen in spite of directions on the welcome screen to read it.
One of the major problems with this is that most users miss the fact that our
help screens are dynamic and context sensitive. Most users wouldn’t realize
this and repeatedly asked us for help regarding questions that they thought
needed more explanation. While many solutions like pop up windows, words
that are links to help pages and extra help buttons on the screen were
considered, none were implemented because we found this out very late in
the development process and didn’t have enough time to go through another
development cycle. This problem will be fixed in the future versions of PRISM.
We chose a color scheme for PRISM that was soothing to the patients and still
provided a sufficiently high contrast to enable easy viewing by patients with
poor vision. There is no reliance on color in consideration of patients who
might be color blind, and the smallest letters in the application have been
chosen to be a 12 pt Times New Roman font to ensure that the text is
readable by everybody.
One of our goals was to build PRISM in accordance with ADA guidelines, even
though this was not required by the customer. This would need features like
designing pages with meta-data embedded in the tags that would enable a
page reader application to read screens to a visually impaired person.
Unfortunately, we haven’t been able to meet that goal due to lack of time.
This feature will be added in a future version.
Finally one of the most important features of PRISM - its Spanish language
support has been implemented in the front end. Based on a session variable,
conditional statements in the JSP pages generate either English or Spanish
language HTML for the viewer. This breaks our target of separating
functionality from presentation and was done due to shortage of time. We
realize that the best strategy in this situation is to extract all this information
into an XML document and to generate the front end pages dynamically
during run time. This is a cleaner design and lends itself to future expansion
to other languages in addition to English and Spanish. Changing this would
need a major refactoring of PRISM and is planned in the future. This would
also clean up all the messy JSP pages that are currently being used.
E. Middle Tier Detailed Design
Here is a block diagram that illustrates the major components in the PRISM
application and how messages are passed between them:
Welcome JSP Controller Medical
Other JSPs Servlet Assistant
All JSP pages post to a main dispatching Servlet, which in effect directs the
request to the corresponding processing Servlet for that request, i.e. database
processing, session management handling, or page branching logic. This design
allows us to quickly and effortlessly add new functionality to the application in
future by providing a new Servlet that implements this new functionality and
forwards the request.
All http requests post to the ProcessMainServlet servlet. Based on the first two
letters of the JSP page name, this servlet determines where to forward the
request. For the patient side of the application, the requests are dispatched to
the ProcessPatientServlet and for the medical assistant side, the requests are
dispatched to the ProcessAssistantServlet.
Once an http request has been forwarded to the appropriate servlet for
processing, that servlet performs all the required functions, then forwards the
response to the appropriate JSP page, which is displayed to the end user.
Therefore the only objects that have access or need access to the http request
object are the three servlet classes listed above. This has the effect of the URL
remaining unchanged throughout the course of the application.
For the patient application, the servlet determines the final page to which the
application branches based on the current page and how the user has answered.
It looks up the page name in the PatientDispatchTable. Based on whether the
page is a branching page, and the value of the associated branch question, the
servlet dispatches to the appropriate page. This “smart branching” saves the end
Session management is handled based on the current page being processed. If
the current page is the starting page for the application (pa_welcome.jsp for the
patient and ma_login.jsp for the assistant) the old session is invalidated and a
new session is created.
The main classes of our application are described below:
Abstract class DispatchTable: This is an abstract class that provides dispatch
table functionality. The dispatch table functionality allows the forwarding of posts
to the appropriate page, for example skipping certain pages based on user
response. The dispatch table stores PageObjects, which will be discussed later.
The dispatchTable contains methods to store and retrieve PageOjects which will
be similar across all of its child classes. The DispatchTable queries the Page
Object corresponding to the current page in order to see which page it should
display. Based on the responses from the query the DispatchTable makes a
decision about which page to display next.
Class PatientDispatchTable extends DispatchTable: This class provides the
Dispatch Table functionality for the patient screens. It instantiates the
PageObject for each patient page and installs them into the PatientDispatchTable.
It maps page names to the PageObject’s associated with that page. Whenever a
new patient page, i.e. question, needs to be added it must also be instantiated
and installed here.
Class PageObject: The PageObject is used to provide information about a
particular page, JSP page in this context. It provides information such as: the
name of the page, what fields/values the page branches on (i.e. uses conditional
logic to skip sections), the name of the page to forward to on a branch, and the
name of a page to forward on a forward with no branching.
Class PatientRecord: The PatientRecord class is holds all the patient information.
It stores the information as entered by the patient into the JSP pages. The JSP
pages have access to this object, as it is stored in the session. When a page is
forwarded, the middle tier, via the ProcessPatientServlet class, adds data to this
object. At the end of the process of entering the data, the middle tier posts to the
database from this object. Also, for returning patients with data already in the
database, this object is populated that data, which is therefore available to the
UI. This class essentially acts as the common conduit between the UI, the middle
tier and the database.
Class PatientSession: The PatientSession class contains a stack that works similar
to the back button in a web browser. It is used to ensure that when forwarding a
request to go back, the user follows the same sequence of pages that was
originally visited. This class implements the functionality of the back button.
Other information that is specific to a patient, such as the last question
completed, would be stored in this class.
Class ProcessMainServlet: This class is responsible for forwarding the request to
the appropriate servlet. It serves as a dispatch layer between the Servlets. Any
request is sent directly from Tomcat to this particular Servlet, and no processing
occurs here, the request is then forwarded to the Servlet where the processing
for this request will take place. For example, a request by the patient to go to the
next question would be forwarded to ProcessPatientServlet, which is described
Class ProcessPatientServlet: This class handles all of the requests made from the
patient pages. All of the processing for the help, forward, back, and exit buttons
on the patient pages occurs here. This class stores the information entered by
the patient into a PatientRecord object so that it can be retrieved later by the
report page. This class also uses a PatientSession in order to responds to user
requests needing to go back to the previous page. Similarly, the
PatientDispatchTable is queried each time the patient sends a forward request, in
order to determine which page the patient will be forwarded to next. Once the
request was forwarded, the name of the previous page is pushed onto the
PatientSession (which is a stack) so that it may be visited at a later time if the is
a back request.
Class ProcessAssistantServlet: This class handles all of the requests made from
the medical assistant pages. It works in conjunction with the Control object in the
session to access and change the fields in the patient record in the database.
Class Control: This class provides the main functionality for the database
connection. It creates and destroys the connection to the database. It provides
methods to add, change and retrieve data in the database.
Class Audit: This class wraps the audit record in the database with setters and
Class ContextListener: Instantiates and holds the Control and patientTable
objects. The objects are common to the entire application.
Class SessionListener: This class performs the session management for the
PRISM application. When a session is created by the servlet container, new
PatientRecord, PatientSession, and TranslateTable objects are instantiated and
stored as session attributes. This class also holds information about the state of
the current session, including whether the application is in edit mode, the
language to be displayed, and if the user has correctly logged into the
Class TranslateTable: This class holds a hashmap for translating English words
and phrases used by the UI into Spanish words and phrases.
- UML Diagrams will come here. -
F. Database Detailed Design
In total there are six tables in our current design. They are composed as follows:
Activation part(1 table) : Activation
User Authentication part (1 table): UserPasswd
Audit part (1 table): Audit
Patient information storage part (4 tables): tblIndividual stores single
value answers, PtMammogyears, PtFamilyCancers and PtOtherCancers
store the multi-value answers.
Our database design follows the E-R model. Actually, all four parts are Entities.
Except the authentication part which is independent of the rest, all tables are
connected via a foreign key: "MRN" & "Created". "MRN" represents blue card
number whereas "Created" stands for the created date time.
Here’s how this design looks like:
Primary keys and foreign Keys
Activation is the first table that the application uses. It has only two columns:
MRN and status. MRN is primary key and is referred by all patient information
tables. The default value of status is "off".
The primary key in the 4 patient information tables are composed of two
columns "MRN" and "Created". MRN is not unique in those tables since there
are previous records regarding to the same patient are stored in the same
table. The datatype of "Created" is datetime. It is almost always unique. All of
MRN column in the four tables are foreign keys, referring to "MRN" in the
Activation table. "MRN" in the Audit table is also set to be foreign key, refer to
"MRN" in table Activation. The primary key in table UserPasswd is
"userName". No foreign key. Null values are not allowed at each attribute.
In order to retrieve the most recent patient record more efficiently, indices
have been applied to four patient information tables. The index is set to two
columns: MRN and Created. Patient records will be sorted first based on the
blue number, then the created date time in descending order.
In order to allow data to be imported and exported between PRISM schema
and the current MGH database, some table name and column names follow
the MGH database schema.
Currently our database design allows a user to login to the database directly
(provided he/she has an account) and touch any data without leaving behind
an audit trail. This is a major deficiency that needs to be fixed in the future
version of PRISM. This will be achieved by having triggers in place that enter
an entry into the audit table for audit purposes according to HIPAA
regulations. Everything is tracked as long as the user accesses the database
We have also improved the design of the current database, but were not able
to implement it due to shortage of time. Here are the changes we propose:
Patient's name will be stored in Activation table and will be inserted when
activating the patient’s account. They are referred by the patient name in
table tblIndividual. The answers in breast history part are multi values so that
part will be moved out of table tblIndividual. Table PtBreastHistoryL and
PtBreastHistoryR will store this information.
Here is how this design will look like: