# Research required “Do the simplest thing that will work.” # BACK END / ARCHITECTURE ## DOCKER FINDINGS - Need a shared docker network between all containers, I was assuming could just redirect to localhost but didn't realize docker network is internal to docker - this helped https://stackoverflow.com/questions/39202964/how-to-reach-another-container-from-a-dockerised-nginx?rq=1 - first created a defined external network sudo docker network create docker-network - HOWEVER - I think docker has a default network so this external network probably isn't necessary, ??? MORE RESEARCH REQUIRED HERE - Then in the docker compose files of all involved had to put at the bottom one network statement (none in the service sections above) - networks: docker-network: driver: bridge - need to run Nginx in front of ayanova for easiest ssl cert handling etc - Very good reference here: https://gist.github.com/soheilhy/8b94347ff8336d971ad0 - Nginx needs to see ayanova via the docker host name which is the container name - So I had to point it like this: proxy_pass http://ayanova:7575; - Where ayanova is the image name in the docker compose file for starting AyaNova server ## DEFAULT PORTS (unassigned) http://www.iana.org/assignments/service-names-port-numbers/service-names-port-numbers.txt - Some available ports not specifically assigned that I like the look of: - 4048, 4144, 4194, 4195, 4196, 4198, 4317, 4318, 4319, 4332, 4337-4339 , 4363-4365, 4366, 4424, 4434-4440, 4748, 5076-5077, 5551-5552,5994-5998 - 7575-7587, 8084-8085 - 7575 (RAVEN IS USING THIS) - 5995? - 4424? - 8084? ## ?? LICENSING - ??how to functionally license RAVEN - ??how to protect the keys ## ?? How am I going to expose the api for developers - Only through the rest interface? - Will there be plugins at the backend code level in any of those layers? - OUR STUFF VS END USERS STUFF - What existing plugins did we make and what would they need from Raven to be replicated? - how will this affect api decisions? - What can end users be allowed to do and how and at what layer. ## ?? FUNCTIONAL REQUIREMENTS /FEATURES Look at AyaNova existing code, A) what worked well B) what was repetitious and should be automated C) what had ongoing problems Will help greatly with design ## TAGS - Wait to choose implementation type until basic design is decided upon as it will affect method use internally - This is actually a big adn tricky topic, here are some resources found while researching: - http://tagging.pui.ch/post/37027745720/tags-database-schemas - https://stackoverflow.com/questions/172648/is-there-an-agreed-ideal-schema-for-tagging - https://dba.stackexchange.com/a/35795 <---this is what I'm leaning towards - Leaning towards a single tags table with word and id (and maybe other properties like color, last used etc) - Each taggable other table has a map of it's own to the tags, so i.e.[TAGS: id, text] [CUSTOMERTAGS: customerID, tagId], [WORKORDERTAGS: WOID, tagID] - This will require a bit of complexity to keep it pruned though, i.e. tags will get orphaned when no one is using them so a routine will periodically need to clean them out. - This may be a better way to handle full text indexing as well with a search table for each object table. Kind of balloons the table count though, but who cares really, does that matter? - An alternative is exactly like how I do full text search in AyaNova now with a generic foreign key, upside is cleaner db structure, but downside is ensuring cleanup and maint. - If parent object is deleted must go in and remove any linked tags as well. - Upside is it's easily searchable for all incidents of a specific tag over all taggable types, but is this really necessary? It can still be done with separate queries. ** SEPARATE FOR *MVP* PRIORITY ONE IS MUST HAVE BEFORE RELEASE 8.0 / PRIORITY 2 OR LOWER IS NICE TO HAVE ** - go over all rockfish AyaNova related cases and request for features, into the hopper. - Move stuff to v8 if going forward, otherwise drop it's priority to lowest in AyaNova 7.x and any related project cases - Move any items that just have to be done now for v7 into high priority AyaNova 7.x track. - ?? What are the commonalities of things required in the UI to come from the backend based on current AyaNova - Name ID lists? - list factories - report factories - fetch by name / id - Email sending and processing ## ?? CONCURRENCY ISSUES - In the ef core book the author mentions getting around a concurrency issue by making it a non issue by not even updating the same order but instead appending status changes to another table - https://livebook.manning.com/#!/book/entity-framework-core-in-action/chapter-8/v-7/171 - "This design approach meant that I never updated or deleted any order data, which means that concurrent conflicts could not happen. It did make handling a customer change to an order a bit more complicated, but it meant that orders were safe from concurrent conflict issues." - Microsoft tutorial: https://docs.microsoft.com/en-us/aspnet/core/data/ef-mvc/concurrency - See what will be critical concurrency in RAVEN (inventory likely), see if can code around it so no concurrency can happen. - Plan on what is concurrency prone and how to deal with it. - Maybe split out the concurrent sensitive bits of a workorder (parts) to a different screen, i.e. show read only in workorder adn to update that specific section have to go in and do it like a wizard or something? ## ?? BACKDOOR / LOST PASSWORD - How to handle this, current method is horribly susceptable to nefarious purpose - Maybe requires "physical" access to the server (put a file up or something?) ## ?? AUTOMATED BACKGROUND PROCESSOR "GENERATOR" - What will replace "Generator" in RAVEN? ## FRONT END - VISUAL DESIGN / UX - - https://www.ventureharbour.com/form-design-best-practices/ - Make the form designs simple and beautiful, it will directly translate into sales - Field labels above fields, not beside them (https://research.googleblog.com/2014/07/simple-is-better-making-your-web-forms.html) - Single column vertical layout for complex forms is definitely best. In wide mode though what to do? - It's ok to have two inputs on a line together if they are directly related so that they have one single label above them and minimal space between them - i.e. date and time ([day] [month] [year] [hour][minute] etc) - But really don't if possible because it's never better than a single field that just "figures out" the parts of the input. - Always indicate required fields, don't just error if they are not filled out. - Break big forms into sections with shaded headers or emboldened headers with larger fonts but shaded background is good even with no text to break apart. - Use single fields for phone numbers or postal codes and process and interpret it through code rather than forcing them to use multiple fields as this causes confusion - Messages to users that are important and long and required to convey need to *really* stand out to even be read. In their own box with a different background or something alike. - Put validation errors to the right of the input field, not below it as users can see it better and it requires less cognitive load. - Multi page forms (like wizards) need to have progress indicators or people will get antsy and bail - Favor checkboxes or radio buttons over drop downs unless there are more than 6 or so options as they require less cognitive load - Use placeholders sparingly (light gray prompt inside input) only when there is ambiguity, don't use them for obvious stuff - Always use a predictive search / autocomplete for any field that requires a selection from a large number of options - Selectable images are the most compelling engaging selection type for users - I.E. like a row of radio buttons but a row of images to select from and the choice is the selection by clicking on the image. - People enjoy clicking on images. - Use this as much as possible wherever possible. I.E. for things like - A trial user picking the company type they would like to trial data for - Input fields should be sized to reflect the amount of data required to be entered in them - This helps the user understand what is required of them - ZIP code or house number should be much shorter than an address line for example - Do not rely on colour alone to communicate - 1 in 12 men have some degree of colour blindness - Ensure entire forms can be navigated using the tab key. - Test the form in low and bright light situations on a mobile device outdoors and desktop - Enable browser autofill with contextual tags - Not exactly sure what this means in practice but it sounds good - Use visual cues and icons, brains process visual cues way faster than text alone - Don't ask for a password twice, use a eyeball icon to reveal text instead like keepass does - Mobile should be at least 16px high text / desktop can be 14px - FRONT END FRAMEWORK - https://stackshare.io/stacks (interesting tool to see what other companies use in their stacks) - https://semantic-ui.com/ - Vue.js https://vuejs.org/v2/guide/comparison.html - JS IN HTML via directives (kind of like Angular) - State management library if required: https://github.com/vuejs/vuex - Similar to redux but different - Module for VS Code!! https://vuejs.github.io/vetur/ - PROS: - GUIDE: https://vuejs.org/v2/guide/ - Simpler to code than React "Vue has the most gentle learning curve of all js frameworks I have tried" - Single file components, all aspects of a component are in the same file (css, js, html) - UI LIBRARY: http://element.eleme.io/#/en-US - Everyone keeps claiming it's more productive - Comes with a databinding and MVC model built in - CLI project generator - Has official routing solution and state management solutions - They are starting to work on a native library like react native (not there yet though and maybe I don't care about that so much) - Getting things done over "purity" - http://pixeljets.com/blog/why-we-chose-vuejs-over-react/ - Working with html forms is a breeze in Vue. This is where two-way binding shines. - Vue is much simpler than AngularJS, both in terms of API and design. Learning enough to build non-trivial applications typically takes less than a day, which is not true for AngularJS - CONS: - Less answers on stackoverflow than React (for example) - Vue on the other hand only supports IE9+ (not sure if this is a con or not) - Doesn't have a major corporation behind it like React or Angular - (2016)runtime errors in templates are still a weak point of Vue - exception stacktraces in a lot of times are not useful and are leading into Vue.js internal methods - React.js - HTML in JS - PROS: - Very widely used, tons of resources - Works with huge apps - Can be compiled to native apps (somehow, though Vue is working on it) - CONS: - Requires a good grasp of javascript - Harder to code - Requires a *TON* of add-on libraries as it only deals with the view part - "PURITY" over getting things DONE - Very nitpicky and fuckery prone just to do things the official way, slower to get business objectives accomplished - Ember - PROS: - Requires less knowledge of javascript - Comprehensive includes all bits - Suited to small teams - CONS: - Angular - PROS: - Google and Microsoft supported - Supposed to be good for someone coming from C# (typescript) - CONS: - Requires a *lot* of learning to use - Typescript - Angular directives and ways of doing things which are peculiar to it - Possibly slower than others to render - ARCHITECTURE / TECHNOLOGY STACK - Electron hosted desktop app like vs code or Slack: - What is the advantage of Electron hosted app vs just a plain html 5 app? (nothing) - https://slack.com/downloads/windows - https://blog.bridge.net/widgetoko-a-node-js-and-electron-application-written-in-c-1a2be480e4f9 - PERFORMANCE: Do not send one byte extra that is not needed at the client - Not even a single space, - especially not extra libraries or unminified code or cases - ICONS and webfonts should have only what is needed, nothing more. - ??USING A CDN?? - VERSIONING STATIC RESOURCES - Use Gulp, process with hash *in filename* not as a query string (better supported by intermediate caching or proxy servers) - https://docs.microsoft.com/en-us/aspnet/core/client-side/using-gulp - https://code.visualstudio.com/docs/editor/tasks - https://hackernoon.com/how-to-automate-all-the-things-with-gulp-b21a3fc96885 - https://github.com/sindresorhus/gulp-rev - https://github.com/jamesknelson/gulp-rev-replace - FORM VALIDATION: - https://developer.mozilla.org/en-US/docs/Learn/HTML/Forms/Form_validation - ?? framework for complex UI required or plain old javascript? (imagine a workorder or PO) - Need a lot of shit on forms, maybe a framework is the way to go: - VALIDATION / DIRTY CHECK - AJAX FEEDBACK - ?? - ?? Funky graphs - ?? Markdown - Generate html pages from Markdown docs: https://github.com/Knagis/CommonMark.NET - Markdown UI editor I haven't evaluated yet: https://github.com/nhnent/tui.editor - ?? TESTING - ??Automated UI testing in browser. - To catch browser changes that break functionality. - Get a quick tool overview. - Also can it use diff. browsers and devices?