Readmes update

README.md

@@ -1 +1,73 @@
-# todo-toy-project
+# Todo-toy-project
+
+A simple todo toy application for todo duties management that can add/edit/complete the duties.
+
+## How to run
+
+### Prerequisites
+
+`Docker` and `Docker Compose` are required. Recommend the newest version of Docker and Docker Compose.
+
+The exact minimum versions that can run this project has not been tested. However, they must be at least the versions that support `include` syntax in `docker-compose.yml` is required. See [Docker Docs on include](https://docs.docker.com/compose/multiple-compose-files/include/).
+
+### Steps
+
+1. Build the docker images needed and run the containers with the below command.
+
+```bash
+make build-and-run
+```
+
+2. Open the browser and go to http://localhost. Done!
+
+## Engineering Practices
+
+### Continuous Integration
+
+This project has setup github workflows for CI. Formatting / linting / unit tests for both frontend and backend, integration tests for backend, and end to end tests for the entire application.
+
+See `.github/workflows` directory for more details.
+
+### Small Pull Request and Focused Commits
+
+This project has a convention that each pull request should be manageable in size and each commit should be focused on the change as described in the commit message.
+
+No direct pushes to main branch and all changes should be made via pull request.
+
+## Local Development
+
+### Prerequisites
+
+- Node v20
+
+### Setup
+
+Install the node dependencies needed with the below command.
+
+```bash
+make local-install
+```
+
+### Architecture
+
+- `backend/` directory is for backend code.\
+  See [README of backend](./backend/README.md) for more details.
+- `frontend/` directory is for frontend code.\
+  See [README of frontend](./frontend/README.md) for more details.
+- `e2e/` directory contains end-to-end test code using `Cypress`.\
+  See [below command](#make-e2e-dev) for shortcut to run `cypress` in this project. Also can refer to the official document of `cypress` for further details.
+
+### Useful Commands
+
+Noted that term of `development mode` below means that the application will be reloaded automatically when the code is changed.
+
+#### `make backend-dev`
+
+Run the backend server in development mode.
+
+#### `make e2e-dev`
+
+Run both frontend and `cypress` in development mode. Also have to run `make backend-dev` in another terminal.
+
+See [makefile](./makefile) for more details.\
+[README of backend](./backend/README.md) and [README of frontend](./frontend/README.md) for more specific commands of both frontend and backend during development.

backend/README.md

@@ -1 +1,51 @@
-# backend
+# Backend
+
+## Technical Stack
+
+TypeScript, Node.js, Express.js, PostgreSQL
+
+## Features
+
+- CRUD APIs for duties. Also an api for delete all duties that is useful for e2e testings.
+- Validation for duties input.
+  - Name of duties can't be empty and too long.
+- Automatically trim input values for duties to remove unnecessary whitespace.
+
+### Utilities for Error Handling
+
+1. By default, `express` can't handle errors thrown from async request handler. So defined [RouteService](./src/route/route.ts) to handle it.
+2. Defined [RouteErrorHandler](./src/route/util.ts) to handle error and return the desired response to client.
+
+## Testing strategy
+
+Have unit tests that don't involve external dependencies and integration tests that involve PostgreSQL. See [below section](#useful-commands) for how to run them.
+
+### Explanation for `createNull` convention
+
+In this project, some classes have creation methods like `Xyz.create` and `Xyz.createNull` respectively. It is a pattern learnt from [Testing Without Mocks: A Pattern Language](https://www.jamesshore.com/v2/projects/nullables/testing-without-mocks) by James Shore.
+
+`Xyz.create` is the creation method for production code. `Xyz.createNull` is the creation method for test code that support parameterless instantiation and provided some fake implementation for some external dependencies to enhance testability and maintainability of test cases.
+
+## Local Development
+
+See [this section in root README](../README.md#setup) for how to setup.
+
+### Useful Commands
+
+#### `make dev-with-db`
+
+This command starts the backend server in development mode along with a local PostgreSQL database running inside a Docker container.
+
+#### `make run-db-and-integration-test`
+
+Run integration tests involving PostgreSQL after initiating a local database in a Docker container.
+
+#### `make clean-db`
+
+Fully reset and clean the local PostgreSQL Docker image. Noted that some setting of image can't be reset if simply using `docker compose down` but this command can.
+
+#### `yarn test:watch`
+
+Run unit tests in watch mode. Noted that this excludes integration tests.
+
+See [package.json](./package.json) for more details and different commands.

frontend/README.md

@@ -1,46 +1,47 @@
-# Getting Started with Create React App
+# Frontend
 
 This project was bootstrapped with [Create React App](https://github.com/facebook/create-react-app).
 
-## Available Scripts
+## Technical Stack
 
-In the project directory, you can run:
+TypeScript, React, Ant Design
 
-### `yarn dev`
+## Features
 
-Runs the app in the development mode.\
-Open [http://localhost:3000](http://localhost:3000) to view it in the browser.
+- Add / edit / complete(delete) duties.
+- Input validation for duty entries.
+- Error handling for failed API calls when adding, editing, or completing duties.
 
-The page will reload if you make edits.\
-You will also see any lint errors in the console.
+### Screenshot Description
 
-### `yarn test`
+![screenshot](./screenshot.png?raw=true 'screenshot')
 
-Launches the test runner in the interactive watch mode.\
-See the section about [running tests](https://facebook.github.io/create-react-app/docs/running-tests) for more information.
+Add new duty by clicking the Add button.
 
-### `yarn build`
+Edit existing duty by clicking the edit icon button. During editing, the edit icon will change to save icon that can be clicked to save the edit.
 
-Builds the app for production to the `build` folder.\
-It correctly bundles React in production mode and optimizes the build for the best performance.
+Complete(delete) existing duty by clicking the tick icon button.
 
-The build is minified and the filenames include the hashes.\
-Your app is ready to be deployed!
+## Local Development
 
-See the section about [deployment](https://facebook.github.io/create-react-app/docs/deployment) for more information.
+See [this section in root README](../README.md#setup) for how to setup.
 
-### `yarn eject`
+### Useful Commands
 
-**Note: this is a one-way operation. Once you `eject`, you can’t go back!**
+#### `yarn dev`
 
-If you aren’t satisfied with the build tool and configuration choices, you can `eject` at any time. This command will remove the single build dependency from your project.
+Runs the app in the development mode.
 
-Instead, it will copy all the configuration files and the transitive dependencies (webpack, Babel, ESLint, etc) right into your project so you have full control over them. All of the commands except `eject` will still work, but they will point to the copied scripts so you can tweak them. At this point you’re on your own.
+The page will reload if you make edits.\
+You will also see any lint errors in the console.
 
-You don’t have to ever use `eject`. The curated feature set is suitable for small and middle deployments, and you shouldn’t feel obligated to use this feature. However we understand that this tool wouldn’t be useful if you couldn’t customize it when you are ready for it.
+#### `yarn test:watch`
+
+Launches the test runner in the interactive watch mode.\
+See the section about [running tests](https://facebook.github.io/create-react-app/docs/running-tests) for more information.
+
+See [package.json](./package.json) for more details and different commands.
 
 ## Learn More
 
 You can learn more in the [Create React App documentation](https://facebook.github.io/create-react-app/docs/getting-started).
-
-To learn React, check out the [React documentation](https://reactjs.org/).