Software Engineering Handbook

This handbook is the primary guide for every engineer in Qiscus’ Delivery Division—whether you’ve just joined, are still onboarding, or have been here for years. It explains the standards, practices, and processes that keep our projects on track. You’ll also find links to more‑specialised handbooks when you need deeper guidance. Treat this document as your starting point whenever you spin up or work on a project.

Introduction

Our goal is to help you work effectively and efficiently. Everything here reflects hard‑won experience from real projects. For newcomers, the handbook shortens the learning curve so you can contribute productively as quickly as possible.

1. Project Initiation

Project initiation begins right after the internal kickoff session. Follow these steps to ensure a smooth launch.

1.1 System Design

First things first—always create a system‑flow diagram.
If your project integrates with multiple services, a sequence diagram is usually best.

• Use tools like draw.io or Mermaid.

• Involve the tech lead for review and sign‑off.

• Decide on the technology stack at this stage.

• Store the diagram (file/image/link) in both the project’s Notion space and the repository.

• Provide enough detail—the diagram is your ops team’s reference later.

Note: The system diagram must be finished before development starts.

1.2 Choosing the Tech Stack

Your stack should lean on the team’s dominant expertise and future maintenance capacity. Check the skill data in Members and confirm ops readiness.

Consult the Tech Radar—our living catalogue of technologies, each tagged with a confidence ring:

Everyone may contribute experience to the Tech Radar so we avoid repeating mistakes.

Access the Integration Delivery Tech Radar:
https://radar.thoughtworks.com/?documentId=https://docs.google.com/spreadsheets/d/1fYD5wHwG-lM–FkSVommwq8OrnqMD0JqSCVyePnTzwU/edit#gid=0

Exception:
If the client insists on specific technologies—especially when they’ll own the code—adapt the stack to their needs.

1.3 Task Breakdown: Tickets & Spent Time

Once the design is locked, break work into tickets in the project’s Notion board (the PM will create it—ask if you lack access). Map development and QA tasks to relevant user stories; if none exist, create tasks under the epic ticket.

Log your development activity and spent time as you go. Detailed instructions live here:
https://www.notion.so/How-to-Spent-Time-the-Task-e730ade6210244558d5823cc254ef5de

2. Role‑Based Development Practices

These guidelines keep coding style, architecture, testing, and implementation consistent across roles.

2.1 Backend

2.1.1 Key Repository Files

• Dockerfile – Defines the Docker image build. See the sample Dockerfile.

• bitbucket-pipelines.yml – CI/CD config for automatic build, test, deploy. Details in the Deployment section.

• README.md – How to run the app, environment docs, plus a link to the system design.

2.1.2 Logging

• Log every inbound request in JSON. Required fields: request_id, remote_ip, host, user_agent, method, path, body, status_code, latency, message, time.

• Multi‑tenant? Add app_code.

• Authenticated users? Log user info.

• Error logs must include request_id and link to the inbound log (e.g., use Go context with Zerolog).

• Outbound calls (to external APIs) should also be logged.

Inbound example

Outbound example

Tip: Log what matters—excessive logs cost storage and latency.

2.1.3 Health‑Check Endpoint

• GET /health is mandatory.

• Response example:

• Status codes: 200 (all healthy) or 500 (a component failed).

• Include only components relevant to your app.

Sample Go implementation: integration-go/internal/health

2.2 Frontend

2.2.1 Captcha

• Mandatory on every public form (login, register, etc.).

• We use Cloudflare Turnstile. Register your domain via the SRE team.

• Official docs: https://developers.cloudflare.com/turnstile/get-started/

3. Git Collaboration

Qiscus hosts code on Bitbucket. Always use your @qiscus email for work repositories.

3.1 Profile Setup

Keep personal and work Git profiles separate:
https://www.notion.so/Setup-Git-Profile-for-Work-7df882996d6e40449b2996595226fd0d

3.2 Branching Strategy (WIP)

A slimmed‑down Gitflow:

• main – Production‑ready, stable code.

• staging – Integration & testing (CI/CD attached).

• feat/* – Short‑lived feature branches.

Delivery flow

1. Sync staging with main after each production release.

2. Branch features off up‑to‑date staging.

3. When ready, open a PR into staging.

4. For production, PR staging into main.

3.3 Pull Requests

1. Feature → Staging
   PR needs at least one reviewer, passing tests, and resolved conflicts.

2. Staging → Main
   PR requires TL approval, complete features/docs, then deploy to prod.

4. Testing

Testing is non‑negotiable. We track test coverage via Bitbucket Pipelines.

4.1 Implementation

Golang

(built into the integration-go boilerplate)

Ruby on Rails

(RSpec + SimpleCov; adjust thresholds per project)

Want examples for other languages? Feel free to contribute!

5. Deployment

Guidelines for deploying services to staging and production.

5.1 Staging

• Create bitbucket‑pipelines.yml (see the sample).

• Pipeline must be enabled.

• Project naming: <repo‑name>-staging, branch staging.

• Need a DB/Redis? Ask in Slack:

  • DB: /initdb db_user db_name_stag

  • Redis: redis://redis-integration-stage.qiscus.io/0

Central Application

1. Add variables in the Variables tab.

2. Create an Application pointing at the Bitbucket image.

3. Set Neo DNS to a qiscus.io subdomain (no -stag suffix).

Configure once—future pushes to staging auto‑deploy.

Start/Stop Staging Servers

5.3 Production

• First release – handled by SRE.

  • DB request: /initdbprod db_user db_name

• Subsequent deploys:

  • Submit a Slack workflow with repo, command, port, etc.

  • Share env vars privately with SRE.

  • Update image tags via Jenkins (access through TL) and commit changes in integration-helm.

Detailed steps:

• Production Deployment High‑Level Flow

• How to deploy service to k8s

6. Handover

Once the app is live, the PM asks Ops to review the handover docs. Make sure they’re complete and detailed. Stay available for Q&A so knowledge transfer is smooth.

A few days later, we’ll hold a follow‑up meeting to discuss project details, evaluate development, and plan next steps.

Final Words

This handbook isn’t a one‑time read—keep it open as you deliver projects. Feel free to update it with examples or lessons you’ve learned.

Happy building, and best of luck on every project!