docs: README

README.md

@@ -1,49 +1,59 @@
 # creators-app
 
-creators-app is a Next.js React SPA for Brave creators.  It uses tailwind and `brave-leo` for styling, storybook for component documentation, and jest for component testing.
+## Getting started
 
-## project structure
+Installation and running locally
 
-### components/
-#### AppElements/
+```
+npm install
+npm run dev
+```
 
-AppElements is a contextually specific subset of components where each subdirectory represents a page.
+Scanning with typescript
 
-The important distinction between AppElements and pages (which is a next.js framework default) is that AppElements are defined irrespective of paths and the directory is aggressively flat, i.e. an AppElement should never be defined more than one subdirectory away
-from AppElements
+```
+npm install -g typescript
+tsc --watch 
+```
 
-Yes:
-    AppElements/
-    - Page1
-    - Page2
+Running Tests
 
-No:
-    AppElements/
-    -Page1/
-        - Page2/
+```
+npm run test
+```
 
-Emphatically No:
-    AppElements/
-    - Page1/
-        -Page2/
-            -Page3/
+## Application Architecture
+- This app is built using Next.js and tailwind-css using [brave/leo](https://github.com/brave/leo) 
+- TypeScript is used for type-checking and improving developer experience.
+- JSON Schema is used to define the structure of the data used in the app, and is used to generate TypeScript interfaces for all components and unit testing fixtures.
 
-The rationale here is that we define independent stateless functional components that can be re-used in any number of contexts irrespective of paths, and we abstract state implementations to `pages/` so that each `AppElement` can be independently unit tested.
+## Important Dependencies
+- `next`: The core Next.js framework
+- [brave/leo](https://github.com/brave/leo): Design/styling framework that implements tokens derived from the Brave design system that are importable as tailwind utility classes/and or svelte/react components.
+- `json-schema-to-typescript`: A library for generating TypeScript interfaces from JSON Schema.  It is not explicitly required as a dependency for the app but is used as part as a stand alone data generation process.
 
-A good example of this is a `Profile` page.  It may be used in multiple contexts, such of that as an individual authenticated user who is viewing their own profile, or potentially in the context of an administrator who has permissions to view many profiles.
+## JSON Schema
+- JSON Schema is used to define the structure of the data used in the app.
+- It is used to generate TypeScript interfaces for all components and unit testing fixtures, ensuring that the data used in the app is always correctly typed.
+- Schemas are located in the `src/public/schemas` directory and are dynamically generated using `json-schema-to-typescript`
+- Though not implemented, JsonSchema was also chosen because it can be used to validate runtime HTTP request data as well as form-data interactions from client to server.
 
-In this (very common) use case, the maintenance burden of keeping an Admin/User context `Profile` component is simplified because it is simply the same component being re-used in different contexts (i.e. paths).  The component may have different behaviors depending on the permissions of the user who is viewing it, and those can be manually tested independent of application state.
+Taken as a whole, if the patterns setup using JsonSchema and their associated Types are followed and extended, developers should find that many of the common issues associated with React app development are absent as they will have strict type assurances accross a broad spectrum of application uses.
 
-#### FormElements/
-#### PageElements
-#### BrandElements/
+## State Management
+- State is intended to be implemented in the Next.js `pages` directory.
+- Components defined in the `components` directory should be defined as pure, stateless components as much as possible to improve reusability, performance, and to simplify unit testing..
+- The final production state management mechanism for the application is currently TBD.  Right now a simple context provider is available but a more robust state management system may be desirable as the CRUD elements of the application are extended.
 
-### pages/
+## Unit Testing
+- Unit tests are located in the `__tests__` directory.
+- JSON Schema-generated TypeScript interfaces are used as the inputs for unit tests, ensuring that the data used in tests is always correctly typed.
+- Jest is used as the testing framework.## context
 
-Next.js pages/ represent the stateful implementation of AppElement components and can be arbitrarily nested depending on the needs of the application.
+## Directory Structure
 
-### layouts/
-
-### models/
-
-### context
+- The project is organized to keep things as flat as possible and to avoid excessive nesting.
+- The primary component directory is divided into directories by context:
+  - AppElements contains all components that are used to create stateless "page" components, as well as their individual components.
+  - PageElements contains core building blocks of building pages, such as cards and other generic component classes.
+  - FormElements contains the building blocks for creating forms, such as text fields and other dropdown components.