kschappell/py-dvt-ate
Public Access
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity

Initial project setup with documentation

Browse Source 
- Add project requirements document (01_requirements.md)
- Add technical specification (02_technical_specification.md)
- Add architecture decisions (03_architecture_decisions.md)
- Add README with project overview
- Add .gitignore for Python projects
This commit is contained in:
Kai Chappell
2025-01-15 10:17:15 +00:00
commit 2ca5144eaf
5 changed files with 2336 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

362
docs/01_requirements.md Normal file
View File

@@ -0,0 +1,362 @@
# Business Requirements Document
## ThermalATE: Coupled Physics DVT Simulation Platform
| Document ID | BRD-001 |
|-------------|---------|
| Version | 1.1.0 |
| Status | Draft |
| Author | Kai Chappell |
| Created | 2025-12-01 |
| Last Updated | 2025-12-01 |
---
## Purpose
This document defines **what** the ThermalATE system must do. It specifies the functional and non-functional requirements, constraints, and success criteria.
For **why** decisions were made, see `03_architecture_decisions.md`.
For **how** to implement the system, see `02_technical_specification.md`.
---
## Related Documents
| Document | Purpose |
|----------|---------|
| `01_requirements.md` | Defines **what** the system must do (this document) |
| `02_technical_specification.md` | Specifies **how** to implement the system |
| `03_architecture_decisions.md` | Explains **why** decisions were made |
---
## Table of Contents
1. [Executive Summary](#1-executive-summary)
2. [Problem Statement](#2-problem-statement)
3. [Business Objectives](#3-business-objectives)
4. [Stakeholders](#4-stakeholders)
5. [Scope](#5-scope)
6. [Functional Requirements](#6-functional-requirements)
7. [Non-Functional Requirements](#7-non-functional-requirements)
8. [Constraints](#8-constraints)
9. [Assumptions](#9-assumptions)
10. [Success Criteria](#10-success-criteria)
11. [Risks](#11-risks)
12. [Glossary](#12-glossary)
---
## 1. Executive Summary
### 1.1 Purpose
ThermalATE is a coupled-physics Device Validation Test (DVT) simulation platform that enables engineers to develop, validate, and debug characterisation test sequences without physical access to laboratory equipment.
### 1.2 Background
DVT engineers require access to expensive Automated Test Equipment (ATE) to develop and validate characterisation algorithms. Physical equipment is a shared resource with limited availability, creating bottlenecks in the development process.
### 1.3 Proposed Solution
A software simulation environment that accurately models the physical coupling between thermal and electrical domains, allowing complete test sequence development and validation without hardware access.
---
## 2. Problem Statement
### 2.1 Current Challenges
| Challenge | Impact |
|-----------|--------|
| **Limited Equipment Access** | ATE racks cost $100k+ and are shared resources; engineers must schedule lab time |
| **Slow Development Iteration** | Cannot iterate on test algorithms without physical equipment reservation |
| **Difficult Edge Case Testing** | Testing failure modes or boundary conditions risks damaging equipment |
| **Training Barriers** | New engineers cannot practise without supervision on expensive equipment |
| **Remote Work Limitations** | Engineers cannot develop tests without physical lab presence |
### 2.2 Gap Analysis
| Need | Current State | Desired State |
|------|---------------|---------------|
| Algorithm Development | Requires physical equipment | Fully offline development |
| Thermal-Electrical Coupling | Not modelled in simple mocks | Realistic coupled physics |
| Hardware Transition | Separate code for simulation vs real | Single codebase, configuration-driven |
| Test Validation | Only possible in lab | Complete validation before lab time |
---
## 3. Business Objectives
### 3.1 Primary Objectives
| ID | Objective | Measurable Outcome |
|----|-----------|-------------------|
| BO-1 | Enable offline DVT algorithm development | Engineers can develop complete characterisation tests without equipment access |
| BO-2 | Reduce equipment contention | Test code validated before consuming lab time |
| BO-3 | Demonstrate professional software engineering | Portfolio-quality project following industry best practices |
### 3.2 Secondary Objectives
| ID | Objective | Measurable Outcome |
|----|-----------|-------------------|
| BO-4 | Provide training platform | Safe environment for learning ATE concepts |
| BO-5 | Enable remote development | Full DVT development capability without lab presence |
---
## 4. Stakeholders
| Stakeholder | Role | Interest |
|-------------|------|----------|
| DVT Engineer (Primary User) | Develops characterisation tests | Needs realistic simulation for algorithm validation |
| Test Manager | Oversees test development | Wants reduced equipment contention, faster delivery |
| New Engineers | Learning ATE workflows | Needs safe practice environment |
| Portfolio Reviewer | Evaluates project quality | Assesses software engineering competence |
---
## 5. Scope
### 5.1 In Scope
| Category | Items |
|----------|-------|
| **Simulated Instruments** | Thermal Chamber, Programmable Power Supply, Digital Multimeter |
| **DUT Models** | Voltage Regulator (LDO) with thermal-electrical coupling |
| **Test Types** | Temperature Coefficient characterisation, Load Regulation |
| **User Interfaces** | Command-line interface, Streamlit dashboard, Programmatic API |
| **Data Management** | Test result persistence, Data export |
| **Reporting** | Automated test reports (future phase) |
### 5.2 Out of Scope
| Category | Items | Rationale |
|----------|-------|-----------|
| Additional Instruments | Oscilloscope, Signal Generator | Future phase |
| Additional DUT Models | Op-Amp, ADC, MOSFET | Future phase |
| Multi-user Operation | Concurrent users, access control | Not required for portfolio |
| Cloud Deployment | Hosted service | Local execution sufficient |
| Legacy Protocols | GPIB, USB-TMC hardware | Focus on TCP/IP simulation |
### 5.3 Boundaries
The system SHALL:
- Operate as a standalone local application
- Simulate instrument behaviour, not replicate specific vendor implementations
- Model physics at a level sufficient for algorithm validation, not device design
---
## 6. Functional Requirements
### 6.1 Physics Simulation
| ID | Requirement | Priority |
|----|-------------|----------|
| FR-PS-1 | The system SHALL simulate thermal chamber temperature control with realistic ramp and settling behaviour | Must |
| FR-PS-2 | The system SHALL model thermal coupling between chamber ambient and DUT case temperature | Must |
| FR-PS-3 | The system SHALL model DUT self-heating based on power dissipation | Must |
| FR-PS-4 | The system SHALL calculate DUT junction temperature from case temperature and thermal resistance | Must |
| FR-PS-5 | The system SHALL compute DUT electrical parameters as functions of junction temperature | Must |
| FR-PS-6 | The system SHALL update physics state at a rate sufficient for realistic transient behaviour | Must |
| FR-PS-7 | The system SHALL model thermal time constants for chamber and DUT thermal mass | Should |
### 6.2 Instrument Simulation
| ID | Requirement | Priority |
|----|-------------|----------|
| FR-IS-1 | The system SHALL provide a simulated Thermal Chamber with temperature setpoint and readback | Must |
| FR-IS-2 | The system SHALL provide a simulated Power Supply with voltage/current control and measurement | Must |
| FR-IS-3 | The system SHALL provide a simulated Multimeter with DC voltage measurement | Must |
| FR-IS-4 | All simulated instruments SHALL respond to industry-standard SCPI commands | Must |
| FR-IS-5 | Instruments SHALL communicate over TCP/IP network sockets | Must |
| FR-IS-6 | Instruments SHALL maintain state between commands within a session | Must |
| FR-IS-7 | Instruments SHALL return measurement values derived from the physics simulation | Must |
| FR-IS-8 | Instruments SHALL simulate realistic timing (settling, acquisition delays) | Should |
### 6.3 Hardware Abstraction
| ID | Requirement | Priority |
|----|-------------|----------|
| FR-HA-1 | The system SHALL provide abstract interfaces for each instrument type | Must |
| FR-HA-2 | Test code SHALL interact only with abstract interfaces, not concrete implementations | Must |
| FR-HA-3 | The system SHALL support swapping between simulated and real instruments via configuration | Must |
| FR-HA-4 | The abstraction layer SHALL not expose simulation-specific or hardware-specific details | Must |
### 6.4 Test Execution
| ID | Requirement | Priority |
|----|-------------|----------|
| FR-TE-1 | The system SHALL support defining multi-step test sequences | Must |
| FR-TE-2 | The system SHALL execute test sequences with proper instrument coordination | Must |
| FR-TE-3 | The system SHALL log all measurements during test execution | Must |
| FR-TE-4 | The system SHALL evaluate measurements against defined limits | Must |
| FR-TE-5 | The system SHALL determine overall pass/fail status for tests | Must |
| FR-TE-6 | The system SHALL support Temperature Coefficient characterisation test | Must |
| FR-TE-7 | The system SHALL support Load Regulation vs Temperature test | Should |
### 6.5 Data Management
| ID | Requirement | Priority |
|----|-------------|----------|
| FR-DM-1 | The system SHALL persist test run metadata (test name, timestamp, status) | Must |
| FR-DM-2 | The system SHALL persist all measurements with timestamps and conditions | Must |
| FR-DM-3 | The system SHALL persist calculated results with pass/fail status | Must |
| FR-DM-4 | The system SHALL support querying historical test results | Should |
| FR-DM-5 | The system SHALL support exporting data in common formats (CSV) | Should |
### 6.6 Reporting
| ID | Requirement | Priority |
|----|-------------|----------|
| FR-RP-1 | The system SHALL generate test reports containing results and pass/fail status | Could |
| FR-RP-2 | Reports SHALL include data visualisation (charts/graphs) | Could |
| FR-RP-3 | Reports SHALL be exportable in portable format (PDF or HTML) | Could |
### 6.7 User Interface
| ID | Requirement | Priority |
|----|-------------|----------|
| FR-UI-1 | The system SHALL provide a command-line interface for test execution | Must |
| FR-UI-2 | The system SHALL provide a programmatic API for integration | Must |
| FR-UI-3 | The system SHALL provide a Streamlit dashboard for real-time monitoring | Should |
| FR-UI-4 | Real-time instrument status SHALL be observable during test execution | Should |
---
## 7. Non-Functional Requirements
### 7.1 Performance
| ID | Requirement | Metric |
|----|-------------|--------|
| NFR-P-1 | Physics simulation SHALL run in real-time or faster | Update rate ≥ 100 Hz |
| NFR-P-2 | Instrument command latency SHALL be negligible | < 50 ms round-trip (localhost) |
| NFR-P-3 | Data logging SHALL not impact test execution | No dropped measurements |
### 7.2 Reliability
| ID | Requirement | Metric |
|----|-------------|--------|
| NFR-R-1 | System SHALL handle instrument communication errors gracefully | Clear error messages, no crashes |
| NFR-R-2 | Data SHALL be persisted before system exit | No data loss on normal shutdown |
| NFR-R-3 | System SHALL recover from transient connection failures | Auto-reconnect capability |
### 7.3 Maintainability
| ID | Requirement | Metric |
|----|-------------|--------|
| NFR-M-1 | Code SHALL follow consistent style and formatting | Automated linting passes |
| NFR-M-2 | Public interfaces SHALL be documented | All public APIs have docstrings |
| NFR-M-3 | Code SHALL have automated test coverage | ≥ 80% coverage on core modules |
| NFR-M-4 | Architecture SHALL support adding new instruments without modifying existing code | Open/closed principle demonstrated |
| NFR-M-5 | Architecture SHALL support adding new DUT models without modifying physics engine | Open/closed principle demonstrated |
### 7.4 Portability
| ID | Requirement | Metric |
|----|-------------|--------|
| NFR-PT-1 | System SHALL run on Windows 10+ | Tested and documented |
| NFR-PT-2 | System SHALL run on Linux | Tested and documented |
| NFR-PT-3 | System SHALL require only standard package manager installation | pip install sufficient |
### 7.5 Usability
| ID | Requirement | Metric |
|----|-------------|--------|
| NFR-U-1 | System SHALL start with a single command | Documented quick-start |
| NFR-U-2 | Error messages SHALL clearly indicate the problem and suggested resolution | Actionable error messages |
| NFR-U-3 | Configuration SHALL use human-readable format | YAML or similar |
---
## 8. Constraints
### 8.1 Technical Constraints
| ID | Constraint | Rationale |
|----|------------|-----------|
| C-T-1 | Implementation SHALL be 100% Python | Target role alignment; industry standard for test automation |
| C-T-2 | System SHALL not require external service dependencies (database servers, message brokers) | Simplify deployment; portfolio reviewability |
| C-T-3 | All dependencies SHALL be open-source | Avoid licensing issues |
| C-T-4 | System SHALL run without requiring physical instruments | Core purpose of the project |
### 8.2 Project Constraints
| ID | Constraint | Rationale |
|----|------------|-----------|
| C-P-1 | Single developer | Portfolio project |
| C-P-2 | No budget for commercial tools or services | Personal project |
---
## 9. Assumptions
| ID | Assumption | Impact if Invalid |
|----|------------|-------------------|
| A-1 | Users have Python 3.11+ installed | Must document installation requirements |
| A-2 | Users have basic familiarity with ATE concepts | May need to add tutorial documentation |
| A-3 | Localhost network performance is sufficient | May need to optimise for slower systems |
| A-4 | Single-user operation is acceptable for MVP | Multi-user would require significant redesign |
| A-5 | Simplified physics models are acceptable for algorithm validation | May need to increase model fidelity |
---
## 10. Success Criteria
### 10.1 Minimum Viable Product (MVP)
The project is successful if:
| ID | Criterion | Verification Method |
|----|-----------|---------------------|
| SC-1 | Can execute a complete Temperature Coefficient characterisation test against simulated instruments | End-to-end test demonstration |
| SC-2 | Physics coupling is evident: DUT self-heating affects measurements | Comparison of low-power vs high-power test results |
| SC-3 | Same test code runs against simulated and real instruments via configuration change | Demonstrate with PyVISA backend (if hardware available) or mock |
| SC-4 | Test results are persisted and retrievable | Query historical results |
| SC-5 | Code follows SOLID principles with clear module boundaries | Architecture review |
| SC-6 | Core modules have ≥ 80% test coverage | Coverage report |
### 10.2 Full Project Success
| ID | Criterion | Verification Method |
|----|-----------|---------------------|
| SC-7 | Streamlit dashboard provides real-time instrument visualisation | Dashboard demonstration |
| SC-8 | System deployable with single command | Docker Compose demonstration |
| SC-9 | Complete documentation (README, architecture, API) | Documentation review |
| SC-10 | Demonstrates portfolio-quality engineering | External code review |
---
## 11. Risks
| ID | Risk | Probability | Impact | Mitigation |
|----|------|-------------|--------|------------|
| R-1 | Physics model too simplistic for realistic behaviour | Medium | High | Research real component datasheets; validate against published specifications |
| R-2 | Scope creep delays completion | High | Medium | Strict MVP definition; defer features to future phases |
| R-3 | SCPI implementation incompatible with real instruments | Low | Medium | Reference IVI Foundation standards |
| R-4 | Over-engineering delays delivery | Medium | Medium | Focus on working software over architectural perfection |
| R-5 | UI development consumes excessive time | Medium | High | CLI-first approach; Streamlit for rapid iteration |
---
## 12. Glossary
| Term | Definition |
|------|------------|
| **ATE** | Automated Test Equipment - systems for testing electronic devices |
| **Characterisation** | Process of measuring device parameters across operating conditions |
| **DUT** | Device Under Test - the component being characterised |
| **DVT** | Design Validation Test - testing to verify design meets specifications |
| **HAL** | Hardware Abstraction Layer - interface isolating code from hardware specifics |
| **LDO** | Low Dropout Regulator - type of linear voltage regulator |
| **NPLC** | Number of Power Line Cycles - integration time unit for DMMs |
| **SCPI** | Standard Commands for Programmable Instruments - IEEE 488.2 command syntax |
| **TempCo** | Temperature Coefficient - rate of parameter change with temperature (ppm/°C) |
| **Thermal Coupling** | Physical interaction between thermal and electrical domains |
| **θ (theta)** | Thermal resistance, measured in °C/W |
---
**End of Business Requirements Document**

1674
docs/02_technical_specification.md Normal file
View File

File diff suppressed because it is too large Load Diff

189
docs/03_architecture_decisions.md Normal file
View File

@@ -0,0 +1,189 @@
# Architecture Decision Record
## ThermalATE: Technical Architecture Decisions
| Document ID | ARD-001 |
|-------------|---------|
| Version | 1.1.0 |
| Status | Draft |
| Author | Kai Chappell |
| Created | 2025-12-01 |
| Last Updated | 2025-12-01 |
---
## Purpose
This document captures the **rationale** behind architectural decisions. It explains **why** certain approaches were chosen over alternatives.
For **what** the system must do, see `01_requirements.md`.
For **how** to implement the system, see `02_technical_specification.md`.
---
## Related Documents
| Document | Purpose |
|----------|---------|
| `01_requirements.md` | Defines **what** the system must do |
| `02_technical_specification.md` | Specifies **how** to implement the system |
| `03_architecture_decisions.md` | Explains **why** decisions were made (this document) |
---
## Table of Contents
1. [Guiding Principles](#1-guiding-principles)
2. [Decision Log](#2-decision-log)
---
## 1. Guiding Principles
These principles guided all architectural decisions:
| Principle | Rationale |
|-----------|-----------|
| **Single Responsibility** | Reduces coupling; each module changes for one reason only |
| **Dependency Inversion** | Enables testing and hardware swapping without code changes |
| **Explicit Dependencies** | Makes code predictable; no hidden global state |
| **Fail Fast** | Problems surface immediately rather than propagating |
| **Configuration over Code** | Runtime behaviour changes without recompilation |
| **Engineering Efficiency** | Prioritise development velocity using appropriate tools |
---
## 2. Decision Log
### ADR-001: Programming Language
| Aspect | Content |
|--------|---------|
| **Context** | Need to choose primary implementation language for a DVT automation platform |
| **Decision** | Python 3.11+ |
| **Why This Choice** | Python is the industry standard for test automation. Hiring managers for DVT roles expect Python proficiency. The ecosystem (NumPy, SciPy, PyVISA) directly supports the problem domain. A single language reduces context-switching and demonstrates depth over breadth. |
| **Trade-offs Accepted** | Slower execution than compiled languages (acceptable for 100Hz simulation). Dynamic typing requires discipline (mitigated with type hints and mypy). |
| **Alternatives Rejected** | LabVIEW (proprietary, not demonstrable in portfolio), C++ (slower development velocity), TypeScript (not standard in ATE domain) |
---
### ADR-002: Frontend Approach
| Aspect | Content |
|--------|---------|
| **Context** | Need user interface for test execution and monitoring. Must balance effort against target role (DVT/Backend, not Frontend). Must demonstrate engineering efficiency. |
| **Decision** | CLI-first with Streamlit dashboard |
| **Why This Choice** | CLI demonstrates core functionality without UI overhead. Streamlit enables rapid iteration on dashboard UI using pure Python—no JavaScript, CSS, or complex state management required. This demonstrates 'Engineering Efficiency': building effective internal tools quickly using appropriate technology. Real ATE tools at hardware companies are often CLI or simple Python GUIs, not React SPAs. |
| **Trade-offs Accepted** | Streamlit has limitations for complex interactivity. Less customisable than React. Re-runs script on interaction (mitigated with caching). |
| **Alternatives Rejected** | React (wrong skill signal for DVT roles, major time investment, JavaScript required), Panel (more powerful but steeper learning curve, slower iteration), PyQt (higher complexity, dated appearance) |
---
### ADR-003: Data Persistence Strategy
| Aspect | Content |
|--------|---------|
| **Context** | Need to persist test metadata and high-frequency measurement data |
| **Decision** | SQLite for metadata + Parquet for time-series measurements |
| **Why This Choice** | SQLite requires no server process—the entire system remains self-contained. Parquet is columnar and optimised for analytical queries on measurement data. Both are file-based, making projects portable and easy to share. Standard library (sqlite3) and well-supported (PyArrow) tools demonstrate effective use of established technologies before reaching for external dependencies. |
| **Trade-offs Accepted** | Single-user only (acceptable for portfolio project). No real-time replication. Query capabilities limited to pandas/SQL without additional tools. |
| **Alternatives Rejected** | PostgreSQL (requires server, adds infrastructure complexity), InfluxDB (another service to manage), DuckDB (additional dependency not strictly necessary for single-user simulator) |
---
### ADR-004: Instrument Communication Protocol
| Aspect | Content |
|--------|---------|
| **Context** | Need protocol for test application to communicate with simulated instruments |
| **Decision** | SCPI over TCP/IP sockets |
| **Why This Choice** | SCPI is the industry standard for programmable instruments (IEEE 488.2). Using the real protocol means the same drivers work with real hardware. TCP/IP enables process separation and future network deployment. Demonstrates domain knowledge to reviewers. |
| **Trade-offs Accepted** | Must implement SCPI parser. Network overhead (negligible on localhost). |
| **Alternatives Rejected** | Direct function calls (wouldn't demonstrate real-world architecture), gRPC (not industry standard for instruments), REST API (not SCPI-compliant, wouldn't transfer to real hardware) |
---
### ADR-005: Process Architecture
| Aspect | Content |
|--------|---------|
| **Context** | Need to decide if physics simulation runs in-process or separately |
| **Decision** | Simulation server runs as separate process |
| **Why This Choice** | Mimics real hardware architecture where instruments are separate devices. Forces clean network boundaries that translate to real deployments. Enables Docker containerisation with proper service separation. The same test code works whether talking to simulation or real instruments over network. |
| **Trade-offs Accepted** | Process management complexity. Inter-process communication overhead. |
| **Alternatives Rejected** | In-process simulation (wouldn't demonstrate production architecture, wouldn't prove hardware abstraction works) |
---
### ADR-006: Hardware Abstraction Mechanism
| Aspect | Content |
|--------|---------|
| **Context** | Need to swap between simulated and real instruments without changing test code |
| **Decision** | Python Protocol classes (structural typing) with Factory pattern |
| **Why This Choice** | Protocols enable interface-based programming without inheritance coupling. Factory centralises the simulator-vs-real decision to configuration. No heavy DI framework needed—Python's simplicity is sufficient. Demonstrates understanding of SOLID principles and dependency injection. |
| **Trade-offs Accepted** | Manual wiring in factory (acceptable at this scale). Protocols require Python 3.8+. |
| **Alternatives Rejected** | Abstract Base Classes only (less flexible than Protocols), DI framework like dependency-injector (over-engineering for this scale), No abstraction (would couple test code to simulator) |
---
### ADR-007: Concurrency Model
| Aspect | Content |
|--------|---------|
| **Context** | Need to handle concurrent instrument connections and real-time physics updates |
| **Decision** | asyncio for simulation server; synchronous-first for test code |
| **Why This Choice** | Server must handle multiple simultaneous connections efficiently—asyncio is Python's standard solution. Test code is inherently sequential (set voltage, wait, measure), so forcing async everywhere adds complexity without benefit. Clear boundary at transport layer. |
| **Trade-offs Accepted** | Two patterns to understand. Must be careful about blocking calls in async context. |
| **Alternatives Rejected** | Threading everywhere (GIL limitations, harder to reason about), Full async in test code (unnecessary complexity, test sequences are sequential) |
---
### ADR-008: Configuration Format
| Aspect | Content |
|--------|---------|
| **Context** | Need human-readable, version-controllable configuration |
| **Decision** | YAML files validated with Pydantic |
| **Why This Choice** | YAML supports comments (unlike JSON), making configs self-documenting. Pydantic provides type-safe parsing with clear error messages. Configs can be version-controlled alongside code. |
| **Trade-offs Accepted** | YAML has some parsing quirks (Norway problem). Pydantic v2 has breaking changes from v1. |
| **Alternatives Rejected** | JSON (no comments), TOML (less common in Python data ecosystem), Environment variables only (not structured enough for complex config) |
---
### ADR-009: Testing Philosophy
| Aspect | Content |
|--------|---------|
| **Context** | Need automated testing strategy for quality assurance |
| **Decision** | pytest with dependency injection via fixtures; 80% coverage target on core modules |
| **Why This Choice** | pytest is the Python community standard. Fixtures align with DI pattern—inject mocks at test boundaries. 80% coverage balances thoroughness with pragmatism. Demonstrates professional engineering practices expected at senior level. |
| **Trade-offs Accepted** | Must design for testability from the start. Some integration tests require running simulation server. |
| **Alternatives Rejected** | No tests (unacceptable for portfolio demonstrating senior-level work), unittest (less ergonomic than pytest), 100% coverage target (diminishing returns, encourages testing trivial code) |
---
### ADR-010: Project Structure
| Aspect | Content |
|--------|---------|
| **Context** | Need to organise code for clarity and maintainability |
| **Decision** | Monorepo with src layout and package-per-concern |
| **Why This Choice** | Single repository simplifies development for a solo developer. Src layout is Python packaging best practice (prevents import confusion). Package-per-concern makes dependencies explicit and enforceable. |
| **Trade-offs Accepted** | Must configure editable installs for development. All code in one repo (acceptable at this scale). |
| **Alternatives Rejected** | Flat structure (poor for larger codebases), Multi-repo (overhead for single developer), Package-per-layer only (too coarse-grained) |
---
### ADR-011: Development Phasing Strategy
| Aspect | Content |
|--------|---------|
| **Context** | Need to prioritise features for efficient delivery of portfolio-quality project |
| **Decision** | Vertical Slice approach: deliver end-to-end functionality (Physics → HAL → Driver → UI) before adding horizontal features (reporting, API) |
| **Why This Choice** | A working "Virtual Lab Bench" demonstrates the core value proposition immediately. Vertical slices reduce integration risk—problems surface early. Defers low-value work (PDF formatting) until core is proven. Enables meaningful demos at every phase. |
| **Trade-offs Accepted** | Some infrastructure (reporting) delayed. May need refactoring when adding phases. |
| **Alternatives Rejected** | Horizontal layers first (delays integration, hides problems), Feature-complete phases (too long between demos), MVP without UI (harder to demonstrate value) |
---
**End of Architecture Decision Record**