{"type":"doc","content":[{"type":"heading","attrs":{"level":3},"content":[{"text":"Project Name: DST Database/API Architecture","type":"text","marks":[{"type":"strong"}]}]},{"type":"paragraph","content":[{"text":"Date: 08/23/2022","type":"text","marks":[{"type":"strong"}]}]},{"type":"paragraph","content":[{"text":"Written By: Mikah Pinegar","type":"text","marks":[{"type":"strong"}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Introduction","type":"text","marks":[{"type":"strong"}]}]},{"type":"paragraph","content":[{"text":"This document will be the starting point for solidifying the thoughts from the meetings we’ve had thus far. Feel free to add or edit sections or leave comments. This process will need a lot of hands.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"System Overview","type":"text","marks":[{"type":"strong"}]}]},{"type":"paragraph","content":[{"text":"There are 5 tools meant to assist farmers in the cover crop decision making process. The goal is to modularize the tools in a way that will allow seamless navigation between the tools while still maintaining their independence.","type":"text"}]},{"type":"paragraph","content":[{"text":"The 5 tools are listed below","type":"text"}]},{"type":"orderedList","attrs":{"order":1},"content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Cover Crop Species Selector ","type":"text"}]},{"type":"orderedList","attrs":{"order":1},"content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"The species selector DST is used to help farmers select a cover crop that fits their goals and constraints. The user can either input specifics about their field location and cover cropping goals or explore cover crops without entering those details. The tool is mainly used to explore expert recommendations and ratings for cover crops in the farmer's USDA Plant Hardiness Zone. This allows farmers to make educated decisions that are best suited for their specific goals and can save time as opposed to calling the extension office.","type":"text"}]}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Cover Crop Economics Calculator","type":"text"}]},{"type":"orderedList","attrs":{"order":1},"content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"The economics calculator is used to help farmers get a quantitative idea of how much money it will cost to implement cover crops for their specific farms. They enter in data about their farm and the cover crops that they want to grow and the calculator will estimate the initial cost as well as the long term savings of cover cropping. This allows the farmer to make better informed financial decisions that are tailored to their situation.","type":"text"}]}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Cover Crop Nitrogen Calculator","type":"text"}]},{"type":"orderedList","attrs":{"order":1},"content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"The nitrogen calculator is used to help farmers by giving an estimate of the nitrogen output for a given cover crop. The farmer will enter data about their fields, cover crop(s), cash crop, and important dates and the model will output the expected nitrogen output as a function of time. It also is estimates the cash crop nitrogen uptake as a function of time.","type":"text"}]}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Cover Crop Seeding Rate Calculator","type":"text"}]},{"type":"orderedList","attrs":{"order":1},"content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"The seeding rate calculator is designed to help farmers determine the ratio of seeds needed to optimally cover crop their specific fields. The farmer will input metadata about the field and which cover crops they want to plant and the tool will give a recommendation about what ratio of seeds they should plant.","type":"text"}]}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Water Calculator","type":"text"}]},{"type":"orderedList","attrs":{"order":1},"content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"The water DST provides a Web interface and an API for the ","type":"text"},{"text":"MAIZSIM","type":"text","marks":[{"type":"link","attrs":{"href":"https://github.com/ARS-CSGCL-DT/MAIZSIM"}}]},{"text":" corn simulation model.","type":"text"}]}]}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Design Considerations","type":"text","marks":[{"type":"strong"}]}]},{"type":"paragraph","content":[{"text":"There will be 5 independent DSTs that will have a shared user history and some inputs and outputs will be shared between tools.","type":"text"}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"Assumptions and Dependencies:","type":"text","marks":[{"type":"strong"}]}]},{"type":"paragraph","content":[{"text":"Each DST needs to be fully independent and be able to easily be moved to a different provider. We want to have shared user experience data for our first iteration but we don’t want this user data to bog down the individual DST DBs in the event that a big provide (Bayer, John Deere, ","type":"text"},{"text":"Farmers.gov","type":"text","marks":[{"type":"link","attrs":{"href":"http://Farmers.gov"}}]},{"text":", etc.) decides to acquire any of the tools.","type":"text"}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"General Constraints","type":"text","marks":[{"type":"strong"}]}]},{"type":"paragraph","content":[{"text":"We want new members of the team to be able to quickly get up to speed with how things are architected and not get slowed down with one off design choices.","type":"text"}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"Goals and Guidelines","type":"text","marks":[{"type":"strong"}]}]},{"type":"paragraph","content":[{"text":"The tools should all follow the best practices outlined in the ","type":"text"},{"type":"inlineCard","attrs":{"url":"https://precision-sustainable-ag.atlassian.net/wiki/spaces/ON"}},{"text":" space.","type":"text"}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"Development Methods","type":"text","marks":[{"type":"strong"}]}]},{"type":"paragraph","content":[{"text":"We will be using a simple version of the scrum methodology.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Architectural Strategies","type":"text","marks":[{"type":"strong"}]}]},{"type":"paragraph","content":[{"text":"The front end will be written in React, and styled using material ui. The API language will be Node.js (TBD). The databases will be PostgreSQL. DevOps TBD.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"System Architecture First Draft","type":"text","marks":[{"type":"strong"}]}]},{"type":"paragraph","content":[{"text":"This is the first draft overview of the design discussed in the 8/22/22 DST meeting.","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Each DST will have its own PostgreSQL database that only stores the data and logging needed to make the app run (no user history)","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Each DST will have its own API (first guess Node.js) that will interact with its DB. This API will likely only be reading data and will not need authentication","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"The API will represent the app as a whole: it will take the inputs and return a recommendation","type":"text"}]}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"There will be a shared PostgreSQL DB and API that requires authentication that will hold user history and meta data to be used throughout all the DSTs","type":"text"}]}]}]},{"type":"mediaSingle","attrs":{"layout":"center","width":100.0},"content":[{"type":"media","attrs":{"width":756,"id":"faab666e-af9b-40c6-87d2-32beb6911dc4","collection":"contentId-167837762","type":"file","height":648}}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Each DST will be able to be used via its API alone so that they can call any of the others and get a recommendation. This will be important for setting default values etc.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Three user tiers for the applications that the user will choose from","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Anonymous ","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"no history between visits","type":"text"}]}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Logged in but data is not to be used for research or aggregated (default)","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Users will have history between visits and be able to view their previous recommendations and info about their farms","type":"text"}]}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Logged in and data can be used for research or aggregated","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Users will have history between visits and be able to view their previous recommendations and info about their farms","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"We will be able to analyze this user data for research purposes","type":"text"}]}]}]}]}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"System Architecture Second Draft","type":"text","marks":[{"type":"strong"}]}]},{"type":"paragraph","content":[{"text":"This is the second draft overview of the design based on meetings","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Each DST will have its own PostgreSQL database that only stores the data and logging needed to make the app run (no user history)","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Each DST will have its own node.js API that will interact with its PostgreSQL DB","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"The API will represent the app as a whole: it will take the inputs and return a recommendation without the need of a front end. This will be important for setting default values for the other DSTs etc.","type":"text"}]}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"There will be a shared PostgreSQL DB and API that requires authentication that will hold user history to be used throughout all the DST front ends","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"There will be a shared PostgreSQL DB and API that will hold shared cover crop data to be used throughout all the DST APIs","type":"text"}]}]}]},{"type":"mediaSingle","attrs":{"layout":"center"},"content":[{"type":"media","attrs":{"width":342,"id":"540a5e14-4ca5-4b94-8cdc-0a5b96515a9f","collection":"contentId-167837762","type":"file","height":283}}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"The shared CC data will be the single source of truth, and the entry point for maintaining general cover crop data. The Shared CC Data API will utilize the ","type":"text"},{"text":"observer pattern","type":"text","marks":[{"type":"link","attrs":{"href":"https://refactoring.guru/design-patterns/observer"}}]},{"text":" to ensure that any service that subscribes to it will always be notified when data changes occur, and it will be the responsibility of the subscribed service to update its databases. This allows any service that depends on cover crop data the ability manage its own data dependencies and creates a loose coupling, giving all services the ability to be cloned and capable of running without the need of external resources, but will be able to utilize the Shared CC Data as an external data source.","type":"text"}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Detailed System Design","type":"text","marks":[{"type":"strong"}]}]},{"type":"panel","attrs":{"panelType":"note"},"content":[{"type":"paragraph","content":[{"text":"Shared CC Data Database Diagram","type":"text","marks":[{"type":"strong"},{"type":"link","attrs":{"href":"https://whimsical.com/shared-cc-data-db-Qhk33PJg5d26TKpHFXaw1b"}}]}]}]},{"type":"panel","attrs":{"panelType":"note"},"content":[{"type":"paragraph","content":[{"text":"Species Selector Database Diagram","type":"text","marks":[{"type":"strong"},{"type":"link","attrs":{"href":"https://whimsical.com/species-selector-db-9JJrHXLxpYCVsszhrWyQRt"}}]}]}]},{"type":"panel","attrs":{"panelType":"note"},"content":[{"type":"paragraph","content":[{"text":"Shared CC Data API Observer Notification Flow Chart","type":"text","marks":[{"type":"strong"},{"type":"link","attrs":{"href":"https://whimsical.com/shared-cc-data-observer-flow-diagram-N2gomFX5ddnhd1n8amPFp9"}}]}]}]},{"type":"paragraph","content":[{"text":"CC Image Storage","type":"text","marks":[{"type":"strong"}]}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Store original resolutions images in azure blob storage","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Folder structure will be // so it’s obvious to the users what images are associated with what crops and where to put new images","type":"text"}]}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Store metadata in a table inside the shared CC data DB so it doesn’t need to get split out of the file name","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Resize the images in the front end using CSS","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Return image metadata and locations with routes like below","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"List all species (ex GET /images)","type":"text"}]},{"type":"codeBlock","attrs":{"language":"json"},"content":[{"text":"[\n {\n \"ccName\": \"Alfalfa\",\n \"images\": [\n {\n \"imageURL\": \"\",\n \"isThumbnail\": \n \"growthStage\": \"\",\n \"owner\": \"\",\n \"yearTaken\": \"\",\n \"notes\": \"\"\n },\n ...etc\n ],\n },\n ...etc\n]","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"List a specific species (ex GET /images/)","type":"text"}]},{"type":"codeBlock","attrs":{"language":"json"},"content":[{"text":"{\n \"ccName\": \"Alfalfa\",\n \"images\": [\n {\n \"imageURL\": \"\",\n \"isThumbnail\": \n \"growthStage\": \"\",\n \"owner\": \"\",\n \"yearTaken\": \"\",\n \"notes\": \"\"\n },\n ...etc\n ],\n},","type":"text"}]}]}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Phases","type":"text","marks":[{"type":"strong"}]}]},{"type":"orderedList","attrs":{"order":1},"content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Research","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Design meeting","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Architectural decisions","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Implementation","type":"text"}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Glossary","type":"text","marks":[{"type":"strong"}]}]},{"type":"paragraph","content":[{"text":"An ordered list of defined terms and concepts used throughout the document.","type":"text"}]},{"type":"table","attrs":{"layout":"default","localId":"04c857c9-3cb3-4257-99be-4968484df9d7"},"content":[{"type":"tableRow","content":[{"type":"tableHeader","attrs":{"colspan":1,"rowspan":1,"colwidth":[284.0]},"content":[{"type":"paragraph","content":[{"text":"Term","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"tableHeader","attrs":{"colspan":1,"rowspan":1,"colwidth":[474.0]},"content":[{"type":"paragraph","content":[{"text":"Definition","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"tableHeader","attrs":{"colspan":1,"rowspan":1,"colwidth":[506.0]},"content":[{"type":"paragraph"}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[284.0]},"content":[{"type":"paragraph","content":[{"text":"Application Protocol Interface (API)","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[474.0]},"content":[{"type":"paragraph","content":[{"text":"A tool that allows two programs to talk to each other.","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[506.0]},"content":[{"type":"paragraph"}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[284.0]},"content":[{"type":"paragraph","content":[{"text":"Database (DB)","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[474.0]},"content":[{"type":"paragraph","content":[{"text":"A structured set of data held in a computer","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[506.0]},"content":[{"type":"paragraph"}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[284.0]},"content":[{"type":"paragraph","content":[{"text":"Decision Support Tool (DST)","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[474.0]},"content":[{"type":"paragraph","content":[{"text":"A tool used to aid the user in making a decision","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[506.0]},"content":[{"type":"paragraph"}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[284.0]},"content":[{"type":"paragraph"}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[474.0]},"content":[{"type":"paragraph"}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[506.0]},"content":[{"type":"paragraph"}]}]}]},{"type":"paragraph"}],"version":1}

Browser not supported