# AD0000 - Architecture Design Intent

### Author: Angus Forrest
### Date: 29-10-2025

## Context

Creating a usable integrator package for the astronomy community is the most ambitious project that I have attempted to date.
For the best possible success, documentation of design decisions throughout the development process seems a reasonable goal.
This especially true when this project is viewed through the lens of a learning opportunity.
To better understand the success and failures of decisions it is important to have thoughts commited to paper so that revisionism can be minimsed.
We can view this through the model of state of mind, where there could be four main category of outcomes for design decisions:
intended successes, unintended success, intended failures, and unintended failures.
- Intended successes, are the decisions to be strived for as they show mastery in intention leading to execution of an idea. If a design decision leads to this outcome, a post-mortem can analyse the key components of the implementation and clarity of design that lead to this outcome as well as the specific contributions of collaborators that lead to positive success.
- Unintended successes, are decisions that workout in spite of false impressions or incorrect reasoning which did not derail the decision from turning out to be the correct one in the end. A post-mortem could focus on the specific lack of judgement in the planning phase or the overlooked components that turned out to have an oversized impact on the result of the decision.
- Intended failures, are unfortunately the worst outcome and thus require the most amount of analysis when they occur. These usually occur when background context was misidentified. Post-mortems should focus on the specific actions that led to incorrect understanding from forming and how support can be provided to individuals in decision making roles throughout the design implementation process.
- unintended failures, can only be managed by identifying their occurence early and pivoting or changing the decision. unintended failure can also be thought of as failure due to external reasons or due to reasons outside of the scope of the project. Where as intended failures are failures that are a natural result of misestimations, lack of skill or lack of research.
All these categories are have blurry boundaries and thus decisions may not neatly fall into a single category and therefore post-mortems of architectural decisions should be broken down into major events in the timeline and be evaluate individually and then as collectively to determine leasons that can be learnt and carried into future design decisions.
## Alternatives

The strongest alternative to this model is a more informal method of architectural decision discussions where the collaborators create a design document together inside of a meeting and then update and close the document once the technicial implementation is complete.
The argument for the chosen implementation over this informal method is that written documentation can be used as a basis for published works and that the skill of communicating technical ideas through a written medium is a useful skill that can be developed more effectively with complete written tickets compared to general meeting minutes notes.  


## Implementation

The creation of docs/arch folder within the astrodrift repository and the plan for additions and signoff of architecture decision tickets.
