Skip to main content
Design documents are detailed technical specifications that outline the architecture, implementation approach, and key decisions for significant features or system changes. They serve as a communication tool for gathering feedback and ensuring alignment before implementation begins.

​
Purpose

Design documents help us:
  • Think through complex problems systematically
  • Gather feedback from stakeholders early in the process
  • Document key architectural decisions for future reference
  • Ensure alignment across engineering teams
  • Reduce implementation risks by identifying edge cases upfront
  • Consider security implications of the change

​
Security considerations

Every design document includes a Security considerations section covering data flows, trust boundaries and data being stored. A design document (with this section) is required for changes that impact the data that Polar exposes or that change public APIs.

​
GitHub Integration

All design documents are version-controlled in this repository. Use GitHub’s commenting and review features available in Pull Requests to provide feedback on proposed designs. This ensures all discussions are captured and can be referenced later.