Skip to content

architecture-docs

Home for all AdAction Architectural documentation, including Architecture Decision Records (ADRs).

We will be managing our architectural artifacts in this repository. Changes will be made via pull requests and reviewed by the team. Currently, the repository contains only Architecture Decision Records (ADRs), but we can add other artifacts as needed.

Using this approach, an AdAction engineer will know exactly where they can look to understand the current architecture of our systems. If they should need a change, or wish to propose a new architecturally significant decision, we will have a clear process in place.

ADRs

We will document architecturally significant decisions using Architecture Decision Records (ADRs). An ADR is a short document that describes a significant decision along with its context, consequences, and alternatives. Architecturally significant decisions are those that affect the structure, nonfunctional characteristics, dependencies, interfaces, or construction techniques of a system(s). ADRs will be stored in a git repository and will be versioned.

Auto-Indexing Workflow

As part of the CICD Process we have a Github Action in place that automatically will update your ADR commit with the next number in the index. Additionally, this process will update the [Number] section at the top of your ADR to ensure it matches the document title.

The process for creating an ADR is as follows:

  1. Create a new ADR file in the appropriate directory, using the provided template named kebab-case-title.md.
  2. Fill out the ADR template
  3. Submit a pull request. Please title the PR with the following format: <title>
  4. The pull request will require one approval from a member of the owning team (auto-assigned via CODEOWNERS).

ADR directory structure

The ADRs are organized into subdirectories based on the area of the system they are related to. For example, ADRs related to the adgem system would be located in the adgem directory. If an ADR is related to multiple areas, it should be placed in the shared directory.

Bi-Weekly ADR Review

We hold bi-weekly ADR review meetings to discuss proposed and in-progress ADRs as a team. The process is async-first:

  1. Announcement: Two ADRs are announced in the #topic-adr-reviews Slack channel (pinned message)
  2. Async Review: Team members review the PRs and leave GitHub comments at least 24 hours before the meeting
  3. Meeting: We discuss open questions and work toward consensus
  4. Approval: Formal GitHub approvals happen after discussion (1 approval required)

This process is additive to the existing approval workflow—the meeting facilitates discussion but doesn't replace the formal PR approval requirement.

Building this documentation

This repo contains configuration for rendering the documentation using mkdocs. To view the documentation, you will need to install mkdocs and the necessary plugins. You can do this by running the following commands:

pip install -r requirements.txt

Once you have installed mkdocs, you can view the documentation by running the following command:

mkdocs serve

Static site

This main branch of this documentation is hosted via AWS Amplify: https://eng.adaction.com

PR versions are automatically hosted and the url can be found in the PR conversation.

Please reference the Architecture Docs entry in the Engineering 1Password vault for the Amplify credentials.