-
Notifications
You must be signed in to change notification settings - Fork 5
Courtbot Design Specification
This courtbot application exists to assist people who need to attend court in Santa Clara County, California. It will provide timely reminders that help people remember when they need to be at court. Missing a court date generally adds additional burden to a person who may already be in financial distress, so this tool is aiming to improve the chances that a person would show up in court.
Basic:
- User provides a phone number and a case number to be alerted for via a web form (or text).
- User is notified via text - alerting them that court date is imminent. The frequency of notification is constant (ie no user customization)
Nice to have:
- User may have preferences on when to be notified / and frequency. There will be a limit to the length depending on the data retrieved.
- User may want to stop notification for the specific case. We may additional provide court location information as part of the text. Links to directions, via car or public transportation.
The application will consists of 4 main components as described below:
- UI frontend
- Data / REST services
- Notification scheduler
- Notifier service
Minimal frontend is needed for this application. This will need to be hosted somewhere and that the connection is secure.
- User adds notification by providing data to the frontend.
- REST:
- Data is passed to the next layer for add (REST / CREATE )
- (optional) Data may be validated against Santa Clara county court case data (internal REST)
- User receives feedback that the information is received and processed.
- User can be notified whether this is a valid case number or not.
- REST:
Optional enhancements:
- User can retrieve notification information and adjust notification frequency
- REST:
- Data can be retrieved (REST / GET)
- Data can be updated. NOTE: phone number + case number combo is the key to the record. (REST / POST)
- REST:
- User removes notification by providing data to the frontend. Or as part of the notification to "STOP"
- REST:
- Data is passed to the next layer for remove (REST / DELETE)
- User receives feedback that the information is received and processed.
- REST:
The REST services provided will have a few functions:
- CREATE/DELETE/GET: function for case number + phone number data.
- These information will need to be stored in a table.
- Additional data may be associated with it - such as frequency of notification etc.
Optional:
- POST: function to updated associated data that are retrievable with case and phone number.
See detailed discussion on data in the original documentation:
- A database storing case number with a phone number is needed. (REQUESTOR)
- NOTE: it is possible that multiple phone numbers can be associated with a case, and that multiple case can be associated with one phone number.
- Optionally, a table storing court calendar data can be made available. (COURT_CAL)
- table will need to store: case number -> court date / time
- If this table exists, a job will needs to be setup to ensure data integrity is preserved. In addition, potential uses during detection of change:
- if case number moved to later dates/closer dates - information can be used to alert to users that date has changed. (Leverage Notification service)
- if case number no longer exists (ie moved to later dates outside of scanning range? or settled out of court?)- what to alert?
- if case status changed?
- etc?
The court website in Santa Clara County has a REST service behind it which vends data as JSON files. The keys to each court appearance on the calendars consists only of the case numbers, the list of parties and the scheduled time for the court appearance.
Strictly speaking, this service does not require any links to anything but the case number and scheduled time. The name of the parties may be helpful if we have an interface through which someone can locate their case, but this feature is not planned for the current release. On the other hand, we get the parties information with the response no matter what. It is just as easy to store it as not, while the application is not storage-constrained.
The notification service includes all functions to notify the user when a court date is imminent.
- A script / job / service needs to determine which case needs to be notified base on date criteria ** This can be calculated via the live court calendar data or against the existing database (COURT_CAL) ** This calculation might be done via database joins. (REQUESTOR join COURT_CAL on case number & date)
- This sends a text to the number associated with case that needs to be notified.
- On sending of a text. ** (optional) Can be an opportunity to store additional data to indicate notified, or previous status.
- Deployment.
- Court cases may have multiple hearings - Do we need a function to purge?
- What do we do when court dates changes? (say if we notified that case is happening in 2 days, then case date change to 5 days later - outside of the range we did not evaluate). This would be confusing to the user.
- FYI any user can request notification of anyone's court dates. This is not disallowed, or even noticed, by this app.
- See OWASP Cheat Sheet for how to store phone numbers and other PII securely.
(Ying's version of this document has been merged in after these comments were provided.)
ying: The actual elaboration of the design is a bit terse, please expand them.
rrk: I think it makes sense that a first version is a bit terse. We can all participate in writing this, yes? ("Version control means never having to say you are sorry.")
ying: Other content relating to data has been discussed in the tasks as well as in the meeting-minutes. They are good to include to explain why we determine what data is needed.
rrk: I am not sure about this suggestion. I think that meeting minutes stand by themselves, to represent the discussion that occurred in the meeting. This design document is an attempt to capture my thoughts on the design. I do not feel that I should or can represent someone else's viewpoint. Anyone can make changes to the design doc if they feel that they made a point in a meeting which is not captured in it.
ying2: It was a statement about how the data was included. We probably should include data in the design consideration section
ying: 1. Please add additional details to the UI and user experience. (component 1)
- What does this UI do ?
- What REST services would this UI require?
- Is this UI mobile enabled? web page? etc?
rrk: I am deliberately not giving much detail to the UI design. UI design is not really in my skill set. For myself, I do apps that showcase data and I have minimal UIs for them. Can someone else take on this job? Or can we find someone to do it?
ying2: That is ok. The idea for design doc is to have a vision of how this application should work. We can hash it out as a team.
ying: 2. Please add additional details to the data service. (component 2)
- What does this data service do?
- Is this the REST services that this UI connects to?
rrk: I have not gotten to designing the REST endpoints yet. The data job is always the same though: CRUD (Create, Retrieve, Update, Delete). The answer to the second question is yes.
ying2: Ok. We may do: frontend <-> frontend REST <-> backend REST. This shields the backend REST api to be exposed. But we can think about it.
ying: 3. Notification of court date / services (component 3)
- Is this a cron job? or is this service triggered when?
- If this is a cron job, then how often would this run?
rrk: This is an implementation question, and not really something needed in a design document. If we decide, in the design document, that notifications should be go out on a schedule, then an implementer can find any of a number of tools to do that.
ying2: We should decide on the behavior, so that there are enough details for people who want to implement this.
ying: 4. Data details. It seems that the discussion goes back/forth relating to whether we keep data or we don't keep data.
- per "Connecting Court Appearances and Phone Numbers" - i think we will be keeping phone data. I also agree that we don't need to require that the person wanting to be notified for a specific case is related to the case. Any phone number should be fine.
rrkL +1
ying: 5. Any particular framework for these tasks ?
rrk: I am not trying to answer this question yet.
ying2: ok.