Skip to content

Commit 213198f

Browse files
ScottSucksAtProgrammingScottSucksAtProgramming
committed
Update design doc
1 parent 954dda3 commit 213198f

12 files changed

+676
-0
lines changed

‎docs/design/00_design_overview.md

+77
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,77 @@
1+
# Design Doc Part 0 - Overview / Table of Contents
2+
3+
|Section | Version | Created | Updated |
4+
|:-------| :------ | :--------- | :--------- |
5+
| 0 | 0.1.0 | 08/01/2022 | 08/24/2022 |
6+
7+
{{TOC}}
8+
9+
## Summary
10+
11+
Welcome to the **Narcotics Tracker**! This software is designed to assist controlled substance agents working at EMS agencies with inventory tracking and periodic reporting of controlled substance activities to their governing agencies.
12+
13+
### Motivation
14+
I am a controlled substance agent working in New York State. The tracking of controlled substances is complicated and requires multiple forms and processes. I have wished for a single place where all of that information can be stored and easily accessed. This software is intended to fill that need.
15+
16+
### Goals
17+
18+
The **Narcotics Tracker** will provide a single place to enter all changes to an agencies controlled substance inventory. Each change in the inventory can be entered peridoically where the data can be queried to return information requried for reporting and compliance with tracking specifications.
19+
20+
##### Project Specifications
21+
1. Inventory tracking of all controlled substances used by an EMS agency.
22+
2. Ability to create agency specific medications.
23+
3. Tracking of medication lots as they as disbursed to sub-stocks.
24+
4. Tracking of medication orders.
25+
5. Tracking of medication destruction.
26+
6. Tracking of medication administration.
27+
7. Tracking of medication waste.
28+
8. Built in reports which can be generated at the users request which fulfill the New York State and DEA requirements.
29+
9. A simple but powerful console user interface.
30+
10. A graphical user interface.
31+
32+
I am a self-taught programmer looking to improve my knowledge and experience in soft-ware design by building projects which have practical applications.
33+
34+
##### Personal Learning Goals
35+
1. Increase my knowledge and experience with Python.
36+
2. Learn about Object Oriented Programming.
37+
3. Practice and gain experience with Test Driven Development
38+
4. Gain knowledge on the storage, and manipulation, of data and the use of databases.
39+
5. Potentially branch out into GUI development with Python or different languages as necessary.
40+
6. To put out a product which I may be able to use to help generate extra income though licensing and service contracts.
41+
42+
## Development Roadmap / Progress
43+
44+
I'm not entirely sure where the best place to begin is. I do not have a enough
45+
experience to know how to design this kind of software. I'll be using a lot of
46+
trial and error. Here is my imagined development Path.
47+
48+
- [x] Medication Creation and Management
49+
- [x] Builder Pattern
50+
- [x] Communication with a Database
51+
- [ ] Inventory Management
52+
- [ ] Medication Use
53+
- [ ] Medication Waste
54+
- [ ] Medication Destruction
55+
- [ ] Medication Orders
56+
- [ ] Lot Management
57+
- [ ] Agent Management
58+
- [ ] Provider Management
59+
- [ ] Report Generation
60+
- [ ] Console User Interface
61+
- [ ] Graphical User Interface
62+
63+
## Table Of Contents
64+
65+
* [Medications](01_medications.md)
66+
* [Database](02.database.md)
67+
* [Inventory](03_inventory.md)
68+
* Medication Use
69+
* Medication Waste
70+
* Medication Destruction
71+
* [Medication Orders](07_orders.md)
72+
* Lot Management
73+
* Agent Management
74+
* Provider Management
75+
* Report Generation
76+
* Console UI
77+
* Graphical UI

‎docs/design/01_medications.md

