77 lines
2.5 KiB
Markdown
77 lines
2.5 KiB
Markdown
|
# Architecture Decision Records (ADRs)
|
||
|
|
|
||
|
|
This directory contains Architecture Decision Records (ADRs) for SYNTAXIS - significant architectural and design decisions, their rationale, and implications.
|
||
|
|
|
||
|
|
## What is an ADR?
|
||
|
|
|
||
|
|
An ADR documents a significant architectural decision, the reasoning behind it, and trade-offs considered. Each ADR:
|
||
|
|
- Describes a specific decision
|
||
|
|
- Explains the problem and context
|
||
|
|
- Lists alternatives considered
|
||
|
|
- States the decision and rationale
|
||
|
|
- Documents trade-offs and implications
|
||
|
|
|
||
|
|
## Index
|
||
|
|
|
||
|
|
### ADR-001: Wrapper Architecture Strategy
|
||
|
|
**Status**: DEPRECATED (See ADR-002 for deployment wrappers)
|
||
|
|
**Date**: 2025-11-17
|
||
|
|
|
||
|
|
~~Analyzes installation orchestrator wrappers (`provision.sh`). Deprecated in favor of ADR-002 which focuses on runtime deployment wrappers.~~
|
||
|
|
|
||
|
|
**Files**: [ADR-001-wrapper-architecture-strategy.md](./ADR-001-wrapper-architecture-strategy.md)
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
### ADR-002: Bundle Wrapper Deployment Architecture
|
||
|
|
**Status**: ACCEPTED
|
||
|
|
**Date**: 2025-11-17
|
||
|
|
|
||
|
|
Defines three-layer wrapper deployment for bundle installations:
|
||
|
|
1. **Bash Wrapper** (`~/.cargo/bin/syntaxis-cli`)
|
||
|
|
- Sets environment variables
|
||
|
|
- Calls NuShell wrapper
|
||
|
|
|
||
|
|
2. **NuShell Wrapper** (`~/.config/syntaxis/scripts/syntaxis-cli.nu`)
|
||
|
|
- Discovers configuration files
|
||
|
|
- Auto-injects `--config` path
|
||
|
|
- Calls actual binary
|
||
|
|
|
||
|
|
3. **Real Binary** (`~/.cargo/bin/syntaxis-cli.real`)
|
||
|
|
- Actual compiled executable
|
||
|
|
|
||
|
|
**Decision**: Bundle installations should create the same wrapper structure as development installations for consistent UX.
|
||
|
|
|
||
|
|
**Key Insight**: Users should NOT have to type `--config path` every time (frequent burden). Wrappers solve this.
|
||
|
|
|
||
|
|
**Files**: [ADR-002-bundle-wrapper-deployment.md](./ADR-002-bundle-wrapper-deployment.md)
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## How to Use These ADRs
|
||
|
|
|
||
|
|
1. **Read the Decision**: Start with "Decision" section
|
||
|
|
2. **Understand the Rationale**: See "Problem Statement" and analysis
|
||
|
|
3. **Review Trade-offs**: Consider both sides
|
||
|
|
4. **Check Status**: Is this PROPOSED, ACCEPTED, SUPERSEDED?
|
||
|
|
|
||
|
|
## Contributing
|
||
|
|
|
||
|
|
When proposing a new ADR:
|
||
|
|
1. Create `ADR-NNN-short-title.md` in this directory
|
||
|
|
2. Use template from existing ADRs
|
||
|
|
3. Include decision, rationale, trade-offs
|
||
|
|
4. Update this README with reference
|
||
|
|
|
||
|
|
## Decision Status Reference
|
||
|
|
|
||
|
|
- **PROPOSED**: Under review, not yet accepted
|
||
|
|
- **ACCEPTED**: Approved, implementation proceeding
|
||
|
|
- **IMPLEMENTED**: Completed and in production
|
||
|
|
- **SUPERSEDED**: Replaced by newer ADR (reference new one)
|
||
|
|
- **DEPRECATED**: No longer relevant
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
**SYNTAXIS** v0.1.0
|