# Project Documentation and Requirements Analysis - Template
> This document may be used to create the Design Doc.
> See too [Developer Workflow document](https://hackmd.io/3KtlpfTHTwiRQWv3pXn9_Q).

## 1 Project information

#### 1.1 Project Name: `__name__`
#### 1.2 Description: `__description__`
#### 1.3 Author: `__author__`
#### 1.4 Date: `mm/dd/aaaa`
#### 1.5 Document version: `0.0.0`
#### 1.6 Target audience: `__anyone__`

## 2 Problem Statement
> Describe what you are trying to solve.
> A good structure first presents a contextualization and introduction to the topic, next shows the problem that will be solved justifying its relevance. And then talk about this solution evidencing differences from other solutions and the innovative points.

### 2.1 Objectives
> Project objectives.

### 2.2 Sensational description

## 3 Stakeholders
|Role |Person|
| ---------------------- | ---- |
|Product Owner | - |
|Scrum Master | - |
|Dev Owner | - |
|Other Dev 1 (Front-end) | Me |
|Other Dev 2 (Back-end) | Me |
|Docs | Me |
|QA (Quality Assurance) | Me |
|UX (User eXperience) | Me |

## 4 Requirements

### 4.1 Functional Requirements
> how it will work.
> Identifier: FR00x
> Include user functions
> Classified as [essential, important, desirable]

> Words used in requirements from [RFC2119](https://www.ietf.org/rfc/rfc2119.txt)
> MUST is equivalent to REQUIRED and SHALL indicating that the definition is an absolute requirement.
> MUST NOT is equivalent to SHALL NOT and indicates that it is an absolute prohibition of the specs.
> SHOULD is equivalent to RECOMMENDED means that there are valid reasons to ignore a particular requirement, but the implications need to be weighed.
> SHOULD NOT and NOT RECOMMENDED means that a particular behavior may be acceptable or useful, but again, the implications need to be weighed.
> MAY means OPTIONAL and that the requirement is truly optional. Interoperability with different systems that may or may not implement an optional requirement must be done.

**FR001**: The system must be SEO friendly.

**FR002**: The front-end must totally loaded in <500 ms.

**FR003**: The front-end must partially loaded and usable in <500 ms.

**FR004**: Each page title and meta description must be unique and relevant to the page they represent.

### 4.2 Non-Functional Requirements
> Identifier: NFR00x
> See [ISO/IEC 25010](https://iso25000.com/index.php/en/iso-25000-standards/iso-25010)
> See [Software Quality Attributes, Non-Functional Requirements and Better Software Architecture](https://medium.com/@andreigridnev/non-functional-requirements-quality-attributes-and-better-software-architecture-855425310e60)

> Non-Functional Aspect (NFA): security, reliability, performance, maintainability, scalability, and usability.
> **Functional** suitability: functional completeness, functional correctness, functional appropriateness;
> **Performance efficiency**: time behaviour, resource utilisation, capacity;
> **Reliability**: maturity, availability, fault tolerance, recoverability;
> **Usability**: appropriateness, recognisability, learnability, operability, user error protection, user interface aesthetics, accessibility;
> **Security**: confidentiality, integrity, non-repudiation, accountability, authenticity;
> **Compatibility**: co-existence, interoperability;
> **Maintainability**: modularity, reusability, analysability, modifiability, testability;
> **Portability**: adaptability, installability, replaceability.

### 4.2.1 Compatibility

#### 4.2.1.1 Interoperability
**NFR001**: API must to use a pattern, like RESTfull with JSON.

---

### 4.2.2 Maintainability

#### 4.2.2.1 Adaptability / Portability
> Platforms that will run.
**NFR002**: System should be tune to key devices (desktops and smartphones)

**NFR003**: System must run for browsers with Responsive Web Design, using these rules in browserlist:
`last 1 version`
`> 1%`
`maintained node versions`
`not dead`
Platforms including:
- Desktop and Notebooks
- Mobile (PWA - Progressive Web App)

#### 4.2.2.2 Analysability
**NFR004**: Collect access information (web analytics) with Google Analytics.
- react-ga

**NFR005**: System must be maintaining full traceability of DB transactions.

#### 4.2.2.3 Modularity

**NFR006**: React components must be modularized with JavaScript code, CSS, unit test in one directory for each.

#### 4.2.2.4 Reusability

**NFR007**: React components should be created for reuse.

**NFR008**: No Linter errors
- Verify and fix all Linter errors.

#### 4.2.2.5 Testability
**NFR009**: It has at least 98% unit test coverage for backend and frontend code.

---

### 4.2.3 Performance Efficiency

#### 4.2.3.1 Capacity

> Throughput – how many transactions at peak time does the system need to be able to handle?
> Storage – (memory/disk) – volume of data the system will page/persist in running time to disk
> Year-on-year growth requirements (users, processing & storage)

#### 4.2.3.2 Time Behaviour

**NFR010**: Score scale more than 75 (green status) in all metrics from Chrome Audits (Performance, Progressive Web App, Accessibility, Best Practices and SEO)
- Critical Rendering Path
- Code Splitting with Webpack or react-loadable

**NFR011**: Site Speed Requirements
- Server response time <500ms.
- Server supports browser caching and file compression, like gzip.
- Supports minification of JS and CSS
- webpack
- Tree shaking/dead code elimination from webpack

**NFR012**: SEO (Search Engine Optimization) friendly
- React Router for URL optimization.
- React Helmet for meta tags optimization.
- Analyze the system with Fetch As Google
- Prerendering with ReactSnap
- Sitemap
- Robots.txt
- Breadcrumb Navigation
- Customisable Canonical Tags & Pagination Tags
- A descriptive URL provides both humans and search engines with an indication of what a page will be about.

**NFR013**: Editable Image Titles and Alt Text

**NFR014**: Ability to Implement Structured Data
- Schema markup
- Facebook OpenGraph

**NFR015**: Page speed - Google Mobile-Friendly

~~**NFR000**: APM (Accelerated Mobile Pages)~~
~~- Ampreact~~
~~- Next.js~~

---

### 4.2.4 Reliability
#### 4.2.4.1 Availability
**NFR016**: System must be available in 99% of the time.
#### 4.2.4.2 Fault tolerance

#### 4.2.4.3 Recoverability
> Backup frequencies – how often is the transaction data, config data, code backed-up?

---

### 4.2.5 Security

#### 4.2.5.1 Authenticity

**NFR017**: Use HTTPS (HTTP over SSL)

> Password requirements – length, special characters, expiry, recycling policies, 2FA
> Inactivity timeouts – durations, actions, traceability

#### 4.2.5.2 Confidentiality
**NFR018**: API data are accessible only to those authorized to have access.

#### 4.2.5.3 Integrity
**NFR019**: API data must prevents unauthorized access to, or modification of the database data.

---

### 4.2.6 Usability

#### 4.2.6.1 Accessibility
> Degree to which a product or system can be used by people with the widest range of characteristics and capabilities to achieve a specified goal in a specified context of use.
> Internationalization/localization requirements – languages, spellings, keyboards, etc.

#### 4.2.6.2 Learnability.
> Degree to which a product or system can be used by specified users to achieve specified goals of learning to use the product or system with effectiveness, efficiency, freedom from risk and satisfaction in a specified context of use.
#### 4.2.6.3 Operability
> Degree to which a product or system has attributes that make it easy to operate and control.
#### 4.2.6.4 User error protection
> Degree to which a system protects users against making errors.

**NFR020**: System must have custom 404 page functionality.
#### 4.2.6.5 User interface aesthetics
> Degree to which a user interface enables pleasing and satisfying interaction for the user.

---

### 4.3 Others Non-Functional Requirements

### 4.3.1 Documentation
> User Documentation
> System Documentation (Production Acceptance?)
> Help?
> Training Material

### 4.3.2 Interface Requirements
- User interface:
> Graphic language used
- Hardware interface:
> Any specific hardware?
- Communication interface:
> How will communication, what protocols
### 4.3.3 Technical Requirements (Implementation Requirements and Pattern Requirements)
- **Project Management**
- **Agile Methodology**: Scrum/Kanban
- **Software**: Trello
- **Boards**: One board to the project
- **Lists**: Six lists, each one with some cards:
- **Product Backlog**: tasks that are ready to be developed
- **To do this week**: tasks to be done this week
- **Paused**: paused tasks
- **Doing**: tasks in progress
- **Ready for Test**: developed tasks awaiting testing
- **Done**: completed tasks
- **Labels and Tags**
- **New feature**: label named as `new` and color `blue`
- **Upgrade feature**: label named as `upgrade` and color `green`
- **Bug fix**: label named as `bug` and color `red`
- **Product design**
- **Software to design/prototyping**:
> Wireframing, Prototyping and/or Mockuping
> Wireframe represents a product's structure, therefore without being clickable.
> Mockup represents a mid or high-fidelity display of design, but it's not clickable.
> Prototype represents a design often high fidelity which simulates user interaction.
> mockflow.com, idoc.mockplus.com, webflow.com, marvelapp.com, www.figma.com, evrybo.com, pandasuite.com, vectr.com
> pencil, scratch, alva
> wireframes: wireframe.cc
> jdittrich.github.io/quickMockup/, fatiherikli.github.io/mockup-designer, https://wiredjs.github.io/designer/

- **Screens Name/Description**
- Login
- Home
- etc.
- **Design Pattern / UI Style Guide**:
> Self-made, Material Design, Air BNB, Atlassian, Polaris, IBM, other
- **Colours**
- **Primary**:
- **Secondary**:
- **Others**:
- **Main Font**:
- **Database**
- **SGBD**:
- **Database modeling**:
> DBDiagram.io, MySQL Workbench, pgModeler, DBDesigner, SQLdbm, Vertabelo or other
- **API**
- **Type**: RESTfull
- **Language**: Ruby
- **Documentation**:
- Postman for API design
- Swagger (rswag) with RSpec in Rails to API documentation
- **Test**: Postman
- **Back-end**
- **Main language**: Ruby
- **Main frameworks/library**: Rails
- **Paradigm**: Object-Oriented and Functional programming
- **Package Manager**: NPM
- **Test (TDD)**: RSpec
- **Documentation**:
- RDoc for Rails documentation
- Rails-ERD for generating Entity-Relationship Diagrams based on application's Active Record models
- **Automatic Deployment**:
- **Style Guide**
- Ruby: [Airbnb Ruby Style Guide](https://github.com/Airbnb/ruby)
- **Static Code Analyzer (Linter)**: RuboCop
> Analyze static code to verify stylistic error to ensure code quality.`
- **Formatter**: Editor Config and RuboCop
- **Code Quality Analyzer**: SonarQube for Ruby
- **Benchmark**: Benchmark.ms
- **Continuous Integration**:
> Codeship, Circle CI, Travis CI
- **Online Code Quality Analyzer**: Code Climate
- **Front-end**
- **Main language**: JavaScript
- **Main library/framework**: React
- **Paradigm**: Functional and Reactive programming
- **Main visual technology**: CSS3 with styled-components
- **Package Manager**: Yarn
- **Test (TDD)**: Jest
- **Visual Test/Documentation**: React Styleguidist with React-docgen-typescript and snapguidist
- **Automatic Deployment**:
- **Style Guide**
- JavaScript: [Airbnb JavaScript Style Guide](https://github.com/Airbnb/JavaScript)
- React: [Airbnb React Style Guide](https://github.com/Airbnb/JavaScript/tree/master/react)
- CSS:
- [Airbnb CSS Style Guide](https://github.com/Airbnb/css)
- [Airbnb CSS in JavaScript Style Guide](https://github.com/Airbnb/JavaScript/tree/master/css-in-JavaScript)
- **Static Code Analyzer (Linter)**:
> Analyze static code to verify stylistic error to ensure code quality.`
- TSLint
- CSSLint
- **Formatter**: Editor Config and Prettier
- Editor Config configs:
- Prettier configs:
- **Code Quality Analyzer**: SonarJS
- **Continuous Integration**:
> Codeship, Circle CI, Travis CI
- **Online Code Quality Analyzer**: Code Climate
- Project file and directory structure:
- Container directory
- Container name in CamelCase
- each container with four files:
- index.ts: export the container for app
- Container.tsx: container in React
- Container.style.ts or component.style.scss: styles for container
- Container.test.tsx: test file
- Components directory
- Component name in CamelCase
- each component with four files:
- index.ts: export the component for app
- Component.tsx: component in React
- Component.style.ts or component.style.scss: styles for component
- Component.test.tsx: test file
- Structure:
<pre>
src/
├── assets
│ ├── files
│ └── images
│ └── icons
├── components
│ ├── Nav
│ │ ├── index.ts
│ │ ├── Nav.style.ts
│ │ ├── Nav.test.tsx
│ │ └── Nav.tsx
│ └── themes
├── containers
│ ├── App
│ │ ├── index.ts
│ │ ├── App.style.ts
│ │ ├── App.test.tsx
│ │ └── App.tsx
│ └── Footer
└── styles
public/
node_modules/
.editorconfig
.git
.gitignore
humans.txt
package.json
.prettierrc.json
README.md
robots.txt
tsconfig.json
.vscode
yarn-error.log
yarn.lock
</pre>
- **CVS**
- **System**: Git
- **Repository**: Github.com
- **Commit Patterns**
- **Add a functionality**: `add: message`
- **Fix a functionality**:`fix: message`
- **Update/upgrade a functionality**: `update: message`
- **Change functionality**: `change: message`
- **Remove a functionality**: `rm: message`
- **Branches**
- **Master**: for production.
- **Developer**: for development.
- **Commit Message language**: All commit messages must be writing in English (US).
- **Rules**: Developers should create a branch for each task, submit a pull request to the developer branch, and then Dev Owner will analyse and execute the merge on the developer branch. If to be small team, can commit directly to the developer branch, but it is not a good practice.
### 4.3.4 Versioning
> Semantic Versioning or other
> SemVer: x.y.z
> x: MAJOR version when you make incompatible API changes,
> y: MINOR version when you add functionality in a backwards-compatible manner, and
> z: PATCH version when you make backwards-compatible bug fixes.
### 4.3.5 License Requirements
> Under what license are you?
> see: https://choosealicense.com/licenses/
> see: https://www.quora.com/What-are-different-types-of-software-licenses

Apache 2.0 license.
Key points:
- Keep the copyright notice.
- Your software has to contain a copy of the Apache 2.0 license.
- You are free to use, modify, distribute, and redistribute the software.
- If you modify the code, you have to mention your modifications particularly.
- If there is a text file called NOTICE, take time and read it. It contains further information about the specific parts of the license and the purpose of the software.
- The NOTICE file has to be included in your software release too.

## 5 Sprints/Deliveries
> Define deliveries that must contain functions defined in the functional requirements. Each delivery must be functional and be numbered sequentially.
> As a good practice, a first delivery should be a Minimum Viable Product (MVP), with business objectives, feasibility (including technical, financial, etc.) and the needs for the customer. The following deliveries should represent significant improvements for the customer.
### Delivery 1
**Sprint goal**
> Goal Description in one or two lines.

**Features**
> Features list that will be delivered
### Delivery 2
**Sprint goal**
> Goal Description in one or two lines.

**Features**
> Features list that will be delivered