Short

Preview

Get s/ Chrome extension

Install it from Chrome Web Store or build it from source

Dependent Projects

• app: Reusable framework for Go apps & command line tools.
• kgs: Offline unique key generation service.

Table of Contents

1. Getting Started
   1. Accessing the source code
   2. Prerequisites
   3. Local environmental variables
   4. Create reCAPTCHA account
   5. Configure Single Sign On
   6. Backend
   7. Frontend
2. System Design
   1. App Level Architecture
   2. Service Level Architecture
   3. Object Oriented Design
   4. Dependency Injection
   5. Database Modeling
   6. Feature Toggle
   7. Search Engine Optimization
   8. Social Media Summary Card
3. Testing
   1. The Importance Of Automation
   2. Testing Strategy
   3. Unit Testing
   4. Integration Testing
   5. Component Testing
   6. Contract Testing
   7. End To End Testing
   8. The Test Pyramid
4. Deployment
   1. Continuous Delivery
   2. Kubernetes
   3. GitOps
5. Tools We Use
6. Contributing
7. Author
8. License

Getting Started

Accessing the source code

git clone https://github.com/short-d/short.git

Prerequisites

• Go v1.13.1
• Node.js v12.12.0
• Yarn v1.19.1
• PostgreSQL v12.0

Local environmental variables

1. Copy backend/.env.dist file to backend/.env:

   cp backend/.env.dist backend/.env
   

2. Copy frontend/.env.development.dist file to frontend/.env.development:

   cp frontend/.env.development.dist frontend/.env.development
   

Create reCAPTCHA account

1. Sign up at ReCAPTCHA with the following configurations:

   | Field | Value | |-----------------|----------------| | Label | Short | | reCAPTCHA type | reCAPTCHAv3 | | Domains | localhost |

2. Open settings. Copy SITE KEY and SECRET KEY.

3. Replace the value of RECAPTCHA_SECRET in the backend/.env file with SECRET KEY.

4. Replace the value of REACT_APP_RECAPTCHA_SITE_KEY in frontend/.env.development file with SITE KEY.

Configure Single Sign On

Google

Create a new Client ID at Google API Credentials:

1. Click on Create Credentials and select OAuth client ID.

2. Select Web application for Application type.

3. Fill in http://localhost/oauth/google/sign-in/callback for Authorized redirect URIs and click on Create.

4. Replace the value of GOOGLE_CLIENT_ID in backend/.env file with Your Client ID.

5. Replace the value of GOOGLE_CLIENT_SECRET in backend/.env file with Your Client Secret.

Facebook

You can find the detailed instructions on setting up Facebook sign in here in case you are interested in.

Github

You can find the detailed instructions on setting up Github sign in here in case you are interested in.

Backend

1. Update placeholder values with your own configurations.

2. Launch backend server

   cd backend
   ./scripts/dev
   

3. Remember to install developers tools before start coding:

   ./scripts/tools
   

Frontend

1. Update REACT_APP_RECAPTCHA_SITE_KEY in frontend/.env.development.

2. Launch frontend server

   cd frontend
   ./scripts/dev
   

3. Visit http://localhost:3000

System Design

App Level Architecture

Short backend is built on top of Uncle Bob's Clean Architecture, the central objective of which is separation of concerns.

It enables the developers to modify a single component of the system at a time while leaving the rest unchanged. This minimizes the amount of changes have to be made in order to support new requirements as the system grows. Clean Architecture also improves the testability of system, which in turn saves precious time when creating automated tests.

Service Level Architecture

Short adopts Microservices Architecture to organize dependent services around business capabilities and to enable independent deployment of each service.

SSR, Toggle, Status Page, Search, Data Reporter, Feedback Widget, and Cloud API are still under active development.

Object Oriented Design

Short leverages class design, package cohesion, and package coupling principles to manage logical dependency between internal components.

Class Design

| Principal | Description | |------------------------------------------------------------------|------------------------------------------------------------------------| | Single Responsibility Principle | A class should have one, and only one, reason to change. | | Open Closed Principle | You should be able to extend a classes behavior, without modifying it. | | Liskov Substitution Principle | Derived classes must be substitutable for their base classes. | | Interface Segregation Principle | Make fine grained interfaces that are client specific. | | Dependency Inversion Principle | Depend on abstractions, not on concretions. |

Package Cohesion

| Principal | Description | |----------------------------------------------------------------------|-------------------------------------------------------| | Release Reuse Equivalency Principle | The granule of reuse is the granule of release. | | The Common Closure Principle | Classes that change together are packaged together. | | The Common Reuse Principle | Classes that are used together are packaged together. |

Package Coupling

| Principal | Description | |-----------------------------------------------------------------|-------------------------------------------------------| | Acyclic Dependencies Principle | The dependency graph of packages must have no cycles. | | Stable Dependencies Principle | Depend in the direction of stability. | | Stable Abstractions Principle | Abstractness increases with stability. |

Dependency Injection

Short produces flexible and loosely coupled code, by explicitly providing components with all of the dependencies they need.

type Authenticator struct {
  tokenizer          fw.CryptoTokenizer
  timer              fw.Timer
  tokenValidDuration time.Duration
}

func NewAuthenticator(
  tokenizer fw.CryptoTokenizer,
  timer fw.Timer,
  tokenValidDuration time.Duration,
) Authenticator {
  return Authenticator{
    tokenizer:          tokenizer,
    timer:              timer,
    tokenValidDuration: tokenValidDuration,
  }
}

Short also simplifies the management of the big block of order-dependent initialization code with Wire, a compile time dependency injection framework by Google.

func InjectGraphQlService(
  name string,
  sqlDB *sql.DB,
  gra