Documentation System Requirement Specification (SRS) (#626)

* update our contributing guide to be more concise

* add info on new mock hazardous waste handlers and development configs

* move 'haztrak_book' to 'guide' so our documentation URL do not have an underscore in them, and add a link to edit our documentation

* add SRS document and move requirement specifications from SDD to new file

* expand the architecture of the react client documentation

* remove reduendant source design documentation

.github/CONTRIBUTING.md

@@ -2,4 +2,4 @@
 
 See our contributing guide at https://usepa.github.io/haztrak/development/contributing.html
 
-Markdown file version of our documentation can be found [here](/docs/haztrak_book/src)
+Markdown file version of our documentation can be found [here](/docs/guide/src)

.github/workflows/docs.yaml

@@ -23,7 +23,7 @@ jobs:
     runs-on: ubuntu-latest
     defaults:
       run:
-        working-directory: ./docs/haztrak_book
+        working-directory: ./docs/guide
     steps:
       - name: 'Checkout Repo'
         uses: actions/checkout@v2
@@ -39,7 +39,7 @@ jobs:
       - name: 'Upload Docs'
         uses: actions/upload-pages-artifact@v1
         with:
-          path: ./docs/haztrak_book/book
+          path: ./docs/guide/book
 
   deploy_pages:
     name: 'Deploy Documentation'

docs/README.md

@@ -2,4 +2,4 @@
 
 See our full documentation at https://usepa.github.io/haztrak/
 
-The source for the documentation is found in the [haztrak_book](./haztrak_book) directory
+The source for the documentation is found in the [haztrak_book](./guide) directory

docs/guide/book.toml

@@ -0,0 +1,17 @@
+[book]
+authors = ["David Paul Graham"]
+language = "en"
+multilingual = false
+src = "src"
+title = "Haztrak Documention"
+description = "An open-source web application for tracking hazardous materials shipments."
+
+[output.html]
+default-theme = "light"
+preferred-dark-theme = "navy"
+git-repository-url = "https://github.com/USEPA/haztrak"
+edit-url-template = "https://github.com/usepa/haztrak/edit/main/docs/guide/{path}"
+
+[output.html.fold]
+enable = true
+level = 1

docs/guide/src/design/browser-client.md

@@ -0,0 +1,113 @@
+# Haztrak Client Architecture
+
+## Application Overview
+
+The browser client is a single page application (SPA) that uses the [React library and ecosystem](https://react.dev/) to client side render the user interface. It is responsible for guiding the
+user during the creation, editing, and signing of electronic manifests.
+
+## Application Configuration
+
+The project was originally bootstrapped with `Create React App` but was transitioned to use the `Vite`
+build tool. For more information on Vite, see the [Vite documentation](https://vitejs.dev/). The configuration is found in `./client/vite.config.ts`.
+
+The following tools have been configured to aid development:
+
+### ESLint
+
+The project uses ESLint to lint the codebase and prevent developers from making common/easy to fix mistakes and enforce consistency. For more information on ESLint, see the [ESLint documentation](https://eslint.org/).
+
+### TypeScript
+
+While ESLint is great for catching common little mistakes related to JavaScript, TypeScript is a superset of JavaScript that adds type checking. It's a great tool for catching more complex mistakes and preventing them from making it into production. For more information on TypeScript, see the [TypeScript documentation](https://www.typescriptlang.org/). TypeScript is configured in `./client/tsconfig.json`.
+
+### Prettier
+
+Prettier is a tool for formatting. If enforces a consistent style across the entire codebase and amongst multiple developers, thereby making the codebase more readable and maintainable. For more information on Prettier, see the [Prettier documentation](https://prettier.io/).
+
+## Style Guide
+
+### Clean Code
+
+A classic book on writing clean code is [Clean Code: A Handbook of Agile Software Craftsmanship](https://www.amazon.com/Clean-Code-Handbook-Software-Craftsmanship/dp/0132350882). It's a great read and highly recommended.
+
+### Naming Conventions
+
+Haztrak recommends reading this [naming convention guide](https://github.com/kettanaito/naming-cheatsheet) hosted on github that (conveniently) uses javascript.
+
+In addition, the project uses the following naming conventions for various items:
+
+#### Selectors
+
+Selectors are functions that take the state as an argument and return some data from the state.
+They are used to encapsulate the state shape and allow us to change the state shape without having
+to change all the places where we access the state.
+
+We use two naming conventions for selectors:
+
+1. `<stateField>Selector`
+
+#### React Components
+
+Constructors that return a React component should be named with PascalCase. (e.g., `MyComponent`). In addition, the file they are located in should also be named with PascalCase (e.g., `MyComponent.tsx`).
+
+#### React features
+
+Do differentiate between react components and features, we use lowercase directory name. These directories often do not export a named constant that is identical to the directory name.
+
+```Typescript
+import { ManifestDetails as Component } from './ManifestDetails';
+
+export { Component };
+```
+
+which will automatically be lazy loaded by the React router, which helps with code splitting and keeps are bundle sizes small.
+
+## Project Structure
+
+See the [source roadmap](./source-roadmap.md) for a high level overview of the project structure.
+
+## State Management
+
+### Application State
+
+The project employs `Redux` and `Redux toolkit` as a global state management library. The store is the single source of truth for the client application and stores information relevant to all/most/many subcomponents in the application. For more information on redux, see the [redux documentation](https://redux.js.org/).
+
+### Component State
+
+The project uses the `useState` and `useReducer` React hooks to manage component state. For more information on hooks, see the [react documentation](https://reactjs.org/docs/hooks-intro.html). This type of state is local to a component and can be passed down to child components via props or context.
+
+### Form State
+
+The project embraces use of uncontrolled form inputs where possible. As such, the project uses the `react-hook-form` library to manage form state. For more information on `react-hook-form`, see the [react-hook-form documentation](https://react-hook-form.com/).
+
+Since the manifest is a relatively large and complex schema, we do need to use controlled components when necessary. For example, the hazardous waste generator's state, which is used in other parts of the manifest form to decide what state waste codes are available for selection. This state is controlled in the ManifestForm component and passed down to the child components that need it via props (e.g., the generator form and the waste line forms).
+
+The `react-hook-form` library facilitates the mechanism we use to add one-to-many relationships via the
+`useFieldArray` hook. This allows us to add/edit/delete multiple waste lines and transporters to a manifest.
+
+The forms are also integrated with a schema validation library, currently zod. This allows us to validate the form data before submitting it to the server. For more information on zod, see the [zod documentation](https://zod.dev).
+
+### URL state
+
+The project uses the `react-router` library to manage URL state. For more information on `react-router`, see the [react-router documentation](https://reactrouter.com/). Parameters are passed to components via the URL and are accessible via the `useParams` hook which allows users to share URLs with other users and bookmark URLs for later use.
+
+The complete URL tree can be viewed in the `routes.tsx` file in the root of the client directory.
+
+## Testing
+
+This project uses `vitest` as the test runner as it integrates its configs seamlessly with the `vite` build tool and exposes a `Jest` compatible API (which is generally a standard in the javascript ecosystem). For more information on `vitest`, see the [vitest documentation](https://vitest.dev/).
+
+### Tooling
+
+As previously mentioned the project uses `vitest`. In addition, for assertions, the project uses the `react-testing-library` library. For more information on `react-testing-library`, see the [react-testing-library documentation](https://testing-library.com/docs/react-testing-library/intro/).
+We also use `msw` to mock API requests to ensure that test can be run offline with predictable results. For more information on `msw`, see the [msw documentation](https://mswjs.io/).
+
+### Unit Tests
+
+Unit test represent the bulk of our tests. These test a single unit or component and ensure that it behaves as expected. Unit tests are located in the same directory as the component they are testing and are named with the `.spec.tsx` extension.
+
+### Integration Tests
+
+Integration test look similar to unit test, but they test multiple components simultaneously and ensure they interact as expected. Like unit tests, integration tests are located in the same directory as the component they are testing and are named with the `.spec.tsx` extension.
+
+With integration test, we primarily focus on testing behavior of components to ensure the user interface is behaving as expected. We do not test the implementation details of the components, such as the internal state of the component.

docs/haztrak_book/src/design/db-design.md → docs/guide/src/design/db-design.md

@@ -4,7 +4,18 @@
 
 ## Overview
 
-ToDo
+Haztrak depends on a relational database to persist its user data as well as
+information synced with (pulled from) RCRAInfo. RCRAInfo/e-Manifest should
+always be treated as the source of truth, however, the database provides users
+the means to, for example, draft or update electronic manifests without submitting
+the changes to RCRAInfo immediately.
+
+The database schema is maintained in version control via a series of 'migration'
+scripts. This enables us to initiate a new database and scaffold the expected
+schema quickly and consistently for local development, testing, and backup.
+
+The Haztrak project currently utilizes [PostgreSQL](https://www.postgresql.org/),
+a widely used open-source object-relational database system known for reliability and performance.
 
 ## Django ORM
 

docs/guide/src/design/sdd.md

@@ -0,0 +1,62 @@
+# Source Design Document
+
+This document's purpose is to outline Haztrak's system architecture and design. For more information on the project's specifications and requirements, see the [Software Requirements Specification](./srs.md).
+
+- [Architecture Overview](#architecture-overview)
+  - [Server](./http-server.md)
+  - [Database](./db-design.md)
+  - [Task Queue](./task-queue.md)
+  - [Task Scheduler](./task-queue.md#periodic-tasks)
+  - [Browser Client](./browser-client.md)
+  - [Admin Site](#admin-site)
+- [Testing](./testing.md)
+- [Versioning](#versioning)
+
+## Architecture Overview
+
+As a reference implementation, Haztrak follows a service oriented design however it would not be classified as a microservice architecture. The project is partitioned into a select number of containerized components that are deployed separately but closely work together, including:
+
+1. An [HTTP server](./http-server.md) that provides a RESTful API for the client and admin site.
+2. A [relational database](./db-design.md) for persisting user data and data synced with RCRAInfo.
+3. An in memory database (caching layer)
+4. A [task queue](./task-queue.md)
+5. A [task scheduler](./task-queue.md#periodic-tasks)
+6. A [user interface for the browser](./browser-client.md)
+
+## Admin Site
+
+The Admin site provides a quick, model-centric interface where trusted
+users can manage content. It's not intended to provide a process centric interface,
+admin user's should not be, for example, signing manifests through the admin site.
+
+The admin interface is an out-of-the-box feature of the [Django framework](https://docs.djangoproject.com/en/4.1/ref/contrib/admin/).
+It can be found by appending `/admin` to the URL of the host and port of HTTP server, for example `http://localhost:8000/admin`
+
+## In-memory Database
+
+The in-memory data store serves a couple purposes,
+
+- As a message broker for Haztrak's [task queue](./task-queue.md)
+- A cache for the [http server](./http-server.md)
+
+As a cache, the in-memory data store is utilized to increase performance by allowing Haztrak to cut down on latency for recently used resources including recent database queries, and computed values. As a message broker, the data store provides a reliable way for the back end service to communicate which each other (e.g., launch background tasks).
+
+The Haztrak project currently uses [Redis](https://redis.io/) as both the message broker and in-memory data store.
+
+## Versioning
+
+Haztrak uses [semantic versioning](https://semver.org/) to keep track
+of its software releases. Semantic versioning is a widely used versioning system that allows
+developers to convey the nature of the changes in the software using
+a version number.
+
+The Haztrak project stores versions are in
+[Git tags](https://git-scm.com/book/en/v2/Git-Basics-Tagging). When a new
+version of the software is released, a new Git tag is created to represent that version.
+these tags are then used for the container images that are built and
+released for that version. Since the Git tag and image tag correspond,
+the source for a given container tag can always be easily found. Containers built
+from non-release commits should use
+
+Haztrak is stored in a monorepo, the front-end and back-end
+containers are built and released simultaneously with the same version number.

docs/guide/src/design/source-roadmap.md

@@ -0,0 +1,52 @@
+# Source Roadmap
+
+We know that finding your way around a larger codebase can be intimidating, where do you start?
+To that end, this overview will hopefully get you started looking in the right directory.
+
+```
+├── /configs                 : Example configuration to be passsed as environment variables
+├── runhaz.sh                : shell script for aiding local development
+├── /client                  : Root for the React Browser SPA client
+│   ├── /public              : Entry point and static assets
+│   └── /src
+│       ├── /components      : React componets and building blocks
+│       ├── /features        : Higher level components
+│       ├── /hooks           : Custon hooks
+│       ├── /services        : Library for consuming web services
+│       └── /store           : Global store slices and logic
+└── /server                  : Root for the Django http server
+    ├── /apps                : Container for django 'apps'
+    │   ├── /core            : Django app with core features used by all apps, such as auth
+    │   ├── /site            : Django app encapsulating site and handler related functionality
+    │   └── /trak            : Django app encapsulating hazardous waste manifest functionality
+    │       ├── /migrations  : Database migration
+    │       ├── /models      : Table/Model definitions for database persistence
+    │       ├── /serializers : DRF serializers for model to/from JSON representation
+    │       ├── /services    : Business logic for our app
+    │       ├── /tasks       : Celery tasks, used to asynch interface with RCRAInfo
+    │       ├── /tests       : Our Django app specific tests
+    │       └── /views       : Our Django (DRF) views
+    ├── /fixtures            : Initial data loaded on start
+    └── /haztrak             : Django setting module
+```
+
+## Notable Directories
+
+[`server/apps`](https://github.com/USEPA/haztrak/tree/main/server/apps/trak)
+This directory houses all our Django apps, really just for organizational purposes.
+
+[`server/apps/trak`](https://github.com/USEPA/haztrak/tree/main/server/apps/trak)
+A Django reusable app that contains models related to hazardous waste tracking (electronic manifests)
+It depends on the `sites` app, the Handler model contains a foreign key to the RcraSite model (many-to-one relationship).
+
+[`server/apps/sites`](https://github.com/USEPA/haztrak/tree/main/server/apps/trak)
+A Django reusable app that contains models related to RCRAInfo sites.
+
+[`client/src/features`](https://github.com/USEPA/haztrak/tree/main/client/src/features)
+This directory, theoretically, contains the high level logic for
+rendering haztrak components, consumes the redux store slices. Generally, features map to routes the user can take. A feature component only relies on global state/context and does not accept any props.
+
+[`client/src/components`](https://github.com/USEPA/haztrak/tree/main/client/src/components)
+This directory (should) only contains basic components that are
+primarily act as building blocks. Some of these components are
+simple wrappers around [react-bootstrap](https://react-bootstrap.github.io/) components.