# Chapter 16 Lab: Solution Selection and Architecture Review

This lab supports Chapter 16 of **Data Engineering in Action**. It is the **Part IV architecture capstone**: you will evaluate technology options for TuranMart’s finance analytics platform, calculate a weighted selection matrix, and record the decision as an Architecture Decision Record (ADR).

## Learning Goals

By completing this lab, you will practice translating business requirements into decision criteria, comparing candidate architectures with explicit weights, validating a technology-selection matrix, recording assumptions in an ADR, and defining review triggers so that architecture decisions remain revisitable.

## Files

| Path | Purpose |
|---|---|
| `technology_selection_matrix.csv` | Starter weighted matrix comparing a managed warehouse, an open lakehouse, and a self-managed stack. |
| `architecture_decision_record.md` | Starter ADR for the TuranMart finance analytics platform decision. |
| `tests/validate_matrix.py` | Validation script that checks matrix shape, weights, score ranges, evidence requirements, and weighted totals. |
| `exercises/README.md` | Extension tasks for improving the matrix, adding POC evidence, and preparing an architecture review. |
| `../../../shared/solutions/ch16_solution_selection_architecture_review/solution.md` | Reference solution guide for instructors and self-study review. |

## Quick Start

From the repository root, run:

```bash
python shared/labs/ch16_solution_selection_architecture_review/tests/validate_matrix.py
```

The lab does not require Docker Compose because the artifact is an architecture decision package rather than a running service. The validation script reads the CSV file, confirms that the weights sum to 1.0, checks that scores are between 1 and 10, verifies that evidence requirements are not empty, and prints the weighted ranking.

## Suggested Workflow

Begin by reading the Chapter 16 TuranMart scenario. Then open `technology_selection_matrix.csv` and review the criteria, weights, and scores. Do not change all scores at once. Adjust one criterion at a time and add evidence in your notes: documentation, benchmark output, security review notes, cost-estimator screenshots, migration assumptions, or a short proof-of-concept result.

After each change, rerun the validation script. When the ranking stabilizes, update `architecture_decision_record.md`. The ADR should not merely repeat the winning score. It should explain the context, alternatives, evidence, consequences, owner assumptions, and review trigger. If your chosen option has a major weakness, document how TuranMart will mitigate it.

## Expected Output

A successful validation run prints output similar to the following:

```text
Weighted scores:
- managed_warehouse: 7.70
- open_lakehouse: 7.30
- self_managed_stack: 5.95
Recommended option under current weights: managed_warehouse
Validation passed: matrix shape, weights, scores, and evidence requirements are usable.
```

Your exact scores may differ after you revise the matrix. The important result is not that one specific option always wins. The important result is that the decision is traceable from requirements to evidence.

## Completion Checklist

| Check | Expected result |
|---|---|
| Matrix validates | The validation script exits successfully and prints weighted scores for all candidate options. |
| Criteria are measurable | Each criterion has a clear meaning and a practical evidence requirement. |
| Weights reflect priorities | The weights explain TuranMart’s business priorities rather than personal preference. |
| ADR is complete | The ADR includes context, drivers, alternatives, evidence, decision, consequences, and review trigger. |
| Decision is revisitable | The ADR names measurable conditions that should force re-evaluation. |

## Cleanup

No services are started and no generated files are required. If you create temporary notes or exported spreadsheets, keep them outside the repository unless your instructor asks you to submit them.

## Troubleshooting

| Symptom | Likely cause | Fix |
|---|---|---|
| `Weights must sum to 1.0` | A weight was added or changed without rebalancing the matrix. | Adjust weights until the total is exactly 1.0. |
| `Score must be between 1 and 10` | A score is blank, text, zero, or above 10. | Use numeric scores from 1 to 10 for every candidate and criterion. |
| `Evidence requirement is too vague` | The `evidence_required` field is empty or too short. | Write a concrete evidence requirement such as benchmark, security review, cost model, or POC result. |
| Winning option feels wrong | Weights may not reflect the real business priorities. | Discuss priorities with stakeholders, revise weights, and explain the change in the ADR. |