How to write technical specification

March 30, 2025

Because after a long period of time, we may not be able to remember what and why we decide for that design.

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.

A visual depiction of what is being written about

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:

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:

/{group}/{code}/{version}/{internalFileName}

/{group}/{code}/{internalFileName}

#	Database	Collections	Description
1	dlc	dlc_item	• id: uuid • code: string • version: number • size_in_bytes: number • download_url: string • expiration_date: nu

API details

internal/v1/items

Upload Item

POST

BODY: file: binary string group: string code: string version?: number isPublic: boolean

CODE: 200 BODY:{ "url": "string", "pathName": "string"}

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

TEST GROUP/NAME	REQUIREMENT	RELATED DIAGRAM/FLOW/API/CODE FUNCTION	TEST SAMPLE	EXPECTED RESULT	RESULT
E2E
healthcheck-01	The API healthcheck must return the version as text	GET /dlc/healthcheck	N/A	Response body is the content of file ./version	Success on Attached file / screenshots
Unit Test
game-download-asset	Downloads item with a valid access token and gets the latest version	ItemApiController.downloadItems	• Input: {"code": "utest000000","version": 2}	• Response:Status Code: 302 Response Header:Location: url (the url to which the client is redirected)	Success on Attached file / screenshots
	Downloads item with a valid access token and gets a specific version		• Input: {"code": "utest000000","version": 1}	• Response:Status Code: 302 Response Header:Location: url (the url to which the client is redirected)	Success on Attached file / screenshots
	Download the item with the invalid access token		• Input: {"code": "utest000000"}	• Response: To throw AccessTokenUnauthorized	Success on Attached file / screenshots
	Download Items that do not exist		• Input: {"code": "utest000001"}	• Response:To throw ItemNotFoundError	Success on Attached file / screenshots
	Download item that expires		• Input: {"code": "utest000002", "expiredAt": now}	• Response:Status Code: 302 Response Header:Location: url (the url to which the client is redirected)	Success on Attached file / screenshots

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?

Endpoint	Access	Authorization
/internal/*	service 2 service	api key
/cms/*	internet with whitelist IPs	cms user access token
/api/*	internet	user access token

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)

Discussion (0)

Recommended articles

Exploring Colyseus: Building Scalable Game Servers and Enhancing Team Performance

The rollercoaster ride of landing a programming job as a student