How to write technical specification

Description#

A quick description of the service, what it used for, a list of user stories that will be needed based on game design document

DLC management allows game admin to freely manage the additional assets (DLC) and allows game client to get the download links.

Requirements#

How:

Read through the GDD and try to determine the following information:

• Entity, attributes, actions and relationships. There’s are 2 types of attributes: game-managed attributes and backend-managed attributes. Attributes should be marked in 2 different colors.
• Business constraints: Data constraint and action constraint.

Rules of thumb:

• Domain entity diagram must have at least 2 entities (no such domain has only 1 entity).
• Domain entity diagram cannot contain a completely independent entity.
• Domain entity diagram must specify the quantity relationship (eg: Each Game User can register only one SFC Account)
• There are at least 1 data constraint if the domain entity contains backend-managed data.
• Do not include unrelated data (database field, etc) to the domain entity.

Data constraints:

• Email of each SFC Account MUST BE unique
• Phone number of each SFC Account MUST BE unique

Action constraints:

• If user does not enter OTP sent to his/her phone, he/she cannot use the created account to login the game.

User stories & Use cases#

For each feature, we need to provide list of use stories

Then, draw 2 usecase diagrams, 1 for CMS and the other for Game.

Rules of thumb:

• Each action in the business document should be a usecase. Determine primary usecase, included usecase and extended usecase.
• There are 2 types of actors:
  • Left side: Internal services
  • Right side: External services.
• Usecase which involved by internal services should be in green.
• Usecase which involved by external services should be in yellow.
• Green usecase and yellow usecase must always be INCLUDED or EXTENDED.
• A reference to extended usecase must include the condition which triggers the usecase.
• If a usecase is a command (create / update / delete something), it must always involve 1 and only 1 instance of one entity. Below are examples of an invalid usecase:
  • Register user and create profile (this involves 1 instance of User and 1 instance of Profile)
  • Delete multiple users (this involves multiple instances of User)

What should be discussed during Usecase review?

• Validate usecases and actors (using above rules)
• How intensive each usecase is executed (This should be answered by the assignee since he/she is the one who is in touch with GDD) (Intensive usecases are expected to be executed in high frequency)
• Determine if intensive usecase depends on multiple internal or external services. If that’s the case, we should reconsider the service’s boundary or redesign that usecase.
• Determine the priority of of each usecase (useful for planning iteration)

The assignee should be able to answer the following questions:

• In what context is this usecase applied ?
• How frequent will the usecase be executed ? (Give an estimation based on GDD)

Game Client Use Case#

BE Service Use Case#

CMS Use Case#

Database details#

• Object Storage: S3
  • File Name:
    • defaults: {fileName}: {dlcCode}-{version}.{extension}
    • internal: {internalFileName}: {itemCode}.{extension}
  • Folder structure:
    • Bucket:
      • {project}-{env}-private-assets (pri)
      • {project}-{env}-public-assets (pub)
    • Key:
      • pri: /private/{group}/{code}/{fileName}
      • pub:

API details#

Diagrams#

Each use case / user story can have its own diagram or grouped in one diagram

Sequence diagram#

Data flow#

7. Relevant services#

Does this service require any other service / internal call?

DLC is used for game setting, single page application, time-limited event and any other service that require to upload file to store in the backend

8. Test plan#

You need to outline all the test cases, unit test, performance test, integration test and their results

• Test cases → Dev, QC
• Unit tests and results → Dev
• Performance tests and results → QC
• Integration tests and results → QC

Scalability#

You need to answer these questions and outline here:

• Will the database size and data response size increase with more users and/or longer they play?
• What is the estimation of total data size for these cases: 100,000 users, 1,000,000 users and10,000,000 users?
  • What can go wrong (in term of logic, flow, behavior,...) when the data in production is too big like those case?
  • What are our back up / failover plan? (logs, metrics, alarms, scalability logic)
• How do we plan to support more users while reducing the cost? (achieve old data, clean up database,...)
• If this is an additional feature on the already-live game, do we consider how it will process the big data of production database?
  • What would be your simulation and estimation? (how long the CRON would run, we have limitations or anything similar in case it can't process all data?)
  • Do we run test with production-size database in Preproduction already?

Security measures#

You need to answer these questions and outline here:

• Do we require access-token, authentication for all the APIs or some APIs?
• What are hash algorithm (SHA-256,...) that we're using?
• How do we plan to avoid SQL injection and protect this feature / APIs?

Global variables and Secrets#

Provide the list of all global variables, API key of 3rd party provider, secrets for DevOps to setup in the pipeline

• ENV variables:
  • Allowed file extensions:
    • '.zip,.html,.css,.js,.png,.jpg,.jpeg,.gif,.txt,.xlsx,.json,.csv,.ttf,.hash,.bundle'
  • Host URL
  • Uploaded file size limit: 50MB
  • Object storage credentials (secret envs)