Handbook

The single source of truth for engineering standards, patterns, and decisions at Torcue.

This repository contains no code — only Markdown documents that define how we build software. Every developer is expected to read the relevant sections before starting work and consult this repo when making architectural decisions.

Why This Exists

Without documented standards, every team makes different choices. This leads to inconsistent codebases, repeated debates, and knowledge that walks out the door when people leave. This repo fixes that by giving everyone a shared foundation.

  • New joiners get up to speed faster
  • Code reviews focus on logic, not style wars
  • Architectural decisions are preserved with their reasoning
  • Standards evolve through PRs, not Slack threads

Getting Started

If you're a new developer, start here:

  1. Read guidelines/general/naming-conventions.md
  2. Read the guidelines folder relevant to your domain (backend / frontend / mobile)
  3. Browse decisions/ to understand past architectural choices

How to Contribute

Everyone is encouraged to improve these docs. Follow the steps below.

Adding a new guideline or pattern

  1. Copy ./format/coding-guidelines.md into the appropriate folder
  2. Fill in all fields — especially Author, Owner, and Purpose
  3. Raise a Pull Request and assign at least one reviewer
  4. Once approved, it becomes the official standard

Adding a new Architecture Decision Record (ADR)

  1. Copy templates/adr-template.md into decisions/
  2. Name it with the next available number: 0003-your-decision-title.md
  3. Fill in Context, Options Considered, Decision, and Consequences
  4. Raise a Pull Request — ADRs require approval from a Tech Lead or Architect

Updating an existing document

  • For minor fixes (typos, broken links): raise a PR directly
  • For content changes (new rules, updated conventions): update the Changelog table inside the document with your name, date, and a summary of what changed
  • Never edit a previous changelog entry — always add a new row

⚠️ Do not raise PRs without updating the Version Number field and Changelog in the document.

Document Status

Every document carries a status badge in its header:

Status Meaning
Active Current standard — follow this
Draft Work in progress — do not follow yet
Under Review Being revised — check with the owner before using
Deprecated No longer valid — a newer document supersedes it

Running Repo Locally

To preview the handbook as a website on your local machine, follow these steps:

  1. Initialize Environment:
            python3 -m venv venv
            source venv/bin/activate
  1. Install Dependencies:
            pip install mkdocs mkdocs-shadcn
  1. Spin Up the Server:
            mkdocs serve

The site will be available at http://127.0.0.1:8000 once the server starts.

Ownership

Area Owner Contact
General Guidelines [Vineetha S] [Tibin Sunny]
Backend [Vineetha S] [Rafath KP]
Frontend [Vineetha S] [Rafath KP]
Mobile [Vineetha S] [Appu S Palathinkal]
DevOps [Vineetha S] [Tibin Sunny]
This README [Tibin Sunny]

Questions & Feedback

  • Found something wrong? Raise a PR with the fix.No need to update the version
  • Disagree with a standard? Open a discussion in the PR or raise it with the document owner before deviating.
  • Something missing? Create a new document using the template and raise a PR.

Do not discuss or decide standards in Slack and then fail to document them here. If it was worth discussing, it's worth writing down.

This repository is maintained by the Architectural team a Torcue. All standards are living documents — review them periodically and keep them current.