+244
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,244 @@
1+
# Design Doc Part 1- Medications
2+
3+
|Section | Version | Created | Updated |
4+
|:-------| :------ | :--------- | :--------- |
5+
| 1 | 0.1.0 | 08/25/2022 | 08/25/2022 |
6+
7+
{{TOC}}
8+
9+
## Medication Creation and Management
10+
In order to track the inventory of controlled substance medications a model of the medications has to be built within the program. I decided to start the probject by building a module to handle the creation and implementation of medications.
11+
12+
Medications will be similar across EMS agencies but the specific dosages, concentrations and other attributes of the meds will vary. There are many specifics for controlled substance medications but I narrowed it down to 7 medication specific attributes and 5 which will be important to working with the medication as part of the database.
13+
14+
##### Medication Facing Attributes
15+
16+
- name (str): The name of the medication.
17+
18+
- container_type (containers.Container): The type of container the medication comes in.
19+
20+
- fill_amount (float): The amount of the solvent in the container. Measured in milliliters (ml).
21+
22+
- dose (float): The amount of medication in the container.
23+
24+
- preferred_unit (units.Unit): The unit of measurement the medication is commonly measured in.
25+
26+
- concentration (float): The concentration of the medication to its solvent.
27+
28+
- status (medication_status.MedicationStatus): The status of the medication.
29+
30+
31+
##### Database Facing Attributes
32+
33+
- medication_id (int): The numeric identifier of the medication in the database.
34+
35+
- code (str): The unique identifier for the specific medication.
36+
37+
- created_date (str): The date the medication was first entered into the database.
38+
39+
- modified_date (str): The date the medication was last modified in the database
40+
41+
- modified_by (str): The user who last modified the medication in the database.
42+
43+
44+
A list of five main requirements for controlled substance medications were identified.
45+
##### Medication Behaviors
46+
1. Creation of new medications by users.
47+
2. Saving of medications within the database.
48+
3. Loading of saved medications.
49+
4. Updating of saved medications.
50+
5. Deletion of medications from the database.
51+
52+
## Discussion
53+
### Attributes
54+
55+
**The NDC Number was removed from the list of attributes.** The NDC number is only important for medication destruction. NDC Numbers change between manufacturers and concentrations for the same medication. NDC Numbers may not be tracked at all within the Narcotics Tracker, if they are going to be tracked they will be part of a different module.
56+
57+
- - -
58+
59+
**The Box Quantity was removed from the list of attributes.** Box Quantity (how many containers come in the box) will be important for Orders and Lot Management but not as part of the medication module.
60+
61+
### Medication Data Structures
62+
There were tons of ways to represent medications within the **Narcotics Tracker**. Ordered lists and dictionaries are simple and would fulfill most of the requirements. As of version 0.1.0 dictionaries are used to load medications as objects from data stored in the database and lists are used in a script to quickly create the medications I personally use at my agency. **I decided that using classes and objects would be the best way for me to achieve the results I wanted with this project and help me improve my object oriented programming skills.**
63+
64+
### The Builder Pattern
65+
Since I decided to go with objects as the data structure for medications I needed a way to simplify the creation of medications for myself as the developer and for the users. With twelve total attributes it would be easy to assign values to the wrong attributes, forget attributes and potentiall build medications which would be unusable.
66+
67+
**I employed the builder pattern to separate to separate the creation of medications into smaller, easier to understand steps. Using the builder pattern does add complexity to the code it also adds the flexibility to use the same approach to different objects used later within the Narcotics Tracker.**
68+
69+
### Enums vs. Vocabulary Control Tables
70+
There are limited options for the types of containers a controlled substance medication might come in. The status of each medication and it’s preferred dosage unit also have limited options.
71+
72+
As of the version 0.1.0 release Enums were created for each of those three attributes and are handled through Python and it’s objects. It was brought to my attention that this will limit the flexibility for users who may need to create custom options for these attributes.
73+
74+
**In a future release these Enums will be converted in vocabulary control tables within the datbase. This will allow for users to create new statuses, containers, and units as needed for their agency.**
75+
76+
### Medication Deletion
77+
It’s likely that deleting medications will cause issues in long term record keeping. Attributes for medications which are no longer in use are important when pulling records from previous periods when they were in use. Deletion of medication is likely not going to be a feature that the users will have access to. **Deleting Medications is important enough for this option to be available during development of the Narcotics Tracker that I have chosen to build it.** It can be removed later if deemed unnecessary.
78+
79+
### Communication with a Database
80+
Databases are used everywhere in software and I’ve never worked with one. The **Narcotics Tracker** is an ideal project for me to dip my toes in and build my understanding of databases. Other method for storing data were considered such as writing to JSON Files, CSV Files and Pickle Files but the strengths of using a database made it an obvious choice.
81+
82+
The only attribute required for the database is the connection to the database file. A
83+
84+
###### Database Attributes
85+
- database_connection (sqlite3.Connection): The connection to the database file.
86+
87+
###### Database Behaviors
88+
1. Creation and connection with a database file.
89+
2. Creation of tables within the database.
90+
3. Querying of table names from the database file.
91+
4. Querying of columns names from database tables.
92+
5. Updating tables within the database.
93+
6. Deleting tables from the database.
94+
7. Writing data to the database.
95+
8. Reading data from the database.
96+
9. Loading objects from data saved in the database.
97+
10. Setting of the dates when saving objects to the database.
98+
99+
#### Discussion
100+
##### Attributes
101+
There were not many other attributes I thought would be important to store within the database objects. **One attribute which may be added later is the path to the data directory.** Currently the path is hard coded into the methods, but it might make sense to give users an option on where they want their database files to be stored.
102+
103+
##### Database Choice
104+
**I decided to use SQLite3 for this project.** SQLite3 is built into Python. It requires no configuration or external services, and I already watched a course on using it, so there!
105+
106+
##### Database Tables
107+
Multiple tables will be required for the inventory tracking portion of this project:
108+
109+
**Inventory Tables**
110+
111+
1. Medication Table
112+
2. Order Table
113+
3. Lot Table
114+
4. Administration Table
115+
5. Inventory Table
116+
6. User / Agent Table
117+
118+
In addition vocabulary control tables will be required to help set the specific types of data and events in the project:
119+
120+
**Vocabulary Control Tables**
121+
122+
1. Medication Containers
123+
2. Medication Statuses
124+
3. Medication Units
125+
4. Order Statuses
126+
5. Order Suppliers
127+
6. Inventory Events
128+
129+
130+
131+
1. Containers Table
132+
2. Medication Statuses Table
133+
3. Dosage Units Table
134+
4. Events Table
135+
136+
Additional tables may be identified as the project progresses.
137+
138+
### Tracking of Controlled Substance Orders
139+
Ordering controlled substance medications are one of the only ways new stock gets added into the inventory. They are integral to this project and are next up on my list of features to add.
140+
141+
142+
##### Order Attributes
143+
- order_id (int): The numeric identifier of the order in the database.
144+
145+
- po_number (str): The unique identifier for the specific order.
146+
147+
- date_ordered (str): Date the order was placed.
148+
149+
- medication_code (str): `medication.Medication.code` of medications ordered.
150+
151+
- containers_amount (int): The number of containers for the medication ordered.
152+
153+
- supplier (Enum): The name of the supplier.
154+
155+
- supplier_order_number (str): The suppliers order number for reference.
156+
157+
- dea_form_number (str): The number of the 222 form used to order Class II medications. (Optional)
158+
159+
- date_received (str): Date a package is received.
160+
161+
- packages_received (int): Number of packages of a specific medication received.
162+
163+
- comment (str): Any comments or additional details for the order.
164+
165+
- status (Enum): The status of the order.
166+
167+
- created_date (str): The date the order was first entered into the narcotics tracker.
168+
169+
- modified_date (str): The date the order was last modified.
170+
171+
- modified_by (str): The user who last modified the order.
172+
173+
##### Order Behaviors
174+
- Creation of new orders.
175+
- Saving of orders to the database.
176+
- Loading of orders from data.
177+
- Updating orders.
178+
- Deleting orders.
179+
180+
181+
182+
183+
#### Discussion
184+
##### Attributes
185+
Currently my controlled substance orders are tracked in a spread sheet. The following attributes are tracked.
186+
187+
Row Number, Purchase Order Number, Date Ordered, Medications and Amount Ordered, Supplier, Supplier Order Number, 222 Form Number, Dates Received, Packaged Received, Comments / Notes.
188+
189+
The Purchase Order Number will be the user-facing unique identifier for the order.
190+
191+
Because medications can be received in different shipments a compound or composite primary key (Purchase Order Number AND Medication) need to be used to ensure that this can be acommodated.
192+
193+
##### Behaviors
194+
The process for ordering medications is located in `docs/design/user_processes.md`
195+
196+
**New Orders**
197+
* Orders have to be created.
198+
* PO Number is assigned.
199+
* Spreadsheet is filled out with initial info:
200+
* Purchase Order Number,
201+
* 222 Form Number,
202+
* Date Ordered,
203+
* Medications and Amounts Ordered
204+
* Order Status is set to ‘Open’.
205+
206+
**Shipment is Received**
207+
* Spreadsheet is updated:
208+
* Date Shipment Received
209+
* Medications and Amounts in shipment
210+
* Lot number of Medications.
211+
* Stock Inventory Sheet (DOH-3850) created for each Lot.
212+
* Medications are added to the inventory.
213+
* Repeated for any additional shipments.
214+
* When all medications are received the Status is set to ‘Closed’.
215+
216+
What would This look Like?
217+
1. USER: Places and order with the supplier. Forms are filled out and all paperwork is filed.
218+
2. USER: Creates a New Order.
219+
3. USER: Fills in attributes.
220+
4. PO Number
221+
5. Date Ordered
222+
6. Medication Ordered
223+
7. Amount Ordered
224+
8. 222 Form Number (if applicable)
225+
9. Status set to ‘Open’.
226+
10. USER: Receives medications. Forms a filled out and filed. Medications are placed in safe.
227+
11. USER: Loads Order via PO Number.
228+
12. USER: Updates Order:
229+
13. Date Received
230+
14. Medication Received
231+
15. Amount Received
232+
16. NARCOTICS TRACKER: Creates an Add event in the Inventory Table sending the Medication info, date received, amount in mcg, and the PO Number.
233+
17. NARCOTICS TRACKER: Creates a new Lot Table passing the Lot Number, Amount of Medication, Date, and PO Number for reference.
234+
18. USER: Sets Medication Order to ‘Closed’
235+
236+
##### Tables Needed
237+
* Order Table
238+
* Order Status Table (Vocabulary Control Table)
239+
* Open; Closed; Delayed; Cancelled
240+
* Supplier Table (Vocabluary Control Table)
241+
* BoundTree Medical;
242+
* * Lot Table (To be implemented in a future update)
243+
* Inventory Table (To be implemented in a future update)
244+
* Events Table (To be implemented in a future update)

0 commit comments

Comments
 (0)