Skip to main content
A design document explains a feature, the architecture, and the security decisions before we build it. We review design documents in a pull request. After we ship the feature, the related design document become obsolete. Cross feature decisions should be recorded on ADR.

​
When to write one

Write a design document before the code pull request if any of this is true:
  • Polar will store or process a set of new data (personal data, money information, or secrets).
  • Considerable changes on authentication or authorization.
  • We add a new architectural change (new database, workers, etc.)
  • A new third-party tool will see merchant or customer data.
Do not write a new design document for:
  • New API endpoints that expose the same data and uses the same auth rules as other ones. A pull request is enough.
  • Bug fixes
  • UI changes

​
When we review security

We run security reviews when a change touches any of the things mentioned above. We do not run them on a fixed schedule. Filling in Security considerations in the design document is that review.

​
How to add a design document

  1. Copy template.mdx. Name the file with dashes, like my-feature.mdx.
  2. Fill the template.
  3. Add the page to the Design Documents group in handbook/docs.json.
  4. Open a pull request. Leave comments on that pull request.